covr.Docs

Gateway reference

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

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

RouteKindDirectionPurpose
/makerWebSocketboth waysYour command socket. You send bid_intent, quote, award_decline and rfq_note. The gateway sends replies and award messages.
/rfqs/<asset alias>WebSocketgateway to deskRead-only feed. One rfq event per new customer request for that collateral.
GET /api/rfqs/<id>HTTPSrequest, responseOne 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.

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 }
FieldTypeMeaning
readybooleantrue when covr's price inputs are all fresh, at least one listed market has a live price, and covr's quoting is ready.
marketsnumberListed markets that have a live price now.
priceAgeSecnumber or nullAge of the oldest price input, in seconds. null when any input is stale.
checkedAtnumberWhen the gateway checked, in Unix milliseconds.
StatusWhen
200ready is true.
503ready is false, or the status could not be read. The body then has ready: false, markets: 0 and priceAgeSec: null.
400The URL has a query string.
405A 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). 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, 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 valueWhat it isWhat it controls
Quote keyYour 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 authorityThe 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 assets1 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 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.
  • 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.
  • 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 onShapeMeaning
/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.

FileCovers
maker-rfq.asyncapi.jsonAsyncAPI 3.0: /maker and /rfqs/<alias>, every message both ways, close codes, limits and the EIP-712 types.
maker-http.openapi.jsonOpenAPI 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: handshake, asset aliases, heartbeat and reconnects.
  • Messages: every message with a full example and a field table.
  • RFQ lifecycle: the 3 s / 6 s / 60 s timeline, ranking and award passing.
  • Limits: connection caps, frame budget and timeouts.
  • Errors: every close code and every error message.