Guides
  1. Rave Trading API

Integration Guide

How to discover pairs, request quotes, run firm execution, and follow the trade lifecycle. For endpoint schemas and live examples see the API Reference.

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.
  • slippage_bps is optional. Omit for the default 50 bps (0.50%); set 0 only for exact binary fill.

Do not send V1 fields (asset, side, quote_asset) to V2 endpoints. Discover supported pairs at runtime — never hard-code a single asset or direction.

Base URL

The base URL already includes the /api prefix; write endpoints as relative /v2/... paths:

RAVE_API=https://api.rave-trading.com/api

GET /v2/assets resolves to https://api.rave-trading.com/api/v2/assets. Do not add another /api — $RAVE_API/api/v2/... would build a wrong .../api/api/v2/... URL. The OpenAPI document lists the full server https://api.rave-trading.com with /api/v2/... paths; the reference server is https://api.rave-trading.com/api with /v2/... paths. Both resolve to the same URLs.

https://rave-trading.com/api remains compatibility through the apex router; latency-sensitive RFQ, levels, and stream clients should use https://api.rave-trading.com/api. Use HTTP keep-alive for latency benchmarks.

Discovery flow

Before constructing any quote, discover the live universe. All endpoints below are relative to RAVE_API.

  1. Assets — GET /v2/assets returns every supported asset with chain variants, price, market, and per-chain quote_tokens. Use this to build your token picker.
  2. Limits — GET /v2/limits shows which buy/sell directions are quoteable per asset, raw min/max input bounds, chain-specific allowance_target, and session capacity (remaining_quotes, max_quotes). Pre-validate amounts here.
  3. Market levels — GET /v2/markets/levels gives the current pair books with bid/ask level grids. Filter by chain_id, base, and quote when you need one pair. allowance_target is not present here — read it from /v2/limits.
  4. Market status — GET /v2/markets/status tells you whether the market is open and which assets are tradable for the active session (or the next opening session when the market is closed, indicated by assetTradabilitySession).
  5. Stream — WSS /v2/stream delivers live prices and pair books at 1 Hz for apps that want updates without polling.

The API Reference has the full request/response schema for each endpoint. The examples below show the key fields and flow.

Quote flow

Soft quote (preview)

Request a non-binding indicative price:

curl -s "$RAVE_API/v2/quotes/soft" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "token_in": "0x55d398326f99059ff775485246999027b3197955",
  "token_out": "0x390a684ef9cade28a7ad0dfa61ab1eb3842618c4",
  "amount": "100000000000000000000",
  "chain_id": 56,
  "slippage_bps": 50
}
JSON

Response (soft quotes omit execution):

{
  "type": "soft_quote",
  "schema_version": 2,
  "quote_id": "550e8400-e29b-41d4-a716-446655440000",
  "token_in": { "symbol": "USDT", "address": "0x55d398326f99059ff775485246999027b3197955", "decimals": 18 },
  "token_out": { "symbol": "AAPLon", "address": "0x390a684ef9cade28a7ad0dfa61ab1eb3842618c4", "decimals": 18 },
  "amount_in": "100000000000000000000",
  "amount_out": "361500000000000000",
  "price": "276.625173",
  "expires": "2026-05-15T12:00:30Z",
  "valid_for_secs": 30,
  "slippage_bps": 50,
  "chain_id": 56
}

Common failure: 422 means the amount is outside the current min/max bounds — read /v2/limits and adjust. 503 means quoting is temporarily unavailable — retry later.

Firm quote (executable)

Same body as soft, with recipient required. Complete the allowance checklist below first.

curl -s "$RAVE_API/v2/quotes/firm" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "token_in": "0x55d398326f99059ff775485246999027b3197955",
  "token_out": "0x390a684ef9cade28a7ad0dfa61ab1eb3842618c4",
  "amount": "100000000000000000000",
  "chain_id": 56,
  "slippage_bps": 50,
  "recipient": "0x000000000000000000000000000000000000dEaD"
}
JSON

The response adds execution.transaction with to, data, value, and chain_id:

{
  "type": "firm_quote",
  "schema_version": 2,
  "quote_id": "550e8400-e29b-41d4-a716-446655440000",
  "token_in": { "symbol": "USDT", "address": "0x55d398326f99059ff775485246999027b3197955", "decimals": 18 },
  "token_out": { "symbol": "AAPLon", "address": "0x390a684ef9cade28a7ad0dfa61ab1eb3842618c4", "decimals": 18 },
  "amount_in": "100000000000000000000",
  "amount_out": "361500000000000000",
  "price": "276.625173",
  "expires": "2026-05-15T12:00:30Z",
  "valid_for_secs": 30,
  "slippage_bps": 50,
  "chain_id": 56,
  "execution": {
    "safety_label": "execution-preparatory",
    "transaction": { "to": "0xa53B869C883B5036dDf8D7a12B7618e4612C503e", "data": "0x...", "value": "0", "chain_id": 56 }
  }
}

