1. CRX
  2. API reference
  3. RFQs
  4. Open a request for quotes

Open a request for quotes

POST/rfqs

Opens an RFQ and returns the winning quote when quoting closes, 5 seconds after the open. The RFQ stays open 120 seconds, until closes_at. Set your HTTP timeout to 30 seconds.

With no quote, quote is null and outcome says why. A quote outside the chain's off-market band never wins; if none remains, the RFQ ends cancelled with a reason.

Authentication

  • x-crx-address x-crx-ts x-crx-sig
  • x-crx-address x-crx-signer x-crx-ts x-crx-sig
  • x-crx-session

Request body

FieldTypeDescription
chain requiredstring

A chains[].key from GET /health, such as ethereum.

pair requiredstring

USDBRL or USD/BRL.

side requiredstring buy sell

buy or sell, for the base currency.

notional requiredstring

Amount in the base currency, up to 6 decimal places, within the GET /markets bounds.

expiry requiredintegerminimum 0

Maturity, within the GET /markets tenor.

premium_bpsinteger-10000 to 10000default 0

Upfront premium in basis points; positive if the taker pays. Within ±max_premium_bps (GET /markets). Defaults to 0.

quote_expiryintegerminimum 0

Latest quote expiry you accept, in Unix time (milliseconds). The answer's quote_expiry_max is the value applied.

client_rfq_idstringlength 1 to 128

Your RFQ ID: 1 to 128 printable ASCII characters. The same ID and terms, expiry included, return the existing RFQ until it settles, expires or is cancelled; other terms return 409 conflict.

settlement_fixingstring BRL_PTAX MXN_FIX PHP_BAP

Settle at an official fixing: BRL_PTAX (BCB PTAX) on USD/BRL, MXN_FIX (Banxico FIX) on USD/MXN, PHP_BAP (PHP BAP) on USD/PHP. The trade settles at the market price at expiry. A Fixing adjustment is paid when the official fixing gives the client a better result than the settlement price; otherwise none is due. Set expiry to the fixing time (GET /markets settlement.fixing) on a day the fixing is published, and open the RFQ before the fixing's observation period starts on that day. Otherwise the RFQ is refused with 400 fixing_unavailable. Omit for settlement at the market price. Quotes do not change.

Responses

200

The RFQ and its winning quote.

FieldTypeDescription
rfq_id requiredstring
client_rfq_id requiredstring or null

Your RFQ ID, or null if not sent.

kind requiredstring open
status requiredstring open quoted accepted opened settled expired cancelled
leg_id requiredstring

Your leg ID. The last 8 bytes are quote_expiry_max.

chain requiredstring

Chain key.

pair requiredstring

Pair in compact form, such as USDBRL.

notional requiredstring

Decimal string.

premium_bps requiredinteger

Premium in basis points; positive if the taker pays.

taker_refstring or null

The takerRef a maker's quote signs. null if the RFQ takes no quotes.

side requiredinteger 1 -1

Your side: 1 buys the base, -1 sells it.

expiry requiredintegerminimum 0

Unix time in milliseconds.

closes_at requiredintegerminimum 0

RFQ end, 120 seconds after the open. No accept after it.

quote_expiry_max requiredinteger

Latest quote expiry, in Unix time (seconds). The last 8 bytes of your ownLegId equal it.

quotes requiredarray of object

quote as a list, or empty. Read quote.

quotes[].quote_id requiredstring

Quote ID to send on accept.

quotes[].rate requiredstring

Quoted rate.

quotes[].expires_at requiredintegerminimum 0

Quote expiry, in Unix time (milliseconds).

quotes[].status requiredstring quoted expired accepted declined dropped

Only a quoted quote can win. dropped: withdrawn or replaced by the maker.

quotes[].pyth_spotstring

The pair's Pyth spot when the quote was posted, in the pair's orientation, 6 decimals. Omitted with no current spot.

quotes[].pyth_spot_atintegerminimum 0

The time of pyth_spot. Omitted with it.

quotes[].forward_pointsstring

