Transaction safety

A firm quote is a ready-to-sign transaction. These checks keep users from signing the wrong thing or trading twice.

Before signing

Before the wallet signs execution.transaction, check:

1. expires is still in the future.
2. The connected wallet is on the returned chain_id.
3. The transaction target (to) is the Rave SettlementRouter for that chain (see Contracts). Do not substitute another address.
4. token_in allowance to the /v2/limits allowance_target, and the wallet balance, are sufficient.
5. If the side you routed was exact or the field was missing, at least amount_in must be
   available. If it was variable, Rave handles a short delivery. A missing field always means exact.
6. The quote was requested for the intended recipient, a wallet you control: the output tokens settle there.
7. to, data, value and chain_id go to the wallet unchanged. Never edit the transaction data client-side.
8. You record the transaction hash and nonce as soon as the wallet returns them, so you can reconcile if the broadcast errors.

If the user changes token_in, amount, recipient, chain or slippage, request a fresh firm quote.

Quote expiry

• If expires has passed and the packet was never broadcast, discard it and request a fresh firm quote.
• If the user rejected the signature request (EIP-1193 error code 4001), nothing was signed or sent: you may request a fresh firm quote. Treat every other wallet or RPC error, including one with no transaction hash, as a possible send and reconcile it first. A missing hash does not prove nothing was broadcast.
• GET /v2/quotes/{quote_id} tells you whether a firm quote is active, expired or executed.

After a broadcast error: reconcile before you retry

A broadcast error, an RPC timeout or a missing receipt does not mean the trade failed. The transaction may already be in the mempool or mined, and it can still settle. Every firm quote is a separate trade: the router only refuses to execute the same quote twice, so a new firm quote sent while the first transaction is still live can fill a second time and spend the user's funds twice.

Never re-broadcast and never request a new firm quote until you know the first transaction failed or was dropped. Reconcile first:

1. By transaction hash, if you have one: fetch the receipt. Success means the trade settled; stop and record it. A reverted receipt means it failed; you may re-quote.
2. By the quote: GET /v2/quotes/{quote_id}. executed means it settled; stop. active means the original packet may still land; keep waiting.
3. By the settlement record: GET /v2/transactions/{tx_hash} or GET /v2/executions?recipient=YOUR_WALLET_ADDRESS. A 404 straight after a send only means it is not indexed yet; poll with backoff.
4. By nonce, if you have no hash: compare the wallet's confirmed nonce with the nonce you signed. If the confirmed nonce has moved past it, find the transaction that used it before doing anything else.

The first transaction counts as failed or dropped only when its receipt shows a revert, or when all of these hold: the chain's latest block timestamp is past expires (allow a minute of margin; the API's expired status uses the server clock, and a transaction can still settle in a block stamped exactly at expires), no settlement is recorded, and the signed nonce is still unused or was used by a different transaction. To end the wait sooner, cancel the pending transaction with a replacement on the same nonce, and confirm it was mined before you re-quote. Do not resubmit the old packet: after expires it reverts.

API key handling

• Send API keys only from your backend. Keep them in a secret manager and inject them at request time.
• Never expose keys in browser code, mobile apps, public logs or support screenshots.
• Ask Rave to rotate a key if it may have been exposed.

What the API shares

Partner responses expose only what you need to price, display and submit a trade. The transaction packet (to, data, value, chain_id) is everything a wallet needs.