covr.Docs

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:

SocketPathYou sendYou receive
Command/makerbid_intent, quote, award_decline, rfq_noteReplies, award
Feed/rfqs/0x43127405c3191a0b63a5f3d845f616ffea348c68Nothingrfq 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:

text
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

RuleDetail
SchemeBearer, any letter case, then exactly one space.
Token16 to 256 characters from A-Z a-z 0-9 . _ ~ + / -, optionally followed by = padding.
Whole headerAt most 300 characters.
Anything elseTreated as no token: 4401. This includes Basic auth and a raw token without Bearer.

Path rules

  • The path is exactly /maker or /rfqs/<alias>. No trailing slash. No query string.
  • The alias is lowercase 0x plus 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

StepCheckOutcome on failure
1The endpoint has room for another desk connection. The room is shared by all desks.Connection dropped, or HTTP 503, before any handshake.
2The path is /maker or /rfqs/<alias> of a served asset.Connection dropped before any handshake.
3The token is registered.Handshake completes, then close 4401 Unauthorized.
4For a feed: the asset is in your token's allowlist.Close 4403 Asset not allowed.
5Your 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.

text
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.

AssetMintAlias
JitoSOLJ1toso1uCk3RLmjorhTtrVwY9HJ7X8V9yYac6Y7kGCPn0x43127405c3191a0b63a5f3d845f616ffea348c68
USDCEPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v0x5ce3bf3a31af18be40ba30f721101b4341690186

With the SDK:

ts
import { assetAlias, JITOSOL_ALIAS, JITOSOL_MINT } from '@covrfun/maker-sdk';

assetAlias(JITOSOL_MINT) === JITOSOL_ALIAS; // '0x43127405c3191a0b63a5f3d845f616ffea348c68'

Without it, using ethers and @solana/kit:

ts
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:

  1. If the socket did not answer the previous ping, it is terminated.
  2. If more than 1 MiB of outgoing data is queued for it (you stopped reading), it is terminated.
  3. 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.

Warning

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:

SettingDefaultRange
heartbeatIntervalMs: ping every15 000 ms1 to 300 000
heartbeatTimeoutMs: end the socket if no pong within30 000 ms1 to 300 000
handshakeTimeoutMs: each upgrade must finish within10 000 ms1 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:

  1. 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.
  2. 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.
  3. Open /maker, then the feeds.
  4. 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.