# AllenHark Relay — Customer Integration Guide ## Introduction AllenHark Relay is a Solana transaction relay designed for high-frequency traders, market makers, and automated systems. By bypassing the public mempool and routing directly to leaders, we offer low-latency delivery and MEV protection. **Key Features:** * **0-Slot Execution**: Transactions land in the same slot they are sent. * **0-Hop Delivery**: Direct connections to current and upcoming leaders. * **MEV Protection**: Private transaction routing prevents front-running. * **QUIC & HTTPS Support**: Optimized endpoints for every use case. --- ## Connectivity We provide three submission modes: QUIC, WebSocket, and HTTPS. **QUIC is strongly recommended** for production use — the connection is established once and reused, so each transaction costs one stream write with no handshake. ### 1. QUIC Endpoints (Recommended) Use the IP directly; port `4433` on every region. * **Frankfurt (primary):** `88.216.36.108:4433` * **Amsterdam:** `84.32.104.38:4433` * **New York:** `74.214.174.50:4433` * **Tokyo:** `88.216.188.28:4433` * **Protocol:** QUIC (UDP) * **Features:** Persistent connections, multiplexing, 0-RTT resumption. The old Frankfurt QUIC address 84.32.223.83:4433 is no longer the QUIC endpoint: use 88.216.36.108:4433 for QUIC, and the hostnames (fra.relay.allenhark.com / relay.allenhark.com) for HTTPS and WebSocket. ShredStream's endpoint is 185.191.117.89:9090. endpoint is `88.216.36.108:4433`; the ShredStream shared gRPC endpoint is `185.191.117.89:9090`. ### 2. WebSocket Endpoints * **URL:** `wss://{fra|ams|ny|tyo}.relay.allenhark.com/v1/stream/tx` (and `/v1/stream/bundle`) * One handshake at connect, then one frame per transaction. ### 3. HTTPS Endpoints (Simple integration) * **URL:** `https://{fra|ams|ny|tyo}.relay.allenhark.com/v1/sendTx` — `relay.allenhark.com` is an alias for Frankfurt. * **Method:** `POST` * **Latency:** single-digit milliseconds when you're near a region, tens of milliseconds cross-region — use QUIC or WebSocket when latency matters. --- ## Authentication All requests require an API Key — there is no anonymous submission path. * **HTTPS:** `x-api-key: YOUR_API_KEY` header, or `?api-key=YOUR_API_KEY` query parameter * **WebSocket:** the same header at the upgrade, or `?api-key=` on the URL * **QUIC:** `api-key: YOUR_API_KEY\n` as the first line of the stream Keys have the form `ak_`. Get one from the Relay tab in the console. --- ## Tip Requirements The tip **is** the price of the relay, and it is not a charge we bill you. You pay it yourself, inside the transaction you are already sending: a **top-level `SystemProgram.transfer`** to one of the tip wallets below. No invoice, no card, no monthly minimum. **Minimum Tip:** `0.001 SOL` (1,000,000 lamports) The tip wallet must be in the transaction's **static account keys**. Versioned (v0) transactions with address lookup tables are fully supported as long as that holds — if the tip wallet is only reachable through a lookup table the transaction is rejected with `tip_hidden_in_alt`. **Tip Wallets (Select one randomly per transaction):** ``` hark1zxc5Rz3K8Kquz79WPWFEgNCFeJnsMJ16f22uNP harkm2BTWxZuszoNpZnfe84jRbQTg6KGHaQBmWzDGQQ hark4CwtTnN2y9FaxjcFBAJdJqQrpouu5pgEixfqdEz harkoJfnM6dxrJydx5eVmDVwAgwC94KbhuxF69UbXwP hark6hUDUTekc1DGxWdJcuyDZwf6pJdCxd4SXAVtta6 harkoTvFpKSrEQduYrNHXCurARVT19Ud3BnFhVxabos harkEpXoJv5qVzHaN7HSuUAd6PHjyMcFMcDYBMDJCEQ harkyXDdZSoJGyCxa24t2QXx1poPyp8YfghbtpzGSzK harkR2YJ4Dpt4UDJTcBirjnSPBhNpQFcoFkNpCkVqNk harkRBygM8pHYe4K8eBjfxyEX19oJn3LepFjvNbLbyi harkYFxB6DuUFNwDLvA5CQ66KpfRvFgUoVypMagNcmd ``` --- ## Integration Examples ### 1. JavaScript / TypeScript (HTTPS) ```javascript // Using fetch for HTTPS submission const response = await fetch("https://relay.allenhark.com/v1/sendTx", { method: "POST", headers: { "Content-Type": "application/json", "x-api-key": "YOUR_API_KEY" }, body: JSON.stringify({ tx: "BASE64_ENCODED_TRANSACTION_STRING", // Your signed transaction simulate: false // Must be false }) }); const result = await response.json(); console.log(result); // Success: { "status": "accepted", "request_id": "..." } // Error: { "status": "error", "code": "tip_missing", "message": "..." } ``` ### 2. Rust (QUIC via Quinn) ```rust use quinn::{ClientConfig, Endpoint}; use rustls::RootCertStore; use std::sync::Arc; #[tokio::main] async fn main() -> Result<(), Box> { // 1. Configure TLS (System Roots) let mut roots = RootCertStore::empty(); roots.add_trust_anchors(webpki_roots::TLS_SERVER_ROOTS.iter().map(|ta| { rustls::OwnedTrustAnchor::from_subject_spki_name_constraints( ta.subject, ta.spki, ta.name_constraints, ) })); let client_config = ClientConfig::with_root_certificates(roots); // 2. Connect let mut endpoint = Endpoint::client("0.0.0.0:0".parse()?)?; endpoint.set_default_client_config(client_config); let conn = endpoint.connect("88.216.36.108:4433".parse()?, "relay.allenhark.com")?.await?; // 3. Open Stream & Send let (mut send, mut recv) = conn.open_bi().await?; // Protocol: API Key line -> JSON Payload send.write_all(b"api-key: YOUR_API_KEY\n").await?; let payload = serde_json::json!({ "tx": "BASE64_ENCODED_TX", "simulate": false }); send.write_all(&serde_json::to_vec(&payload)?).await?; send.finish().await?; // 4. Read Response let response = recv.read_to_end(4096).await?; println!("Response: {}", String::from_utf8_lossy(&response)); Ok(()) } ``` --- ## Response Codes | Status | Code | Meaning | |:-------|:-----|:--------| | `200 OK` | `accepted` | Transaction received and queued for broadcast. | | `400 Bad Request` | `tip_missing` | No transfer to an AllenHark wallet found. | | `400 Bad Request` | `tip_insufficient` | Tip is below 0.001 SOL. | | `400 Bad Request` | `simulate_forbidden` | `simulate` parameter was set to `true`. | | `401 Unauthorized` | `invalid_api_key` | API Key is missing or invalid. Note: unknown keys are currently reported as `rate_limit_exceeded`; `invalid_api_key` is being rolled out. | | `429 Too Many Requests` | `rate_limit_exceeded`| You have exceeded your plan's limits. | --- ## Detailed Q&A ### Troubleshooting & Common Issues **Q: Why am I receiving a `tip_missing` error?** A: This error occurs when our validation engine cannot find a transfer instruction to one of our designated tip wallets in your transaction. * **Check 1:** Ensure you are using the list of wallets provided above. Using an old or incorrect wallet address will fail validation. * **Check 2:** Verify the transfer amount. It must be at least 1,000,000 lamports (0.001 SOL). Values like 0.0009 SOL will trigger `tip_insufficient`. * **Check 3:** Ensure the transfer instruction is at the top level of the transaction, not nested deeply in a CPI (Cross-Program Invocation) where static analysis might miss it. **Q: Can I simulate transactions?** A: **No.** The `simulate` flag is explicitly forbidden (`simulate_forbidden`). AllenHark Relay is a pure propagation engine. For simulation, please use a standard RPC provider like Helius or QuickNode. We optimize purely for "fire-and-forget" speed. **Q: My transactions are accepted but not landing. Why?** A: If you receive a `200 OK` with `accepted`, we have successfully broadcast your transaction to the current and next 4 leaders. If it doesn't land: 1. **Blockhash Expired:** Your transaction might have been built with an old blockhash. Use our **gRPC Service** or a fast RPC to get the latest blockhash. 2. **Slippage/State:** The on-chain state might have changed (e.g., the pool price moved), causing the transaction to fail execution on the validator. 3. **Tip Too Low:** During extreme congestion, 0.001 SOL might not be enough to incentivize the leader. Try increasing your tip to 0.002–0.005 SOL. ### Performance & Limits **Q: What is the rate limit?** A: **10 requests per second per API key** by default. * **Scope:** applied per API key, not per IP. * **Exceeding:** You will receive `429 Too Many Requests` with `rate_limit_exceeded`. * **Upgrades:** Contact us for a higher limit based on your volume. Dedicated Relay ($315/month) raises limits and adds tip-free sends from whitelisted wallets. **Q: Is QUIC really faster than HTTPS?** A: Structurally, yes. * **HTTPS:** Requires a TCP handshake + TLS handshake for every new connection (~3-4 round trips) unless you keep it alive. * **QUIC:** Uses a persistent UDP connection with 0-RTT resumption. Once connected, sending a transaction is just one stream write. * **Recommendation:** Use HTTPS for testing/scripts, but **use QUIC or WebSocket** for live trading bots. ### Security **Q: What if my API Key is compromised?** A: Contact support via Discord immediately. We can rotate your key instantly without requiring a code deploy on your end if you load keys from env vars. * **Best Practice:** Never commit keys to GitHub. Use `.env` files. **Q: Do you front-run my transactions?** A: **Absolutely not.** The core value proposition of AllenHark Relay is **MEV protection**. We route your transaction solely to the leader via private TPU ports. It is never broadcast to the public gossip network until it lands in a block. --- ## Performance Tuning * **Co-Location**: The network hop to the relay is usually the biggest latency term left. See https://allenhark.com/co-location for available sites. * **Keep-Alive**: Reuse QUIC connections. Set keep-alive pings to 3s to prevent timeouts. * **Pre-flight**: Skip pre-flight checks in your client to save time; validation happens server-side.