Integration Guide

Mental model

• token_in is what the user sends.
• token_out is what the user receives.
• amount is the raw base-unit GM asset quantity. For buys, it is the desired token_out GM amount; for sells, it is the supplied token_in GM amount.
• chain_id is 56 for BNB Smart Chain. Ethereum (chain ID 1) and other EVM chains are coming soon.
• slippage_bps defaults to 10 when omitted.

Do not send V1 fields such as asset, side, or quote_asset to V2 endpoints.

Public endpoints

Request fields

POST /api/v2/quotes/soft and POST /api/v2/quotes/firm use the same base body.

Response fields

Soft and firm quote responses share the public quote fields below. Firm quotes additionally include execution.

execution.transaction contains the wallet/RPC packet: to, data, value, chain_id, and optional gas_estimate.

Asset fields

GET /api/v2/assets returns supported assets with these public fields:

Smart Contract Addresses

Asset contract addresses are available from the live /api/v2/assets endpoint (see the bsc_address field). For a machine-readable reference of all deployed contract addresses across chains, see the Smart Contracts page.

Health

curl -s "$RAVE_API/health"

Expected shape:

{ "status": "ok" }

Assets

curl -s "$RAVE_API/api/v2/assets" -H "Authorization: Bearer $RAVE_API_KEY"

Look up one asset by contract address:

curl -s "$RAVE_API/api/v2/assets/by-address/0x390a684ef9cade28a7ad0dfa61ab1eb3842618c4" -H "Authorization: Bearer $RAVE_API_KEY"

Soft quote

Soft quotes are non-binding and useful for pricing previews.

curl -s "$RAVE_API/api/v2/quotes/soft" -H "Authorization: Bearer $RAVE_API_KEY" -H "Content-Type: application/json" -d '{"token_in":"0x55d398326f99059ff775485246999027b3197955","token_out":"0x390a684ef9cade28a7ad0dfa61ab1eb3842618c4","amount":"1000000000000000000","chain_id":56}'

Expected shape:

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

Firm quote

Firm quotes require a recipient address and include the wallet/RPC transaction packet.

curl -s "$RAVE_API/api/v2/quotes/firm" -H "Authorization: Bearer $RAVE_API_KEY" -H "Content-Type: application/json" -d '{"token_in":"0x55d398326f99059ff775485246999027b3197955","token_out":"0x390a684ef9cade28a7ad0dfa61ab1eb3842618c4","amount":"1000000000000000000","chain_id":56,"recipient":"0x000000000000000000000000000000000000dEaD"}'

Before submitting, verify:

1. expires is still in the future.
2. The connected wallet is on chain_id 56.
3. Your UI displays token_out, amount_out, and price clearly.
4. execution.transaction.to, data, value, and chain_id are passed unchanged to the wallet/RPC call.

Trading limits

curl -s "$RAVE_API/api/v2/limits" -H "Authorization: Bearer $RAVE_API_KEY"

Returns per-asset trading limits including buy and sell sides with:

• max_notional_value / min_notional_value — USD-denominated order size bounds
• max_input_amount / min_input_amount — raw base-unit input bounds
• allowance_target — settlement contract address for token approval

Use /api/v2/limits to pre-validate order sizes before requesting quotes.

Market levels

curl -s "$RAVE_API/api/v2/markets/levels" -H "Authorization: Bearer $RAVE_API_KEY"

Returns full pair books for all supported assets. Filter with query parameters:

Filter by symbol only:

curl -s "$RAVE_API/api/v2/markets/levels?symbol=AAPLon" -H "Authorization: Bearer ***

Filter by exact chain/pair:

curl -s "$RAVE_API/api/v2/markets/levels?chain_id=56&base_token=0x390a684ef9cade28a7ad0dfa61ab1eb3842618c4&quote_token=0x55d398326f99059ff775485246999027b3197955" -H "Authorization: Bearer ***

Response envelope:

{
  "pairs": [ /* pair book objects (see table below) */ ],
  "market_open": true,
  "as_of": "2026-05-08T10:00:00Z"
}

Each pair includes pair_id, chain_id, base, quote, bids, asks, min_base_amount, max_base_amount, min_base_amount_raw, max_base_amount_raw, indicative, and valid_until. Bid/ask levels include level, base_amount, base_amount_raw, quote_amount, quote_amount_raw, and price.

Quote lookup

curl -s "$RAVE_API/api/v2/quotes/$QUOTE_ID" -H "Authorization: Bearer $RAVE_API_KEY"

Use quote lookup to recover state after refreshes or backend job retries. Request a fresh quote whenever the lookup indicates expiration or rejection.

Quote lookup returns the persisted public quote record. In addition to the V2 fields, it may include compatibility aliases such as asset, side, quote_asset, amount, total, amount_in_raw, and amount_out_raw; do not send those aliases in new V2 quote requests.

Price stream

Connect with the API key in a header when your WebSocket client supports custom headers:

wscat -c "wss://rave-trading.com/api/v2/stream" -H "Authorization: Bearer $RAVE_API_KEY"

When a client cannot set headers, connect from your backend and forward only the data your application needs.

Stream frames use schema_version: 2 and include two views of the market:

Flat prices (prices)

Every frame includes a prices array with one entry per asset. Each price item includes:

Market levels (pairs)

Every frame also includes a pairs array with granular level-based bid/ask books for every supported pair.

Each bid/ask level entry:

When there are more than 64 pairs, frames are chunked with pair_chunk: { index, count }. Clients reassemble the complete snapshot by collecting all chunks. The prices array is only included in the first chunk (index: 0).

Frame metadata

Level detail (REST)

For the same pair-book data via REST, use GET /api/v2/markets/levels.