Quoting RFQs - Joyride Docs

An RFQ is a package of one to thirteen option legs on one underlying and one expiry. The taker submits the legs and names a side: buy or sell, which reveals the direction and asks for that one price, or two_way, which hides it and takes a bid, an ask, or both. The first firm quote wins, and the taker accepts a side the quote priced. This page covers the maker methods and pushes. It assumes the quoter role and the readiness checks on Becoming an RFQ Quoter. Session mechanics are on API Connectivity; what the signature covers is on The Signed Quote. Each method and push has a reference page with its full schema and an example frame under Reference in this tab.

Summary

Parameter	Value	Applies to
Request window	5 seconds from creation	how long a request accepts quotes; `request_deadline` on the `open` object
Quote TTL maximum	3600 seconds, bounded by the nearest leg close	`expires_at - issued_at` on `rfq.maker.respond`; `max_quote_expires_at` on the `open` object is the hard ceiling
Landing haircut	2 seconds	a quote is refused if fewer than 2 seconds of life remain when it lands, and the accept and submission deadlines are clamped 2 seconds before `expires_at`
Submission window	30 seconds after accept	time allowed to submit the fill on chain; shortened if the quote expires first
Legs per request	1 to 13 legs, one underlying, one expiry	`legs[]` on every request
Quotes per request	1 quote per request; the first firm quote wins	`rfq.maker.respond`
Decimal precision	6 decimals, decimal string	every `bid`, `ask`, `quantity`, `premium`, and `maker_fee`
Quote nonce	unsigned 64-bit integer as a decimal string, strictly increasing per account	`quote_nonce` on `rfq.maker.respond`
Poll page size	1 to 100 items, default 100	`limit` on `rfq.maker.poll`

Lifecycle

A request is first visible as pending. States after quoted are delivered only to the maker whose quote won.

State	Meaning	What the maker receives
`pending`	The request is open and no quote has been accepted by the venue yet	an `open` push, or an item in a `rfq.maker.poll` page
`quoted`	The maker’s quote won and is firm until `expires_at`	the `rfq.maker.respond` result with `quote_id` and `state: "quoted"`, and a `state` push with `state: "quoted"`
`accepted`	The taker accepted one side of the maker’s quote	a `state` push with `state: "accepted"` and `accepted_side` set
`submitting`	The fill transaction is being submitted on chain, including a retry after a confirmed fill is reverted	a `state` push with `state: "submitting"`, sent twice (once when the venue signs the fill, once when it is submitted), or a `finality: "reverted"` push whose RFQ has returned to this state
`filled`	The fill landed on chain	a `fill` push carrying the fill object, then a `finality` push when the fill is finalized or reverted
`declined`	A quoter declined it, which ends the request for everyone; the request window closed with no quote from anyone; or a leg stopped trading while the request was open	a `state` push with `state: "declined"` if this maker declined; a broadcast `state` push with `quote_id: null` when nobody quoted or a leg stopped trading; nothing if another quoter declined
`expired`	The winning quote reached 2 seconds before `expires_at` without an accept	a `state` push with `state: "expired"`
`failed`	The venue refused to sign the fill, or the fill was submitted and did not land within the submission window	a `state` push with `state: "failed"`

After another quoter wins, the request is no longer visible. A late rfq.maker.respond returns RFQ_STATE_CONFLICT, and no push reports the outcome.

Connecting

The maker channel is per socket. On every connection, including a resume with public/session_resume, call rfq.maker.subscribe, then page rfq.maker.poll until a result has no next_cursor. Subscribing first closes the gap in which a request could open unseen. Poll items and open pushes have the same shape and overlap in time, so deduplicate on rfq_id. Errors are per call and leave the socket usable; a retryable error on either method is retried with backoff on the same connection.

