Integration Guide

This page is the checklist for a production integration. Each step links to the page with the detail. If you have not made a first quote yet, start with the Quickstart.

Mental model

token_in is what the user sends; token_out is what the user receives.
amount is the raw base-unit quantity of token_in. Convert with token_in.decimals from discovery.
chain_id is the settlement chain for both token addresses.
recipient (firm quotes only) is the wallet where the output settles.
Discover pairs at runtime, and never hard-code a single asset, direction, chain or decimals value.

Discovery

Step	Endpoint	Detail
Build the token list	`GET /v2/assets`	Markets and limits
Find quotable pairs and depth	`GET /v2/markets/levels` or the stream	Markets and limits
Gate size and read the spender	`GET /v2/limits`	Markets and limits
Show session state	`GET /v2/markets/status`	Markets and limits

For live prices, prefer the price stream over polling levels.

Quote and execute

Soft quote for display

POST /v2/quotes/soft with token_in, token_out, amount, chain_id and optional slippage_bps. It returns a price and no transaction. See Quotes.

Firm quote for execution

Make sure the taker approved token_in to the /v2/limits allowance_target (Approvals and settlement).
POST /v2/quotes/firm with the same body plus recipient, and a fresh quote_attempt_id for safe retries (Quotes).
Run the transaction safety checklist.
Submit execution.transaction unchanged before expires.

Transaction status

Record the transaction hash and nonce as soon as the wallet returns them. Track with GET /v2/transactions/{id_or_tx_hash} and GET /v2/executions?recipient=... (Track trades). After any broadcast error, reconcile before you retry (Transaction safety).

Funding a firm quote from another trade

If a Rave leg is funded from an earlier hop, route it only when that side's levels
input_capability.mode is "variable". Rave handles a short delivery on that side. You do not
compute a funding floor.

When mode is "exact", the field is absent, or you do not recognise it, the full amount_in must be available.
Anything below it reverts; if more is available, settlement takes
only amount_in and leaves the surplus with the caller.

Build the path from levels. Request a firm quote for the size you already chose. Submit
execution.transaction unchanged. Full field reference is in Variable Input.

Errors and retries

Branch on HTTP status, not on the error string. Retry 429, 500 and 503 with backoff and jitter; fix the input for 400, 401, 422 and a 404 for an unpublished pair. A 404 from /v2/transactions only means the trade is not indexed yet: poll with backoff. See Errors.

Firm quote allowance checklist

Approve allowance_target from /v2/limits for at least amount_in before requesting the firm quote. Details are in Approvals and settlement.

Go-live checklist

API key used from the backend only; stream relayed through your backend.
Pairs, chains, decimals and spenders read from the API, never hard-coded.
Amounts converted with the decimals for the exact token address and chain.
Side gated on tradable before requesting a firm quote.
Approval confirmed before the firm quote.
recipient is the user's wallet, never a placeholder or burn address.
Packet submitted unchanged, on the returned chain_id, before expires.
Broadcast errors reconciled before any re-quote.
exact sides never placed behind a hop whose output can land short.