rate minus pyth_spot, signed, 6 decimals: pyth_spot plus forward_points is rate. Omitted with pyth_spot.

quotes[].margin_impactobject

What this trade does to your margin: on a quote, your side at the quote's rate; on rfq.opened, a maker's own side at the RFQ's size. Omitted when CRX has no figure. The accept tests your collateral again.

quotes[].margin_impact.im_added requiredstring

The change in your initial margin the trade causes, USD, 6 decimals, signed. Negative when the trade offsets your positions.

quotes[].margin_impact.free_after requiredstring

Free collateral after the trade, USD, 6 decimals, taking that change, the trade's premium and any immediate mark loss.

quotes[].margin_impact.covered requiredboolean

Whether CRX's pre-trade collateral check lets the trade through. This check is stricter than free_after and a trade can read covered: false with free_after above zero.

quotes[].margin_impact.as_of requiredintegerminimum 0

The time of the figures.

quote requiredobject or null

The winning quote, or null. If null, read outcome, then open a new RFQ with a new client_rfq_id.

quote.quote_id requiredstring

Quote ID to send on accept.

quote.rate requiredstring

Quoted rate.

quote.expires_at requiredintegerminimum 0

Quote expiry, in Unix time (milliseconds).

quote.status requiredstring quoted expired accepted declined dropped

Only a quoted quote can win. dropped: withdrawn or replaced by the maker.

quote.pyth_spotstring

The pair's Pyth spot when the quote was posted, in the pair's orientation, 6 decimals. Omitted with no current spot.

quote.pyth_spot_atintegerminimum 0

The time of pyth_spot. Omitted with it.

quote.forward_pointsstring

rate minus pyth_spot, signed, 6 decimals: pyth_spot plus forward_points is rate. Omitted with pyth_spot.

quote.margin_impactobject

What this trade does to your margin: on a quote, your side at the quote's rate; on rfq.opened, a maker's own side at the RFQ's size. Omitted when CRX has no figure. The accept tests your collateral again.

quote.margin_impact.im_added requiredstring

The change in your initial margin the trade causes, USD, 6 decimals, signed. Negative when the trade offsets your positions.

quote.margin_impact.free_after requiredstring

Free collateral after the trade, USD, 6 decimals, taking that change, the trade's premium and any immediate mark loss.

quote.margin_impact.covered requiredboolean

Whether CRX's pre-trade collateral check lets the trade through. This check is stricter than free_after and a trade can read covered: false with free_after above zero.

quote.margin_impact.as_of requiredintegerminimum 0

The time of the figures.

quote.trade_templateobject

The Trade to sign to accept this quote, as an eth_signTypedData_v4 object in typed_data (see TradeTypedData).

Build your own Trade from your RFQ and this quote. Sign only if every check holds:

  1. Domain. name CRX, version rulebook-1.0; chainId and verifyingContract equal the chain_id and core that GET /health serves for your chain.
  2. Type. primaryType is Trade and types.Trade is exactly the Trade type string.
  3. Terms. pair, side, notionalE6 and maturity equal your RFQ; rateE6 equals the quote's rate; premiumBps equals your RFQ's premium_bps, within the chain's cap; summary is the line those fields format to.
  4. Leg ID. ownLegId bytes 24–31, big-endian, equal the RFQ's quote_expiry_max.
  5. Nonce. ownNonce is at most now + 24 hours, in Unix time (milliseconds).

Sign your own object with eth_signTypedData_v4 and send the 65-byte signature, low s and v 27 or 28, as sig to POST /rfqs/{rfq_id}/accept. A wallet that signs only a hash rebuilds the digest from typed_data and compares it with its own first. pairC and ownSalt are used as served.

quote.trade_template.typed_data requiredobject

The Trade, ready for eth_signTypedData_v4. Compare it with your own before signing.

An eth_signTypedData_v4 object; types holds EIP712Domain and the struct. In message, integers are decimal strings, and bytes32 values and addresses are lowercase 0x hex. chainId is a number. Compare parsed values, not bytes. Domain: name CRX, version rulebook-1.0, and the chain_id and core from GET /health.

