Gateway reference
RFQ lifecycle
This page follows one RFQ from the customer's request to the fill on chain, with the exact timings the gateway enforces. It also defines how bids are ranked, how an award passes from one maker to the next, and what an OK reply does and does not mean.
Timing constants
| Constant | Value | Meaning |
|---|---|---|
COLLECT_MS | 3 000 ms | Bids are collected for 3 s after the RFQ is created. |
AWARD_MS | 3 000 ms | An award lasts at most 3 s, and never past the hard deadline. |
TOTAL_MS | 6 000 ms | The hard deadline: no quote is admitted 6 s or more after creation. |
REVIEW_SECONDS | 60 s | A quote's validUntil may be at most 60 s after the gateway's clock when it starts admitting that quote. It does not run from the RFQ's creation. |
The SDK exports all four. Because 3 s + 3 s = 6 s, the first award's window runs to the hard deadline, and so does every later one.
Timeline
Times are from the moment the gateway creates the RFQ. The snapshot gives that moment as closesAt - 3000.
| Time | What happens | Your move |
|---|---|---|
| 0 s | The customer asks for a quote. The gateway creates the RFQ and sends one rfq event to every feed for that asset. | Read GET /api/rfqs/<id> for the market and the customer wallet. |
| 0 to 3 s | Collection. Sealed bids are accepted. | Send one bid_intent, or an rfq_note if you will not bid. |
3 s (closesAt) | Collection closes. Bids are ranked. The best bid's socket gets an award. | |
| 3 to 6 s | The award window. | The awarded maker answers with quote or award_decline. |
6 s (hardDeadline) | No quote is admitted from now on. With no admitted quote, the RFQ is no_quote. | |
Your quote's validUntil | At most 60 s after the gateway began admitting your quote, so at most about 66 s after the RFQ was created. The customer must land the fill before it. | Watch your position PDA on chain. |
| 120 to 130 s | The gateway forgets the RFQ. GET /api/rfqs/<id> returns 404. |
Sequence
Customer Gateway Desk Chain
| | | |
0 s|-- request quote ---->| | |
| |-- rfq event (/rfqs/<alias>) ------>| |
| |<------------ GET /api/rfqs/<id> ---| |
| |-- snapshot: market, wallet ------->| |
| | | price, sign intent |
| |<------------------- bid_intent ----| |
| |-- "BID_ACCEPTED" ----------------->| |
3 s| | collection closes, rank bids | |
| |-- award (intent, awardUntil) ----->| |
| | | journal nonce, sign quote|
| |<------------------------ quote ----| |
| | admit quote | |
| |-- "OK" --------------------------->| |
|<-- winning quote ----| | |
6 s| | hard deadline | |
| review, sign fill | | |
|-------------------------------------------------------------------- fill (fill_v3) -->|
| | |<-- read position PDA -----|
| | | (until validUntil) |No message tells you about the fill. You learn it from the chain.
Collection
- Each maker may enter one bid per RFQ. A second bid from the same maker is refused.
- A bid must arrive before collection closes. The gateway measures this on its own clock.
- The bid's
validUntilmust be later than the gateway's clock, later thanceil(closesAt / 1000), and not later than the optionexpiry. - The gateway does not tell you about other bids.
bidCountin the snapshot says how many bids entered.
Ranking
Bids are sealed. When collection closes, the gateway sorts them:
- Higher
pricefirst. Prices are compared as integers. - On equal prices, the bid that reached the gateway first.
The first bid in that order gets the award.
Practice-mode bids never enter this list.
Awards
The award goes to the socket that sent the winning bid. It carries awardUntil: the time by which your quote must be admitted. It is min(award time + 3 s, hard deadline), so in practice it equals the hard deadline.
Answer every award, once:
quoteif you will trade at your bid price.award_declineif you will not. Do it at once.
Award passing
An award passes to the next ranked bid at once when any of these happens:
| Event | Effect |
|---|---|
You send award_decline and get DECLINED. | Passes at once. |
Your award_decline is refused (wrong intentSignature, extra fields, wrong socket). | Nothing. You still hold the award. Resend exactly {intentSignature} before awardUntil. |
Your awarded socket closes, for any reason. This includes a heartbeat reap, a 4429, and a frame over 16 KiB. | Passes at once. |
| Your awarded socket had already closed when collection ended. | Your bid is skipped. |
You answer with a well-formed quote frame for that RFQ and the gateway refuses it, for any reason: bad params, another intent, a bad signature, a late quote, or the gateway being busy. | Passes at once, after the error reply. |
| Another maker sends a bad frame about your RFQ. | Nothing. Only the award holder's own frames can pass its award. |
| You send a frame that is not valid JSON. | Nothing. It names no RFQ. |
Each bid is offered at most once. A pass never goes back to a maker who already had the award. When no ranked bid is left, the RFQ ends no_quote at once.
A silent winner
If the award holder neither quotes nor declines, it keeps the award until awardUntil, which is the hard deadline. No other maker is offered the RFQ, and the customer gets no quote. A socket that died without closing counts as silent until the heartbeat reaps it, which takes longer than an auction.
A silent winner costs the customer the trade. If anything stops you from quoting, decline.
Quote admission
The gateway admits your quote only if all of these hold when it reads the frame:
- You hold the current award for this RFQ, on this socket, and
awardUntilhas not passed. intentSignatureis the signature of your awarded intent.- The quote's
makerandpriceequal the awarded intent's. auctionIdis the RFQ id andwriteris the customer wallet from the snapshot.- Every instrument field equals the RFQ: aliases,
chainId,strike,expiry,quantity,isPut = false,isTakerBuy = false. now < validUntil <= now + 60andvalidUntil <= expiry, in unix seconds.nowis the gateway's clock when it starts admitting this quote, not the RFQ's creation time.validUntilmust also still be in the future when admission ends.- The nonce is a u64 below 2^64 - 1, and the gateway has not already admitted it in a different quote of yours that is still live.
- The premium,
quantity × price / 10^30, is a whole number of USDC atoms. - The EIP-712 signature recovers to
makerin the market's domain.
Then a final check runs on covr's side. It re-verifies your signature and terms against covr's reviewed copy of the market, checks that your token's maker and Solana authority are the ones the fill will use, and checks the quote is still live. If this check fails, or does not finish before the hard deadline, the quote is refused with Ordinary V3 quote admission unavailable and the award passes.
Keep your clock in sync with NTP. The gateway decides every deadline with its own clock.
What OK means
"OK" means one thing: the gateway admitted your quote and now shows it to the customer as the winning quote.
It does not mean:
- A fill. The customer reviews the quote and may sign the fill transaction before
validUntil, or may not. - A funds check. The gateway checks your signature and terms, not your USDC vault, exposure limits or
min_nonce. Those are checked when the customer's transaction is prepared and again by the program. If they fail, the customer cannot fill and you are not told.
No fill message is sent, ever. To learn the outcome, watch the chain:
- Filled: your position PDA for this nonce exists. Derive it with the SDK's
derivePosition. See Setup. - Not filled: the PDA does not exist, the chain's clock has passed
validUntil, and no transaction ever referenced the PDA. A missing account alone is not proof: a position can be filled and later closed.
Until one of these is proven at finalized commitment, keep the cash the quote could cost on hold.
A fill moves the premium out of your USDC vault. You cannot cancel one quote through the gateway. For an immediate, reversible stop, pause your mint policy (Cancel quotes). To cancel signed quotes for good, raise min_nonce with configureMaker: every quote with a lower nonce then fails on chain.
Practice mode
covr's markets list only covr's own maker today, so every other desk is in practice mode on every market. You receive every RFQ for your allowed assets, and you can send bid intents. Each bid is checked, then refused with Bid intent verified but not entered: this market does not list this maker yet. The refusal comes before the bid would enter the auction, so some checks never run.
What practice mode checks, exactly as for a listed desk:
- Your token, the RFQ's asset against your allowlist, and that
makeris your registered quote key. - The intent's 18 fields, field types and every instrument field against the RFQ.
auctionId,marketandwalletagainst the RFQ and its snapshot.validUntil: later than the gateway's clock, later thanceil(closesAt / 1000), not later thanexpiry.- Price exactness: the premium must be a whole number of USDC atoms.
- The signature: encoding, recovery byte, and recovery to your key in the market's EIP-712 domain.
What practice mode does not check or exercise:
- The 3 s collection deadline. A late practice bid still gets the practice refusal, not
Auction collection closed. - The one-bid-per-maker rule. A repeated practice bid gets the practice refusal again, not
Maker already bid in this auction. - Ranking, awards,
quote,award_decline, nonces, quote admission and fills. You never receive anaward. rfq_note. It is refused withRFQ note needs a maker this market lists.
Your open feed also does not count as a maker listening, so it never hides the customer's warming_up message.
Use practice mode to prove your feed handling, snapshot reads, price rounding, intent signing and reconnects. Time your bids yourself against closesAt: practice mode will not tell you that a bid was late. Your quote path is not exercised until desks can be listed, which is planned work.