# Gateway protocol overview

This section is the wire reference for covr's RFQ gateway, as a market-making desk sees it. It lists every route, every message in both directions, every limit and every error. Use it to build a client in any language, or to debug one.

Most desks do not need it. The SDK's [`GatewayClient`](https://docs.covr.markets/reference/sdk/gateway-client.md) speaks this protocol for you: it opens the sockets, sends your token, matches replies to requests, runs a heartbeat and turns refusals into typed errors. Read on if you write your own client, or if you want to know exactly what `GatewayClient` sends.

> [!NOTE]
> Desk access is turned on per desk by covr. Today covr's markets list only covr's own maker, so your bids are verified like real ones and then refused with `Bid intent verified but not entered: this market does not list this maker yet`. This is practice mode. It skips a few checks; see [Practice mode](https://docs.covr.markets/reference/gateway/rfq-lifecycle.md#practice-mode) for exactly what it tests. Practice bids never rank, never win and never change what a customer sees. Desks can quote JitoSOL call markets only. Listing other desks needs a covr release; its date is to confirm with covr. Cash-secured puts are live for customers since 7 November 2026, but covr's gateway routes put RFQs only to covr's own maker: see [Cash-secured puts](https://docs.covr.markets/concepts/puts.md).


## Base URL

covr gives you one URL: `wss://<provided by covr>`. Every route below hangs off it. The HTTP route uses the same host over `https://`.


## The three desk routes

| Route | Kind | Direction | Purpose |
| --- | --- | --- | --- |
| `/maker` | WebSocket | both ways | Your command socket. You send `bid_intent`, `quote`, `award_decline` and `rfq_note`. The gateway sends replies and `award` messages. |
| `/rfqs/<asset alias>` | WebSocket | gateway to desk | Read-only feed. One `rfq` event per new customer request for that collateral. |
| `GET /api/rfqs/<id>` | HTTPS | request, response | One RFQ's snapshot: market, customer wallet, deadlines, status, and your own admitted quote if you won. |

No other route exists for desks. There is no market list, no order book, no position list, no put feed and no quote withdrawal route. Each RFQ snapshot names its market account: read it from chain. covr's market catalog route is not open to desks: see [Markets](https://docs.covr.markets/concepts/markets.md#the-market-catalog).

## Public quote status

One route needs no token: `GET https://<gateway host>/status/quotes`, on the same host as your `wss://` URL. It reports whether covr's own maker can quote customers right now. It says nothing about your desk.

```json
{ "ready": true, "markets": 2, "priceAgeSec": 4, "checkedAt": 1792915200000 }
```

| Field | Type | Meaning |
| --- | --- | --- |
| `ready` | boolean | `true` when covr's price inputs are all fresh, at least one listed market has a live price, and covr's quoting is ready. |
| `markets` | number | Listed markets that have a live price now. |
| `priceAgeSec` | number or `null` | Age of the oldest price input, in seconds. `null` when any input is stale. |
| `checkedAt` | number | When the gateway checked, in Unix milliseconds. |

| Status | When |
| --- | --- |
| 200 | `ready` is `true`. |
| 503 | `ready` is `false`, or the status could not be read. The body then has `ready: false`, `markets: 0` and `priceAgeSec: null`. |
| 400 | The URL has a query string. |
| 405 | A method other than `GET`. |

Responses carry `Cache-Control: no-store`. The gateway re-reads its inputs at most once a second, so poll no faster than that.

`GET /status/health`, on the same host and also without a token, is the liveness view of the same signal, meant for uptime monitors. It tolerates short dips: it stays healthy until covr's quoting has been not ready for 60 s in a row, or at once if covr's quote publisher has stopped. It returns `200` when `healthy` is `true`, else `503`, with the same `400` and `405` rules. Its body is the quote-status body plus `healthy` (boolean), `notReadyForMs` (number) and `idle: true` while covr's own maker is idle: it pauses price refreshes after 5 minutes without a customer request and warms up on the next one.


> [!WARNING]
> There is no withdrawal route for desks. For an immediate, reversible stop, pause your mint policy ([Cancel quotes](https://docs.covr.markets/guides/cancel-quotes.md)). To cancel quotes you have signed for good, raise `min_nonce` on your Maker account with `configureMaker`. Every fill whose nonce is below the new floor then fails on chain. A quote is valid for at most 60 s anyway.


## Authentication

Every upgrade and every HTTP request carries one header:

```text
Authorization: Bearer <token>
```

covr issues the token. Tokens covr mints start with `covr_mk_`. Keep it secret.

A leaked token lets someone read your RFQ feed and RFQ snapshots, which name customer wallets. It lets them open sockets as your desk and take your 16 slots, so your real bot is refused with `4429`. If desks can be listed in future, it would also let them set the customer-facing `rfq_note` reason on RFQs for your assets. It does **not** let them bid or quote for you: a bid intent must be signed by your registered quote key, and an award goes only to the socket that sent the winning bid. If a token leaks: Message us on Telegram: [@malviyaop](https://t.me/malviyaop), and ask for a new token.

The gateway stores only a SHA-256 digest of each token. It hashes the token you present and compares it with every registered digest in constant time. A token never appears in a close reason, an HTTP body or a JSON-RPC error.


### What a token maps to

A token is bound, at covr's side, to three things. None of them is taken from your frames.

| Bound value | What it is | What it controls |
| --- | --- | --- |
| Quote key | Your secp256k1 signing address (`0x` + 40 hex), the key you registered with `register_maker_v3`. | The `maker` field of every bid intent and quote you send must be this key. |
| Solana authority | The authority of your on-chain Maker account. | A fill of your quote pays from, and opens a position for, the Maker account of this key and authority. |
| Allowed assets | 1 to 16 collateral mints. For desks today: JitoSOL only. | Which `/rfqs/<alias>` feeds you may open and which RFQs you may act on. |


covr can have several tokens for one quote key (for example one per server). They all act as the same maker and share one connection cap. covr checks at startup that your Maker account exists on chain with the registered key and authority, so register on chain before you ask for a token.


## Message framing

The two WebSocket routes carry JSON text frames. The `/maker` socket uses [JSON-RPC 2.0](https://www.jsonrpc.org/specification) with a few covr rules:

- `id` is a string of at most 128 characters. For `bid_intent`, `quote` and `award_decline` it **must** be the RFQ id: the gateway looks the RFQ up by `id`. For `rfq_note` it is any string; the RFQ goes in `params.rfqId`.
- `params` is an object. Exact field sets are given per method in [Messages](https://docs.covr.markets/reference/gateway/messages.md).
- Every reply carries the request's `id`. A frame the gateway cannot parse gets a reply with `"id": null`.
- Every refusal uses error code `-32602`, including parse errors. The `message` text tells you why. See [Errors](https://docs.covr.markets/reference/gateway/errors.md).
- Batch requests (a JSON array) are not supported.
- Replies to different RFQs can arrive in any order. Match them by `id`. Keep at most one request per RFQ in flight.


The gateway also pushes two unsolicited shapes:

| Pushed on | Shape | Meaning |
| --- | --- | --- |
| `/rfqs/<alias>` | `{"jsonrpc":"2.0","id":"<rfq id>","result":{...}}` | A new RFQ. It looks like a response, but you never sent a request. |
| `/maker` | `{"jsonrpc":"2.0","id":"<rfq id>","method":"award","params":{...}}` | You won the auction. Answer it with `quote` or `award_decline`, not with a JSON-RPC response. |


## Machine-readable specs

Two files describe these routes for code generators and validators. A script generates them from covr's source and checks them against it, so a change on covr's side that they no longer match fails that check instead of drifting.

| File | Covers |
| --- | --- |
| [`maker-rfq.asyncapi.json`](https://docs.covr.markets/specs/maker-rfq.asyncapi.json) | AsyncAPI 3.0: `/maker` and `/rfqs/<alias>`, every message both ways, close codes, limits and the EIP-712 types. |
| [`maker-http.openapi.json`](https://docs.covr.markets/specs/maker-http.openapi.json) | OpenAPI 3.1: `GET /api/rfqs/{id}`, `GET /status/quotes` and `GET /status/health`. |

Each file records the covr source commit it was generated from (`x-covr-source`). Timing, ranking, award passing and practice mode are behaviour, not shape: they are on the pages below.

## Where to go next

- [Connection](https://docs.covr.markets/reference/gateway/connection.md): handshake, asset aliases, heartbeat and reconnects.
- [Messages](https://docs.covr.markets/reference/gateway/messages.md): every message with a full example and a field table.
- [RFQ lifecycle](https://docs.covr.markets/reference/gateway/rfq-lifecycle.md): the 3 s / 6 s / 60 s timeline, ranking and award passing.
- [Limits](https://docs.covr.markets/reference/gateway/limits.md): connection caps, frame budget and timeouts.
- [Errors](https://docs.covr.markets/reference/gateway/errors.md): every close code and every error message.

---

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