Method	Request	Response	Errors
`rfq.maker.subscribe`	`{}`	`{channel: "rfq_maker", subscribed: true}`	`1200` `RFQ_WRONG_ROLE`, `RFQ_INVALID_PARAMS`
`rfq.maker.poll`	`cursor?` (an `rfq_id`), `limit?` 1 to 100	`{items: [open object, ...], next_cursor?}`	`1200` `RFQ_NOT_READY`, `RFQ_WRONG_ROLE`, `RFQ_INVALID_PARAMS`, `RFQ_VALUE_OUT_OF_RANGE`, `RFQ_RATE_LIMITED`
`rfq.maker.respond`	`rfq_id`, `quote_nonce`, `bid` and/or `ask`, `issued_at`, `expires_at`, `max_maker_fee`, `max_maker_locked_balance`, `maker_signature`	`{rfq_id, quote_id, state: "quoted"}`	`1200` `RFQ_NOT_READY`, `RFQ_WRONG_ROLE`, `RFQ_STATE_CONFLICT`, `RFQ_SIDE_NOT_REQUESTED`, `RFQ_CANONICAL_MISMATCH`, `RFQ_INVALID_SIGNATURE`, `RFQ_SIGNED_LIMIT_BELOW_REQUIREMENT`, `RFQ_MAKER_UNFUNDED`, `RFQ_QUOTE_EXPIRED`, `RFQ_INVALID_PARAMS`, `RFQ_VALUE_OUT_OF_RANGE`, `RFQ_PRECISION_UNSUPPORTED`, `RFQ_INVALID_INSTRUMENT`, `RFQ_NOT_FOUND`, `RFQ_RATE_LIMITED`
`rfq.maker.decline`	`rfq_id`, `reason`	`{rfq_id, state: "declined", decline_reason}`	`1200` `RFQ_NOT_READY`, `RFQ_WRONG_ROLE`, `RFQ_STATE_CONFLICT`, `RFQ_INVALID_PARAMS`, `RFQ_NOT_FOUND`, `RFQ_RATE_LIMITED`

rfq.maker.poll, rfq.maker.respond, and rfq.maker.decline count against the 100-request account budget; rfq.maker.subscribe does not. See API Connectivity for the fixed-window semantics. Frames for rfq.maker.subscribe and rfq.maker.poll are on their reference pages. A poll result, which lists every request still open for quotes:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "items": [
      {
        "rfq_id": "0192f1a3b4c5d6e7f8091a2b3c4d5e6f",
        "legs": [
          { "instrument": "BTC_USDC-2MAY26-77000-C", "quantity": "1.000000", "asset": 0, "strike": "77000.000000", "expiry": 1777708800, "kind": "call" },
          { "instrument": "BTC_USDC-2MAY26-80000-C", "quantity": "-2.000000", "asset": 0, "strike": "80000.000000", "expiry": 1777708800, "kind": "call" }
        ],
        "taker_account": 2077,
        "taker_subaccount": "<base58 subaccount PDA>",
        "taker_funded": true,
        "maker_funding": {
          "anchored": true,
          "free_balance": "12500.000000",
          "buy": {
            "required": "262.500000",
            "estimate": false,
            "funded": true,
            "package_cash_delta": "470.000000",
            "cash_debit": "0.000000",
            "fee": "0.000000",
            "max_fee": "0.000000",
            "writer": true,
            "lock_increase": "250.000000",
            "post_fill_locked": "1250.000000",
            "max_locked_balance": "1262.500000"
          },
          "sell": {
            "required": "732.500000",
            "estimate": false,
            "funded": true,
            "package_cash_delta": "-470.000000",
            "cash_debit": "470.000000",
            "fee": "0.000000",
            "max_fee": "0.000000",
            "writer": true,
            "lock_increase": "250.000000",
            "post_fill_locked": "1250.000000",
            "max_locked_balance": "1262.500000"
          }
        },
        "request_deadline": "2026-05-01T15:40:06.000Z",
        "deployment": {
          "program_id": "<base58 program id>",
          "deployment_id": "<64 hex characters>",
          "config_pda": "<base58 config PDA>",
          "epoch": 3
        },
        "nearest_leg_close": "2026-05-02T08:00:00.000Z",
        "max_quote_expires_at": 1777708798
      }
    ],
    "next_cursor": "0192f1a3b4c5d6e7f8091a2b3c4d5e6f"
  }
}

Pass next_cursor back as cursor. Paging ends when a result has no next_cursor.

The open request

After subscribing, each new request arrives as a subscription notification on the rfq_maker channel with type: "open" and an rfq object of the same shape as a poll item.

