Quickstart

This walkthrough takes you from an API key to a settled trade. It uses curl and jq, and assumes you set RAVE_API as in Authentication:

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

1. Pick a pair

/v2/markets/levels lists the pairs that are quotable right now. This prints the open buy directions on BNB Smart Chain:

curl -s "$RAVE_API/v2/markets/levels?chain_id=56" \
  -H "Authorization: Bearer ***" \
  | jq -r '.pairs[] | select(.quoteability.buy.tradable) | [.base.symbol, .base.address, .base.decimals, .quote.symbol, .quote.address, .quote.decimals] | @tsv' \
  | head -5

Each line is base_symbol base_address base_decimals quote_symbol quote_address quote_decimals. A buy sends the quote token and receives the base token. A sell does the opposite. Export the direction you want:

export CHAIN_ID=56
export TOKEN_IN="0x..."   # the token the user sends (quote_address for a buy)
export TOKEN_OUT="0x..."  # the token the user receives (base_address for a buy)

2. Check limits

/v2/limits says whether the side is open, the size bounds, and which address to approve:

curl -s "$RAVE_API/v2/limits?symbol=BASE_SYMBOL&chain_id=$CHAIN_ID" \
  -H "Authorization: Bearer ***" \
  | jq '.assets[] | {symbol, chain_id: .token.chain_id, buy: .sides.buy | {status, tradable, min: .limits.min_input_amount, max: .limits.max_input_amount, allowance_target}}'

{
  "symbol": "BASE_SYMBOL",
  "chain_id": 56,
  "buy": {
    "status": "available",
    "tradable": true,
    "min": { "amount": "3", "decimals": 18, "token": "QUOTE_SYMBOL" },
    "max": { "amount": "499425.13494", "decimals": 18, "token": "QUOTE_SYMBOL" },
    "allowance_target": "0x..."
  }
}

Limit amounts are human-readable. Quote amounts are raw base units. Convert before you compare.

3. Get a soft quote

amount is the raw base-unit quantity of token_in, as a string. For a token with 18 decimals, 100 tokens is "100000000000000000000":

curl -s "$RAVE_API/v2/quotes/soft" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  --data "{\"token_in\":\"$TOKEN_IN\",\"token_out\":\"$TOKEN_OUT\",\"amount\":\"100000000000000000000\",\"chain_id\":$CHAIN_ID,\"slippage_bps\":50}"

{
  "type": "soft_quote",
  "schema_version": 2,
  "quote_id": "64ec0a6f-8d98-499f-a1b2-090dd2967dc5",
  "token_in": { "symbol": "TOKEN_IN", "address": "0x...", "decimals": 18 },
  "token_out": { "symbol": "TOKEN_OUT", "address": "0x...", "decimals": 18 },
  "amount_in": "100000000000000000000",
  "amount_out": "292558761888100307",
  "price": "341.81167350663256234402428564",
  "expires": "2026-09-26T11:09:47.855097475Z",
  "valid_for_secs": 60,
  "slippage_bps": 50,
  "chain_id": 56
}

A soft quote is a price only. It has no execution field and cannot be looked up later.

4. Approve the input token

From the taker wallet, approve token_in to the allowance_target from step 2, on the same chain, and wait for the receipt. See Approvals and settlement.

5. Get a firm quote

Send the same body plus recipient. recipient is your wallet address: the output tokens settle there. Replace YOUR_WALLET_ADDRESS with a wallet you control. Tokens sent to a wrong or burn address cannot be recovered.

curl -s "$RAVE_API/v2/quotes/firm" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  --data "{\"token_in\":\"$TOKEN_IN\",\"token_out\":\"$TOKEN_OUT\",\"amount\":\"100000000000000000000\",\"chain_id\":$CHAIN_ID,\"slippage_bps\":50,\"recipient\":\"YOUR_WALLET_ADDRESS\"}"

{
  "type": "firm_quote",
  "schema_version": 2,
  "quote_id": "550e8400-e29b-41d4-a716-446655440000",
  "token_in": { "symbol": "TOKEN_IN", "address": "0x...", "decimals": 18 },
  "token_out": { "symbol": "TOKEN_OUT", "address": "0x...", "decimals": 18 },
  "amount_in": "100000000000000000000",
  "amount_out": "292558761888100307",
  "price": "341.81167350663256234402428564",
  "expires": "2026-09-26T11:10:17Z",
  "valid_for_secs": 30,
  "slippage_bps": 50,
  "chain_id": 56,
  "execution": {
    "safety_label": "execution-preparatory",
    "transaction": { "to": "0x...", "data": "0x...", "value": "0", "chain_id": 56 }
  }
}

6. Submit and track

Send execution.transaction (to, data, value, chain_id) unchanged from the taker wallet before expires. Then follow the trade:

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

/v2/transactions/... returns 404 until the settlement is indexed. Poll with backoff. See Track trades.

Next steps

Integration Guide: the production checklist.
Quotes: every request field, retries, and common failures.
Transaction safety: what to check before the wallet signs.