Track trades

Three endpoints follow a trade after the firm quote:

Endpoint	Use it for	Before settlement
`GET /v2/quotes/{quote_id}`	Recover firm-quote state after a refresh or retry	`status` is `active` or `expired`
`GET /v2/transactions/{id_or_tx_hash}`	The settled trade, by trade ID or transaction hash	`404` until indexed. Poll with backoff
`GET /v2/executions?recipient=0x...`	A wallet's settled history, newest first	Empty list

Trial access scope

For trial keys, transaction lookup and wallet history include only trades quoted through that trial access. A known transaction from outside that scope returns the same 404 as an unknown transaction; wallet-history counts and pagination cover only the permitted records. A wallet address or transaction hash alone does not widen trial access. If trial access cannot be verified, the API returns 503 instead of exposing records; retry with backoff.

Quote status

GET /v2/quotes/{quote_id} returns { "status": "active" | "expired" | "executed", "quote": { ... } }. Executed quotes also carry execution_record. Unknown IDs, including soft-quote IDs, return 404.

Transaction record

curl -s "$RAVE_API/v2/transactions/TX_HASH_OR_TRADE_ID" -H "Authorization: Bearer ***"

{
  "type": "trade_execution",
  "schema_version": 1,
  "trade_id": "550e8400-e29b-41d4-a716-446655440001",
  "quote_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "confirmed",
  "chain_id": 56,
  "side": "buy",
  "tx_hash": "0xabababababababababababababababababababababababababababababababab",
  "block_number": 41234567,
  "input": { "amount_raw": "100000000000000000000", "token": "0x55d398326f99059ff775485246999027b3197955" },
  "output": { "amount_raw": "361500000000000000", "token": "0x390a684ef9cade28a7ad0dfa61ab1eb3842618c4" },
  "explorer_url": "https://bscscan.com/tx/0xabababababababababababababababababababababababababababababababab"
}

Before the settlement is indexed the API returns 404 with { "error": "transaction not found" }.

Numeric ledger amounts are raw base units (amount_raw) plus the token address. Render them with decimals from /v2/assets.

A sell record can return output.amount_raw: "unknown" when its transaction receipt does not establish a unique delivery amount. Display the amount as unknown, not zero, and do not substitute the quote amount or a gross settlement amount. status: "confirmed" means the settlement was indexed, not that an unknown amount became measurable. This also applies to execution_record on quote lookup and to wallet-history entries.

For sell records with receipt-backed delivery evidence, the numeric output is the net amount delivered to the recipient after the retained fee. Older records can retain their original event-derived amounts; do not assume all historical sell records prove net delivery.

Wallet history

curl -s "$RAVE_API/v2/executions?recipient=YOUR_WALLET_ADDRESS&limit=20" -H "Authorization: Bearer ***"

{
  "type": "wallet_executions",
  "schema_version": 1,
  "recipient": "YOUR_WALLET_ADDRESS",
  "executions": [],
  "total": 0,
  "truncated": false,
  "next_cursor": null
}

recipient is required; without it the API returns a plain-text 400. Optional: chain_id, limit, cursor. Pass next_cursor as cursor to read the next page. Each executions[] item has the same shape as the transaction record.