Quickstart

This guide takes you from zero to your first order. You will read public market data (no credentials), sign in with your wallet, move collateral into a venue, and place a trade. All requests go through the API gateway, referred to here as {BASE_URL}.

Prices and sizes are decimal strings. Send and parse them as strings to keep full precision.

1. Read public market data

No authentication is needed for market data. List the linear markets and pull a book snapshot.

# list perp / futures / spot markets
curl -s "{BASE_URL}/perps/markets"

# order book snapshot for one market
curl -s "{BASE_URL}/perps/orderbook/BTC-PERP?depth=10"

# 24h ticker: mark, change, volume, open interest, funding
curl -s "{BASE_URL}/perps/market-stats?marketId=BTC-PERP"

const markets = await fetch(`${BASE_URL}/perps/markets`).then(r => r.json());
const book = await fetch(
  `${BASE_URL}/perps/orderbook/BTC-PERP?depth=10`,
).then(r => r.json());
console.log(markets[0], book.bids[0], book.asks[0]);

Example market-stats response:

{
  "marketId": "BTC-PERP",
  "baseSymbol": "BTC",
  "markPrice": "68210.5",
  "change24hPct": "1.42",
  "volume24hUsd": "18422100",
  "openInterestUsd": "9231000",
  "funding1hPct": "0.0021"
}

For live values, subscribe to the SSE stream {BASE_URL}/perps/book-stream?marketId=BTC-PERP instead of polling — it pushes a snapshot then incremental updates.

Open a session with SIWE. Request a nonce, sign the message in your wallet, then verify. See Authentication for the full flow.

NONCE=$(curl -s -X POST {BASE_URL}/auth/nonce \
  -H 'Content-Type: application/json' \
  -d '{"walletAddress":"0xabc..."}' | jq -r .nonce)

# build + sign the SIWE message with $NONCE → $MSG, $SIG
curl -s -c cookies.txt -X POST {BASE_URL}/auth/siwe \
  -H 'Content-Type: application/json' \
  -d "{\"message\":\"$MSG\",\"signature\":\"$SIG\"}"

The -c cookies.txt jar now holds your session cookie; pass -b cookies.txt on authenticated calls.

3. Fund a venue

Deposits land in your wallet bucket. Move collateral into the venue you want to trade — here, perps.

Check your balances

curl -s -b cookies.txt {BASE_URL}/wallet/balance

{ "walletBalance": "2000.00", "perpsBalance": "0", "optionsBalance": "0", "pendingWithdrawalTotal": "0" }

Transfer wallet → perps

curl -s -b cookies.txt -X POST {BASE_URL}/wallet/transfer \
  -H 'Content-Type: application/json' \
  -d '{"from":"wallet","to":"perps","amount":"500"}'

Transfers are atomic. Move funds back to wallet before withdrawing.

4. Preview, then place your first order

Always dry-run first. preview returns your notional, estimated fee, fee role, your volume tier, and whether the order passes the margin check — with no side effects.

# dry-run
curl -s -b cookies.txt -X POST {BASE_URL}/perps/orders/preview \
  -H 'Content-Type: application/json' \
  -d '{"marketId":"BTC-PERP","side":"buy","type":"limit","price":"68000","quantity":"0.05"}'

# place a post-only limit order
curl -s -b cookies.txt -X POST {BASE_URL}/perps/orders \
  -H 'Content-Type: application/json' \
  -d '{"marketId":"BTC-PERP","side":"buy","type":"limit","price":"68000","quantity":"0.05","timeInForce":"gtc","postOnly":true,"clientOrderId":"my-first-order"}'

const order = await fetch(`${BASE_URL}/perps/orders`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  credentials: "include",
  body: JSON.stringify({
    marketId: "BTC-PERP",
    side: "buy",
    type: "limit",
    price: "68000",
    quantity: "0.05",
    timeInForce: "gtc",
    postOnly: true,
    clientOrderId: "my-first-order",
  }),
}).then(r => r.json());

Use clientOrderId for idempotent client-side tracking. postOnly keeps you on the maker side (the order is rejected if it would take liquidity), and reduceOnly prevents an order from increasing your position.

5. Watch your orders, positions, and fills

curl -s -b cookies.txt "{BASE_URL}/perps/orders/open"
curl -s -b cookies.txt "{BASE_URL}/perps/positions"
curl -s -b cookies.txt "{BASE_URL}/perps/trades"

// live: book + your fills + your positions for one market
const es = new EventSource(
  `${BASE_URL}/perps/stream/events?marketId=BTC-PERP`,
  { withCredentials: true },
);
es.addEventListener("snapshot", e => init(JSON.parse(e.data).payload));
es.addEventListener("delta",    e => apply(JSON.parse(e.data).payload));

To exit, cancel resting orders or close the position:

curl -s -b cookies.txt -X POST {BASE_URL}/perps/orders/cancel-all \
  -H 'Content-Type: application/json' -d '{"marketId":"BTC-PERP"}'

curl -s -b cookies.txt -X POST {BASE_URL}/perps/positions/close \
  -H 'Content-Type: application/json' -d '{"marketId":"BTC-PERP"}'

Next steps

Authentication & API keys

Provision scoped keys for bots and market makers.

Methodology

Understand marks, funding, and the options surface.

Architecture

See how the gateway, engines, and streams fit together.

Market data API

Pull the option board, order books, and marks over REST.

Get started

Trading concepts

Methodology

Quickstart

1. Read public market data

3. Fund a venue

4. Preview, then place your first order

5. Watch your orders, positions, and fills

Next steps

Authentication & API keys

Methodology

Architecture

Market data API

​1. Read public market data

​2. Sign in with your wallet

​3. Fund a venue

​4. Preview, then place your first order

​5. Watch your orders, positions, and fills

​Next steps

Authentication & API keys

Methodology

Architecture

Market data API

1. Read public market data

2. Sign in with your wallet

3. Fund a venue

4. Preview, then place your first order

5. Watch your orders, positions, and fills

Next steps