quote.trade_template.typed_data.types requiredobject
quote.trade_template.typed_data.primaryType requiredstring

Trade, or Quote for a maker.

quote.trade_template.typed_data.domain requiredobject
quote.trade_template.typed_data.message requiredobject

The struct's fields. For Trade, see TradeTypedData; for Quote, QuoteTypedData.

reasonstring

Cancel reason: rate_out_of_band or mark_unavailable (no quote passed the price check), or position_matured (close rounds only).

price_expected_byintegerminimum 0

Time the next price is expected. Present only on a mark_unavailable cancel during a price update.

price_expected_by_atstring

price_expected_by as ISO 8601 UTC.

outcomestring

Why quote is null, such as no_quote, or why the RFQ ended without a trade. Omitted otherwise.

messagestring

Text to show the user. On a cancel with reason rate_out_of_band, mark_unavailable or position_matured, it states why no quote remained.

400

bad_request, notional_below_minimum, notional_above_maximum, invalid_signature. fixing_unavailable: CRX does not offer settlement at the requested fixing for this pair, expiry or account now; message says why.

code bad_request notional_below_minimum notional_above_maximum invalid_signature fixing_unavailable

401

unauthorized: a header is missing or malformed, x-crx-ts is out of range, the call was already used, the signature does not match, or the caller lacks access.

code unauthorized

403

not_whitelisted: the account is not approved for this call. setup_pending: the account is approved and its setup is in progress. seat_cannot_sign: the account wallet cannot sign trades. Contract wallets such as a Safe are refused; an EOA with an EIP-7702 delegation is accepted.

code not_whitelisted setup_pending seat_cannot_sign

408

timeout: no answer within 30 seconds. Resend with the same client_rfq_id and terms.

code timeout

409

conflict: the same client_rfq_id with other terms. market_paused: the pair accepts no new RFQs. platform_paused: CRX is paused.

code conflict market_paused platform_paused

413

payload_too_large: the body is over 2 MiB.

code payload_too_large

415

unsupported_media_type: send content-type: application/json.

code unsupported_media_type

422

unprocessable_entity: a field has the wrong type. insufficient_collateral: free collateral does not cover the margin this trade adds; details carries side, required and available in USD. expiry_outside_hours, expiry_past_fence: the expiry is outside the hours CRX accepts, or past its latest date. expiry_after_delist: the expiry is at or after delisting_at on GET /markets.

code unprocessable_entity insufficient_collateral expiry_outside_hours expiry_past_fence expiry_after_delist

429

rate_limited: retry after Retry-After seconds.

code rate_limited

HeaderTypeDescription
Retry-Afterinteger

Seconds until the next call is accepted.

ratelimit-limitinteger

Maximum calls in a burst.

ratelimit-remaininginteger

Calls remaining before the limit.

ratelimit-resetinteger

Seconds until the full limit is restored.

ratelimit-refillinteger

Calls restored per minute.

502

upstream: a chain read failed. Retry shortly.

code upstream

503

collateral_unverified: no current collateral figure; retry shortly. withdraw_pending: a pending withdrawal blocks the collateral check; details carries step, reason (withdraw_unconfirmed or withdraw_above_free), expected_by and expected_by_at. Retry after expected_by_at.

code collateral_unverified withdraw_pending

Schemas

TradeTypedData

The Trade struct, one line, no space after a comma:

Trade(string summary,string pair,string side,uint256 notionalE6,uint64 rateE6,int16 premiumBps,uint40 maturity,bytes32 pairC,bytes32 ownLegId,uint64 ownNonce,bytes32 ownSalt)

Typehash 0x2a4f432dd51178481baaacab72453a149e29560e5d366c2ebb93bb767fab4630. Build each field from your own RFQ and the quote:

FieldFromForm
summarythe fields belowone line, rules below
pairthe RFQ pairslash form, USDBRL → USD/BRL
sidethe RFQ side1 → buy, -1 → sell: your side, in the first currency
notionalE6the RFQ notional× 10^6, exact; refuse more than 6 decimal places
rateE6the quote rate× 10^6, exact
premiumBpsthe RFQ premium_bpssigned. Positive: you pay
maturitythe RFQ expiryUnix time in seconds, floor(expiry / 1000)
pairC, ownSaltthe templateas served
ownLegIdthe templatebytes 24–31 equal the RFQ's quote_expiry_max
ownNoncethe templateat most now + 24 hours, Unix time in milliseconds

summary: <side> <size> <BASE> vs <QUOTE> at <rate> <QUOTE> per <BASE>, matures <date>, upfront <up>. <size> and <rate> are the integer part, then . and the fraction with trailing zeros cut (no . when whole). <size> groups thousands with one space; <rate> is not grouped. <date> is YYYY-MM-DDTHH:MM:SSZ, UTC. <up> is none, taker pays <P> % or maker pays <P> %. <P> is the premium in basis points / 100, with two decimal places. ASCII only, one space between words, no trailing space.

QuoteTypedData

The Quote a maker signs for POST /rfqs/{rfq_id}/quotes, as an eth_signTypedData_v4 object (see TypedData). The struct, one line, no space after a comma:

Quote(address seat,bytes32 legId,bytes32 pair,int8 side,uint256 notional,uint64 rate,int16 premiumBps,uint40 expiry,uint64 nonce,bytes32 salt,bytes32 takerRef)

Typehash 0x00fc8b1401eebfc809c01d3a7351526ef07cfd5902793c3d279de280c0aec2cb. Domain: name CRX, version rulebook-1.0, and the chain_id and core from GET /health, whose chains[].domain is the separator. Build each field from the RFQ and your quote:

FieldFromForm
seatyour accountx-crx-address
legIdyour leg_id24 random bytes, then quote_expiry_max as 8 bytes big endian
pairthe RFQ pairkeccak256 of the slash form: USDBRL → keccak256("USD/BRL")
sidethe RFQ sideyour side, as the RFQ shows it to you: 1 long base, -1 short
notionalthe RFQ notional× 10^6, exact
rateyour rate× 10^6, exact; refuse more than 6 decimal places
premiumBpsthe RFQ premium_bpssigned
expirythe RFQ expiryUnix time in seconds, floor(expiry / 1000)
nonceyour leg_idbytes 16–23, big endian. The body does not send it
saltyour saltas sent
takerRefthe RFQ taker_refas served

Test vector on chain ID 1, with an example core that is not deployed. This schema's example is its typed data; the request example of POST /rfqs/{rfq_id}/quotes is its body.

seat          0x70997970C51812dc3A010C7d01b50e0d17dc79C8
legId         0x555555555555555555555555555555555555555555555555000000006ab13dd8
pair          0x644668ae48a22c7afafcf35ff66ebf9c8af2c396ae03de0795d66bde06cdf851 (keccak256("USD/BRL"))
side          -1
notional      5000000000000
rate          5410000
premiumBps    0
expiry        1798732800
nonce         6148914691236517205
salt          0x6161616161616161616161616161616161616161616161616161616161616161
takerRef      0x4f412fb92304015b744b7a32155b5879b48aa8cbb0076b8234640f8891c53b0b
              (taker account 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266,
              taker leg id 0x111111111111111111111111111111111111111111111111000000006ab13dd8)
chainId       1
core          0x1111111111111111111111111111111111111111