Field	Meaning
`rfq_id`	16-byte request id as 32 lowercase hex characters; the key for every later method and push, and a field of the signed payload
`side`	Which side(s) you may quote: `buy` means the taker buys the package and takes only an `ask`; `sell` means the taker sells it and takes only a `bid`; `two_way` takes either or both. A price on a side the request did not ask for is refused with `RFQ_SIDE_NOT_REQUESTED`, never trimmed
`legs[]`	The package, in the taker’s submitted order. Each leg is a listed `instrument` symbol and a signed 6-decimal `quantity` in taker-buy orientation: positive means the taker receives that many contracts on a `buy` accept, negative means the taker delivers them. Each leg also carries the instrument’s resolved terms, which are what the signed quote encodes: `asset` (integer underlying id), `strike` (6-decimal string), `expiry` (Unix seconds), and `kind` (`call` or `put`). Legs are signed in this order; the venue never reorders them. A one-leg request with a positive quantity also carries top-level `instrument` and `size`, kept for older clients; ignore them and read `legs[]`
`taker_account`	The taker’s account id
`taker_subaccount`	The taker’s on-chain subaccount PDA, base58. Copied into the signed payload, which binds the quote to this counterparty
`taker_funded`	`true` when the taker has a positive free balance. A coarse signal: it does not show that the taker can fund either side of this package, and it discloses no balances
`maker_funding`	Your own economics on each taker side you may quote (`buy` = the taker buys the package, `sell` = the taker sells it), priced at the current mark through your portfolio and fee tier, and delivered only to you. `fee` and `post_fill_locked` are the unbuffered figures; `max_fee` and `max_locked_balance` add the venue’s configured tolerance and are the floor for the maxima you sign. `writer` says whether that side leaves you short a leg. A side is `null` while your subaccount has no covered on-chain anchor or a leg’s price is not fresh, and the side a single-sided request does not allow is always `null`. The whole object can be absent from an `open` push if the venue could not compute it in time; the next `rfq.maker.poll` item carries it. `rfq.maker.respond` rechecks the same figures at your actual `bid` and `ask`
`request_deadline`	RFC3339 UTC. Quotes that arrive after it are refused and the request drains to `declined`
`deployment`	The margin-vault deployment the request is bound to: `program_id` and `config_pda` in base58, `deployment_id` as 64 hex characters, and the integer `epoch` the request was created under. Of those four fields, only `deployment_id` and `program_id` are copied into the signed quote payload; `config_pda` and `epoch` are request metadata
`nearest_leg_close`	RFC3339 UTC with milliseconds, the same format as `request_deadline`. The earliest expiry among the legs; no quote may expire after it. Note it is NOT unix seconds, unlike `max_quote_expires_at` directly below
`max_quote_expires_at`	Unix seconds; `nearest_leg_close` less the 2-second landing haircut. Sign an `expires_at` at or before it. The venue refuses an `expires_at` after `nearest_leg_close` outright and never clamps; the 3600-second TTL ceiling is a separate check on `expires_at - issued_at`

The taker fixes every leg’s quantity when creating the request. An older one-leg rfq.create may send {instrument, size} instead of legs[]; the venue converts that pair to one positive leg. In either case, quote the exact legs[] shown here. A maker cannot change the quantity.

Pricing a package

bid and ask are signed USDC totals for the whole package in legs[], not per-contract or per-leg prices, and no size multiplier applies. Send the side(s) the request’s side allows: only ask on a buy request, only bid on a sell request, either or both on two_way. When both are present bid <= ask is required. Either side may be negative, since a credit structure or an inverted ratio can have negative package value. A side you leave out is signed as a reserved sentinel inside the payload (see The Signed Quote); that is the venue’s concern, and your JSON simply omits the field. The accepted side fixes both the cash and the contracts. Quantities are in taker-buy orientation: on a buy, the taker’s leg vector is legs[] as given and the maker’s is its negation.

Taker accepts	Cash	Taker receives per leg	Maker receives per leg
`buy`	taker pays `ask`; maker receives `ask`	`quantity`	`-quantity`
`sell`	taker receives `bid`; maker pays `bid`	`-quantity`	`quantity`

