Gateway reference
Connection
This page covers how a desk opens, keeps and reopens its gateway sockets: the handshake, the bearer header, asset aliases, the heartbeat and reconnects.
Sockets a desk opens
A desk opens one /maker command socket and one feed socket per collateral it quotes. For a JitoSOL-only desk that is two sockets:
| Socket | Path | You send | You receive |
|---|---|---|---|
| Command | /maker | bid_intent, quote, award_decline, rfq_note | Replies, award |
| Feed | /rfqs/0x43127405c3191a0b63a5f3d845f616ffea348c68 | Nothing | rfq events |
GatewayClient opens /maker first, then one feed per asset, in that order.
Handshake
Each socket is a standard WebSocket upgrade (RFC 6455) with your token in the Authorization header:
GET /maker HTTP/1.1
Host: <provided by covr>
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Authorization: Bearer covr_mk_<rest of your token>The same header goes on GET /api/rfqs/<id>.
Header rules
| Rule | Detail |
|---|---|
| Scheme | Bearer, any letter case, then exactly one space. |
| Token | 16 to 256 characters from A-Z a-z 0-9 . _ ~ + / -, optionally followed by = padding. |
| Whole header | At most 300 characters. |
| Anything else | Treated as no token: 4401. This includes Basic auth and a raw token without Bearer. |
Path rules
- The path is exactly
/makeror/rfqs/<alias>. No trailing slash. No query string. - The alias is lowercase
0xplus 40 hex digits. - Put feeds (
/rfqs/put/<asset alias>/<payment alias>) exist on covr's gateway for covr's own maker only. covr's public desk endpoint does not route them: such an upgrade is refused before the handshake. - A path that is not served is refused before the WebSocket handshake. You get an HTTP error status or a dropped connection, never a close code.
What the gateway checks, in order
| Step | Check | Outcome on failure |
|---|---|---|
| 1 | The endpoint has room for another desk connection. The room is shared by all desks. | Connection dropped, or HTTP 503, before any handshake. |
| 2 | The path is /maker or /rfqs/<alias> of a served asset. | Connection dropped before any handshake. |
| 3 | The token is registered. | Handshake completes, then close 4401 Unauthorized. |
| 4 | For a feed: the asset is in your token's allowlist. | Close 4403 Asset not allowed. |
| 5 | Your maker has fewer than 16 open sockets. | Close 4429 Too many connections. |
A refused socket is never subscribed and never read. It sees no RFQ. If you do not answer the close frame, the gateway cuts the connection after about 1 s.
Asset aliases
The feed path names a collateral by its 20-byte wire alias, not by its mint. The same alias appears in every RFQ (asset, collateralAsset) and in every bid intent and quote you sign (assetAddress, collateralAsset). The USDC alias appears as usd.
alias = "0x" + lowercase hex of the last 20 bytes of keccak256(32-byte mint public key)An alias is an identifier only. It is not an EVM contract.
| Asset | Mint | Alias |
|---|---|---|
| JitoSOL | J1toso1uCk3RLmjorhTtrVwY9HJ7X8V9yYac6Y7kGCPn | 0x43127405c3191a0b63a5f3d845f616ffea348c68 |
| USDC | EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v | 0x5ce3bf3a31af18be40ba30f721101b4341690186 |
With the SDK:
import { assetAlias, JITOSOL_ALIAS, JITOSOL_MINT } from '@covrfun/maker-sdk';
assetAlias(JITOSOL_MINT) === JITOSOL_ALIAS; // '0x43127405c3191a0b63a5f3d845f616ffea348c68'Without it, using ethers and @solana/kit:
import { keccak256 } from 'ethers';
import { address, getAddressEncoder } from '@solana/kit';
function alias(mint: string): string {
const key = getAddressEncoder().encode(address(mint)); // the 32-byte public key
return '0x' + keccak256(new Uint8Array(key)).slice(-40);
}
alias('J1toso1uCk3RLmjorhTtrVwY9HJ7X8V9yYac6Y7kGCPn'); // '0x43127405c3191a0b63a5f3d845f616ffea348c68'Heartbeat
What the gateway does
Every 30 s the gateway visits each of your sockets:
- If the socket did not answer the previous ping, it is terminated.
- If more than 1 MiB of outgoing data is queued for it (you stopped reading), it is terminated.
- Otherwise it gets a new WebSocket ping with a fresh random 16-byte payload.
Only a pong that echoes the latest ping's payload exactly counts. An unsolicited pong, or an echo of an older ping, does not. RFC 6455 clients do this for you. So a socket whose peer vanished without closing is gone within two beats, about 60 s.
A terminated socket gets no close frame. Your client sees an abnormal closure (1006 in most libraries).
Pongs are free. Your own pings count against your frame budget.
While a dead socket waits to be reaped it still holds its slot and any award it holds. An award lasts at most 3 s, far shorter than the reap. A desk whose path dies silently while it holds an award loses that RFQ, and the customer gets no quote.
What GatewayClient adds
The SDK runs its own heartbeat on every socket, so it notices a dead path from its side too:
| Setting | Default | Range |
|---|---|---|
heartbeatIntervalMs: ping every | 15 000 ms | 1 to 300 000 |
heartbeatTimeoutMs: end the socket if no pong within | 30 000 ms | 1 to 300 000 |
handshakeTimeoutMs: each upgrade must finish within | 10 000 ms | 1 to 60 000 |
With the defaults a path that dies silently is reported within about 45 s: up to 15 s until the next ping, then 30 s for its pong. The socket then ends with a closed event whose reason says no pong within 30000 ms.
If you write your own client, do the same. A TCP connection through NATs and proxies can die without a FIN or RST, and nothing else will tell you.
Sockets are single-use
The gateway keeps no session. A socket that closes takes its state with it:
- An award it holds passes on at once to the next ranked maker. See Award passing.
- A bid it sent can never win. If that bid ranks first after the socket closed, the gateway skips it.
- The quote must come on the socket that sent the bid. The award goes to that socket, and a quote from any other socket, even your own, is refused.
- RFQs are announced once. A feed that was down when an RFQ was created never receives it. There is no replay.
Reconnecting
When any of your sockets ends, treat the whole connection as gone:
- Close every socket you still hold. This frees their slots at once. A socket you abandon without closing keeps its slot until the heartbeat reaps it.
- Wait. Use capped exponential backoff with jitter. The example bot starts at 1 s, doubles to a 30 s cap, and picks a random delay in the upper half of each step.
- Open
/maker, then the feeds. - Forget bids you sent on the old connection. Keep reconciling quotes you signed: one may still fill.
Do not retry 4401 or 4403 in a loop. They mean your token or allowlist is wrong, and only covr can change that. 4429 Too many connections usually means old sockets are still open: close them, or wait up to about 60 s for the heartbeat to reap dead ones.