domain        0xc10b07f28873cb547d1ab61e8cacb2c0084fc537ac932f55d21f403a0194785c
structHash    0xfc12020df46e5a207618f5dd4b960ca5dfb75bc5f279d0b168355b5402cbd089
digest        0x66ed64dcb1c180844db51855479f4be2557a3686c64da3c2474f261b4d59d3fc
sig           0xa060dd5965ab39968e1e6f5772969e8617ab2de88eb069e6bee0b67dc07b19600d52812d18a34fa708bbee1755ba6e4d74953120d4e0af7e6b14911510cba9131c
              (signed by the seat: the public anvil test key 1)
{
  "domain": {
    "chainId": 1,
    "name": "CRX",
    "verifyingContract": "0x1111111111111111111111111111111111111111",
    "version": "rulebook-1.0"
  },
  "message": {
    "expiry": "1798732800",
    "legId": "0x555555555555555555555555555555555555555555555555000000006ab13dd8",
    "nonce": "6148914691236517205",
    "notional": "5000000000000",
    "pair": "0x644668ae48a22c7afafcf35ff66ebf9c8af2c396ae03de0795d66bde06cdf851",
    "premiumBps": "0",
    "rate": "5410000",
    "salt": "0x6161616161616161616161616161616161616161616161616161616161616161",
    "seat": "0x70997970c51812dc3a010c7d01b50e0d17dc79c8",
    "side": "-1",
    "takerRef": "0x4f412fb92304015b744b7a32155b5879b48aa8cbb0076b8234640f8891c53b0b"
  },
  "primaryType": "Quote",
  "types": {
    "EIP712Domain": [
      {
        "name": "name",
        "type": "string"
      },
      {
        "name": "version",
        "type": "string"
      },
      {
        "name": "chainId",
        "type": "uint256"
      },
      {
        "name": "verifyingContract",
        "type": "address"
      }
    ],
    "Quote": [
      {
        "name": "seat",
        "type": "address"
      },
      {
        "name": "legId",
        "type": "bytes32"
      },
      {
        "name": "pair",
        "type": "bytes32"
      },
      {
        "name": "side",
        "type": "int8"
      },
      {
        "name": "notional",
        "type": "uint256"
      },
      {
        "name": "rate",
        "type": "uint64"
      },
      {
        "name": "premiumBps",
        "type": "int16"
      },
      {
        "name": "expiry",
        "type": "uint40"
      },
      {
        "name": "nonce",
        "type": "uint64"
      },
      {
        "name": "salt",
        "type": "bytes32"
      },
      {
        "name": "takerRef",
        "type": "bytes32"
      }
    ]
  }
}

TradeTemplate

{
  "typed_data": {
    "domain": {
      "chainId": 1,
      "name": "CRX",
      "verifyingContract": "<core>",
      "version": "rulebook-1.0"
    },
    "message": {
      "maturity": "1798732800",
      "notionalE6": "5000000000000",
      "ownLegId": "0x111111111111111111111111111111111111111111111111000000006ab13dd8",
      "ownNonce": "1790000000123",
      "ownSalt": "0x3131313131313131313131313131313131313131313131313131313131313131",
      "pair": "USD/BRL",
      "pairC": "0x3bb28decf99b625916b2a3c41517a2035273e731a71df7b0e9d5c115ce899795",
      "premiumBps": "0",
      "rateE6": "5410000",
      "side": "buy",
      "summary": "buy 5 000 000 USD vs BRL at 5.41 BRL per USD, matures 2026-12-31T16:00:00Z, upfront none"
    },
    "primaryType": "Trade",
    "types": {
      "EIP712Domain": [
        {
          "name": "name",
          "type": "string"
        },
        {
          "name": "version",
          "type": "string"
        },
        {
          "name": "chainId",
          "type": "uint256"
        },
        {
          "name": "verifyingContract",
          "type": "address"
        }
      ],
      "Trade": [
        {
          "name": "summary",
          "type": "string"
        },
        {
          "name": "pair",
          "type": "string"
        },
        {
          "name": "side",
          "type": "string"
        },
        {
          "name": "notionalE6",
          "type": "uint256"
        },
        {
          "name": "rateE6",
          "type": "uint64"
        },
        {
          "name": "premiumBps",
          "type": "int16"
        },
        {
          "name": "maturity",
          "type": "uint40"
        },
        {
          "name": "pairC",
          "type": "bytes32"
        },
        {
          "name": "ownLegId",
          "type": "bytes32"
        },
        {
          "name": "ownNonce",
          "type": "uint64"
        },
        {
          "name": "ownSalt",
          "type": "bytes32"
        }
      ]
    }
  }
}