The same rules apply to negative prices. With bid: "-120.000000" and ask: "-80.000000", a taker who buys pays -80, so the taker collects 80 USDC from the maker. A taker who sells receives -120, so the taker pays 120 USDC to the maker. Example: 1×2 call spread. The request above asks for +1.000000 of the 77000 call and -2.000000 of the 80000 call. With marks of 1270 USDC and 400 USDC, the package is worth 1 × 1270 - 2 × 400 = 470 USDC to a buyer, and a quote 30 USDC either side of that value is bid 440, ask 500.

Taker accepts	Cash movement	Taker position after the fill	Maker position after the fill	`maker_side`	`premium`	`maker_fee`
`buy`	taker pays 500.000000; maker receives 500.000000	+1 of 77000-C, −2 of 80000-C	−1 of 77000-C, +2 of 80000-C	`sell`	500.000000	0.000000
`sell`	taker receives 440.000000; maker pays 440.000000	−1 of 77000-C, +2 of 80000-C	+1 of 77000-C, −2 of 80000-C	`buy`	440.000000	0.000000

premium on the fill is the accepted package total, not the maker’s signed cash flow: the maker receives it when maker_side is sell and pays it when maker_side is buy. maker_fee is 0 at launch; the fee formula and rates are on Fees and Limits. Either accepted side leaves the maker short at least one leg, so writers.maker on the fill is true.

Responding

A response is a signed quote on one side or both. The maker signs the quote with the wallet key bound to the account and sends the fields from which the venue rebuilds it. The venue verifies the signature over its own reconstruction and compares every field; any difference is RFQ_CANONICAL_MISMATCH. What the signature covers is on The Signed Quote. rfq.maker.respond carries no size; the taker’s requested quantities are already fixed in legs[]. A request that includes size, or any other field not listed below, is rejected with RFQ_INVALID_PARAMS. The frame is on rfq.maker.respond. The result carries the quote_id that identifies the signed quote in every later push. Declining. A decline ends the request. The venue moves it to declined at once, the taker sees the reason instead of waiting for the 5-second timeout, and any later rfq.maker.respond or rfq.maker.decline on it, from any quoter, returns RFQ_STATE_CONFLICT. Decline only requests that would not be quoted at any price, once per request. The result echoes rfq_id with state: "declined" and the decline_reason; the frame is on rfq.maker.decline.

Reason	Use it when	A reference policy
`unlisted_instrument`	A leg names an instrument the maker does not quote	a leg symbol is outside the configured instrument set; decided before pricing
`near_expiry`	The package is too close to `nearest_leg_close` to hedge	time to the leg expiry is under a configured minimum
`size_limit`	The package exceeds the maker’s size or position limit	a leg quantity exceeds the maximum size, or the position on the instrument is at its cap; a quote commits both sides at the taker’s option, so the whole request is declined rather than one side
`stale_data`	Spot, IV, or mark inputs are missing or stale	no fair value can be computed because spot or IV is absent
`low_confidence`	A price can be computed but the maker will not stand behind it	the pricing parameters are invalid, or the rounded bid falls to zero
`queue_overflow`	More requests are open than the maker can price inside the window	not needed when pricing keeps up with the request rate

Quote rules.

expires_at is at most 3600 seconds after issued_at and no later than max_quote_expires_at from the open request. A later value is RFQ_VALUE_OUT_OF_RANGE; the venue never clamps.
A quote must reach the venue with more than 2 seconds of life left, or it is RFQ_QUOTE_EXPIRED. The taker’s accept and submission windows end 2 seconds before the quote’s expiry.
A quote is firm for its full TTL regardless of market moves, so a short, fixed TTL is the recommended policy.
quote_nonce is an unsigned 64-bit integer sent as a decimal string, and it must be higher than every nonce the account has ever sent, across restarts; a wall-clock seed at startup satisfies this. A nonce at or below the account’s high-water mark is refused with RFQ_STATE_CONFLICT.
max_maker_fee and max_maker_locked_balance are unsigned 6-decimal USDC strings covered by the signature. They must be at least the larger fee and post_fill_locked across the sides you quoted, recomputed by the venue at your signed bid and ask; a smaller value is RFQ_SIGNED_LIMIT_BELOW_REQUIREMENT, and a subaccount with no covered anchor is RFQ_MAKER_UNFUNDED. One pair covers every quoted side because the taker chooses among them; an unquoted side contributes nothing. What they authorize is on The Signed Quote.
At least one of bid and ask is required, and only the side(s) the request’s side allows. A supplied unrequested side is RFQ_SIDE_NOT_REQUESTED; the request stays open and a corrected quote may follow.
One quote per request.

