# 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

```text
 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 `validUntil` must be later than the gateway's clock, later than `ceil(closesAt / 1000)`, and not later than the option `expiry`.
- The gateway does not tell you about other bids. `bidCount` in the snapshot says how many bids entered.


## Ranking

Bids are sealed. When collection closes, the gateway sorts them:

1. Higher `price` first. Prices are compared as integers.
2. 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:

- **`quote`** if you will trade at your bid price.
- **`award_decline`** if 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.


> [!WARNING]
> 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 `awardUntil` has not passed.
- `intentSignature` is the signature of your awarded intent.
- The quote's `maker` and `price` equal the awarded intent's.
- `auctionId` is the RFQ id and `writer` is the customer wallet from the snapshot.
- Every instrument field equals the RFQ: aliases, `chainId`, `strike`, `expiry`, `quantity`, `isPut = false`, `isTakerBuy = false`.
- `now < validUntil <= now + 60` and `validUntil <= expiry`, in unix seconds. `now` is the gateway's clock when it starts admitting this quote, not the RFQ's creation time. `validUntil` must 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 `maker` in 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](https://docs.covr.markets/reference/sdk/setup.md).
- **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](https://docs.covr.markets/guides/cancel-quotes.md)). 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 `maker` is your registered quote key.
- The intent's 18 fields, field types and every instrument field against the RFQ.
- `auctionId`, `market` and `wallet` against the RFQ and its snapshot.
- `validUntil`: later than the gateway's clock, later than `ceil(closesAt / 1000)`, not later than `expiry`.
- 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 an `award`.
- `rfq_note`. It is refused with `RFQ 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.

---

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