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

```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

| 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 `/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

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

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


| Asset | Mint | Alias |
| --- | --- | --- |
| JitoSOL | `J1toso1uCk3RLmjorhTtrVwY9HJ7X8V9yYac6Y7kGCPn` | `0x43127405c3191a0b63a5f3d845f616ffea348c68` |
| USDC | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | `0x5ce3bf3a31af18be40ba30f721101b4341690186` |


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](https://docs.covr.markets/reference/gateway/limits.md#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:

| 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](https://docs.covr.markets/reference/gateway/rfq-lifecycle.md#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.

---

Source: https://docs.covr.markets/reference/gateway/connection · Part of covr Docs, https://docs.covr.markets/llms.txt