After quoting

Three push types follow a winning quote, all on the rfq_maker channel and delivered only to the winning maker. Their frames are on rfq_maker pushes.

state arrives on every transition from the quote on: quoted, accepted, submitting (twice), expired, and failed. accepted_side is null until the taker accepts and then carries buy or sell. On a taker buy the maker writes every positive leg and the taker every negative one; on a taker sell the roles flip.
fill arrives when the fill lands. premium is the accepted package total before fees, the same value as execution_price: the quote’s ask when the taker bought, its bid when the taker sold. It is never negated for the maker, so read the direction from maker_side: on sell the maker receives premium, on buy the maker pays it, and a negative premium reverses that. Book the execution provisionally on this push, keyed by rfq_id and quote_id; a later re-land of the same accepted RFQ is not a second trade.
finality repeats the fill object with finality changed from confirmed to finalized, or to reverted if the chain dropped that transaction. finalized is terminal success. reverted is not terminal: the RFQ returns to submitting and the relayer may submit the same accepted trade again. Mark that transaction attempt reverted, but do not unwind an external hedge or declare the RFQ failed yet. Wait for either another fill for the same rfq_id and quote_id under a new tx_signature, in which case keep the existing hedge and do not hedge it a second time, or a state push with state: "failed", in which case the trade is terminally absent and the hedge can be unwound under the desk’s policy.

Losing and late quotes. A losing or late quote receives no push. If another quoter’s respond reached the venue first, the later respond returns RFQ_STATE_CONFLICT and nothing further is sent about the request. The error means another quoter won, and any reserved risk can be released. A respond that arrives after request_deadline returns the same error, because the request has drained. The only push every quoter receives after open is the broadcast state with declined and quote_id: null, sent when the window closes with no quote or a leg stops trading. Reserved risk should be released on local timers, one per request from request_deadline and one per delivered quote from expires_at, not on the arrival of a message.

Reconciliation

On reconnect, run the connect sequence above: rfq.maker.subscribe, then page rfq.maker.poll, which returns every request still inside its window. Missed fills are not replayed over the socket, so read them from the query API with the session token as a bearer token and group attempts by rfq_id and quote identity. A reverted row invalidates that transaction attempt, not necessarily the accepted RFQ: a later row for the same RFQ may be its re-land under a new signature. Book the active confirmed or finalized attempt once. If the newest known attempt is reverted and no later fill or terminal failed state was observed, the fill history alone does not prove failure; leave the hedge in a pending-reversion state and reconcile the outcome rather than unwinding automatically. Send no status filter: it matches one finality value exactly and would hide other attempts. Rows come newest first; while a page carries next_cursor, pass it back as after to read the next one. The row schema and filters are on GET /api/query/rfq-fills.

GET /api/query/rfq-fills?role=maker&limit=100
Authorization: Bearer <jwt>

Errors

Every rfq.maker.* failure is JSON-RPC error 1200. data.error carries the RFQ code, data.retryable states whether the same request can succeed later, and data.operation_id identifies the call for support@joyride.exchange. RFQ_NOT_READY has several causes, distinguished by message and listed on Becoming an RFQ Quoter.