Pass execution.transaction unchanged to the wallet/RPC.

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.

Firm-quote allowance checklist

Firm quotes settle on-chain, so the taker must have approved token_in to the router before the transaction can pull funds. Do this once per (token_in, chain_id, spender) and re-check when the required amount grows:

  1. Read the allowance target. GET /v2/limits and take assets[].sides.<buy|sell>.allowance_target for the asset on chain_id. This is the ERC-20 spender.
  2. Check current allowance. Read token_in.allowance(owner, allowance_target) on chain_id. If it is >= amount, skip to step 5.
  3. Approve. Send token_in.approve(allowance_target, amount) (or an amount you are comfortable pre-approving) on chain_id from the taker wallet.
  4. Wait for the approval receipt to confirm before requesting the firm quote.
  5. Request a fresh firm quote (POST /v2/quotes/firm) so expires and pricing are current.
  6. Submit execution.transaction calldata unchanged before expires.
# Allowance target for a symbol, per chain and side
curl -s "$RAVE_API/v2/limits" -H "Authorization: Bearer ***" \
  | jq '.assets[] | {symbol, chain_id, buy: .sides.buy.allowance_target, sell: .sides.sell.allowance_target}'

Never edit execution.transaction client-side. If the user changes token_in, amount, recipient, chain, or slippage, request a fresh firm quote.

Quote and transaction status

  • GET /v2/quotes/{quote_id} — recover quote state after refreshes or backend retries. Returns { status, quote }, where status is active or expired.
  • GET /v2/transactions/{id_or_tx_hash} — post-submit lifecycle by trade ID or on-chain hash.
  • GET /v2/executions?recipient=... — keyset-paginated settled history for one recipient wallet, newest first. recipient is required; there is no unscoped listing. Use next_cursor to continue paging.
{
  "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": "0x6b3e9a8c1f2d4e5a6b7c8d9e0f1a2b3c4d5e6f7a",
  "block_number": 41234567,
  "input": { "amount_raw": "100000000000000000000", "token": "0x55d398326f99059ff775485246999027b3197955" },
  "output": { "amount_raw": "361500000000000000", "token": "0x390a684ef9cade28a7ad0dfa61ab1eb3842618c4" },
  "explorer_url": "https://bscscan.com/tx/0x6b3e9a8c1f2d4e5a6b7c8d9e0f1a2b3c4d5e6f7a"
}

Ledger amounts are raw base units (amount_raw) plus the token address — render human-readable values with decimals from /v2/assets. If the quote has expired or been rejected, request a fresh one.

Limits and market sessions

  • GET /v2/limits is the pre-quote gate: it exposes per-side status, raw min_input_amount/max_input_amount, notional bounds, session remaining_quotes/max_quotes, and allowance_target. Validate the user's amount here before requesting a quote.
  • GET /v2/markets/status returns camelCase session state: isOpen, marketStatus, the nested public market snapshot, assetTradability for assetTradabilitySession, nextOpen/nextClose, and updatedAt. Gate your execution UI on isOpen and per-asset tradable.

Tokenized-equity markets have sessions (premarket, regular, postmarket, overnight). When the market is closed, assetTradability describes the next opening session, so surface nextOpen/nextOpenSession to set user expectations.

Price stream

Connect at wss://api.rave-trading.com/api/v2/stream with your API key in a header or auth message. Frames arrive at 1 Hz with type: "price_frame" and schema_version: 2. The server supports standard permessage-deflate compression (RFC 7692) when your WebSocket client offers it during the handshake — decompressed frames are identical to uncompressed ones.

Each frame contains:

  • prices[] — flat per-asset prices with symbol, address, bid, ask, max_size, min_size, and updated_at.
  • pairs[] — granular pair books with pair_id, chain_id, bid/ask level grids, size bounds, quoteability (session limits and per-side status), freshness (a { status, fetched_at, age_secs, ttl_secs } object where status = "fresh" means levels are backed by non-expired calibration/depth and status = "stale" means a bounded last-known-good calibration is being carried forward to avoid REST/WS pair flash-gaps while the engine refreshes upstream quotes), and valid_until. allowance_target is not included on stream quoteability — read it from /v2/limits.
  • pair_chunk — present when more than 64 pairs split across multiple frames (index / count). Collect all chunks and merge pairs to rebuild the full snapshot.
  • market_open and timestamp.

When a client cannot set WebSocket headers, proxy through your backend. On close or error, reconnect with exponential backoff and jitter, then rebuild pair state from fresh frames. Full auth, close-code, chunking, and reconnect details are on the Streaming reference.

Key rules

  • All amounts are raw base-unit strings. Use token.decimals from discovery to render human-readable values.
  • Multi-chain assets can appear once per chain_id. Key on (symbol, chain_id) or token.address, not symbol alone.
  • Soft quotes omit execution; only firm quotes include execution.transaction.
  • For complete schemas, default values, and live examples, use the API Reference section — every endpoint has pre-filled request bodies and response examples.

Updated 17 days ago

Did this page help you?