`data.error`	Meaning	Action
`RFQ_NOT_READY`	The venue cannot admit the call yet; `message` names the cause, and the common ones are on Becoming an RFQ Quoter. Also returned, retryable, while the venue is overloaded or restarting, and while an underlying is settling	Retry with backoff inside the window; escalate the Joyride-owned causes if they persist. A `retryable: false` readiness error names a wallet the venue cannot verify; contact support
`RFQ_NOT_ENABLED`	RFQ trading is switched off venue-wide	Do not retry; wait for an announcement
`RFQ_WRONG_ROLE`	The session is not authenticated, the account lacks `rfq_quoter`, or the caller acted on its own request	Check `roles` from `public/auth`; do not retry the same call
`RFQ_STATE_CONFLICT`	The request already holds a quote, was declined, drained at its deadline, or is otherwise past `pending`; or `quote_nonce` is at or below the account’s high-water mark	On respond, treat it as another quoter won and release risk; on a nonce conflict, re-seed above the mark
`RFQ_CANONICAL_MISMATCH`	The venue’s own reconstruction of the quote disagrees with its record of the request; an internal consistency failure rather than a maker error. A payload the maker built differently fails as `RFQ_INVALID_SIGNATURE`	Report the `operation_id` to support; do not retry unchanged
`RFQ_INVALID_SIGNATURE`	`maker_signature` is not a canonical base64 encoding of 64 bytes, or does not verify under the bound wallet key	Sign with the provisioned wallet key; check the encoding
`RFQ_SIGNED_LIMIT_BELOW_REQUIREMENT`	`max_maker_fee` or `max_maker_locked_balance` is below the current requirement on one taker side at the signed `bid` and `ask`; the quote could never fill	Sign maxima at or above `maker_funding`’s `max_fee` and `max_locked_balance` plus your headroom; do not retry unchanged
`RFQ_MAKER_UNFUNDED`	Your subaccount has no covered on-chain anchor, so the venue cannot state your requirement; `data.details` carries the funding object	Deposit and wait for the anchor to be covered; do not retry unchanged
`RFQ_QUOTE_EXPIRED`	Fewer than 2 seconds of the quote’s life remained when it landed	Re-issue with a later `expires_at` while the request is still `pending`
`RFQ_SIDE_NOT_REQUESTED`	The quote priced a side the request’s `side` does not allow: a `bid` on a `buy` request or an `ask` on a `sell` request	Send only the requested side; the request is still open
`RFQ_INVALID_PARAMS`	The frame’s shape is wrong: a field is missing, unknown or of the wrong type, `quote_nonce` is not a decimal string, neither `bid` nor `ask` was sent, or a decline names an unknown reason	Fix the request shape; do not retry unchanged
`RFQ_VALUE_OUT_OF_RANGE`	A value parsed but breaks a bound: a decimal outside the signed 64-bit 6-decimal range, `bid > ask`, `issued_at >= expires_at`, the TTL exceeds 3600 seconds, or `expires_at` after `max_quote_expires_at`	Fix the value; the venue never clamps
`RFQ_PRECISION_UNSUPPORTED`	A decimal carries more than 6 fractional digits	Round to 6 decimals. A decimal that is not a canonical string, or is sent as a JSON number, is `RFQ_INVALID_PARAMS` or `RFQ_VALUE_OUT_OF_RANGE` instead
`RFQ_INVALID_INSTRUMENT`	A leg closed, halted, or went into settlement since the request opened	Do not retry; the request cannot fill
`RFQ_NOT_FOUND`	`rfq_id` names no request the venue knows	Check the id; a request purged at settlement is gone
`RFQ_RATE_LIMITED`	The 100-request account budget is spent for its current one-second fixed window	Back off until the current window turns over; the call was not admitted

What is not supported

There is no cancel and no replace of a delivered quote. A quote is firm until expires_at, and a second rfq.maker.respond on the same request returns RFQ_STATE_CONFLICT. Re-pricing means letting the quote expire, so the TTL is the only control over firmness.
The first firm quote wins and every later quote is refused. rfq.maker.decline with a reason ends the request at once instead of at the 5-second timeout.
A losing or late quote receives no push. Reserved risk is released on local timers per request and per delivered quote.
There are no partial fills. A package fills for its exact legs[] or not at all; a request that cannot be filled whole is declined with size_limit.
There is no maker read of live quotes over the socket. Each delivered quote must be recorded locally. rfq.maker.poll on reconnect returns what is still open, and GET /api/query/rfq-fills?role=maker is the record of fills.

Coming from Deribit Block RFQ? Migrating from Deribit maps the two surfaces method by method. Next: The Signed Quote

​Summary

​Lifecycle

​Connecting

​The open request

​Pricing a package

​Responding

​After quoting

​Reconciliation

​Errors

​What is not supported