Skip to main content

​
GET /v1/orderbook

Returns real-time L2 orderbook data for a specific symbol on a specific exchange. Includes computed spread and mid-price.

​
Query Parameters

​
symbol
string
required
Trading pair. Base assets (e.g., BTC, ETH, DOGE, AVAX) are auto-appended with USDT. Full pair names also accepted (BTCUSDT, BTC-USDT-SWAP, BTC_USDT).
​
exchange
string
required
Exchange ID. Must be a registered exchange with orderbook support. See V2 Exchanges for the full list.
​
depth
integer
default:"20"
Number of price levels per side (bids/asks).

​
Example

curl "https://api.crypton.dev/v1/orderbook?symbol=BTC&exchange=binance&depth=5"

{
  "status": "ok",
  "timestamp": 1709640000000,
  "data": {
    "exchange": "binance",
    "symbol": "BTCUSDT",
    "bids": [
      { "price": 71000.00, "quantity": 1.500 },
      { "price": 70999.50, "quantity": 2.300 },
      { "price": 70999.00, "quantity": 0.750 }
    ],
    "asks": [
      { "price": 71001.00, "quantity": 1.200 },
      { "price": 71001.50, "quantity": 3.100 },
      { "price": 71002.00, "quantity": 0.500 }
    ],
    "spread_pct": 0.0014,
    "mid_price": 71000.50,
    "timestamp": 1709640000000
  }
}

​
Response Fields

​
data.exchange
string
Exchange that provided the data.
​
data.symbol
string
Full symbol as sent to the exchange.
​
data.bids
array
Buy orders sorted by price descending (best bid first).
​
data.asks
array
Sell orders sorted by price ascending (best ask first). Same structure as bids.
​
data.spread_pct
number
Bid-ask spread as a percentage of mid price: (best_ask - best_bid) / mid_price × 100. Returns 0 if mid price is 0.
​
data.mid_price
number
Midpoint price: (best_bid + best_ask) / 2. Returns 0 if either side is empty.

​
Error Responses

StatusCondition
404Exchange not found in registry
400Exchange doesn’t support orderbook data
502Upstream exchange API error

​
Symbol Auto-Detection

The endpoint intelligently appends USDT when the input looks like a base asset:
InputResolvedRule
BTCBTCUSDTNo pair suffix detected
DOGEDOGEUSDTWorks for any length
BTCUSDTBTCUSDTAlready has USDT
BTCUSDBTCUSDHas USD suffix
BTC-USDT-SWAPBTC-USDT-SWAPOKX format preserved
BTC_USDTBTC_USDTGate format preserved

​
Field Reference

FieldTypeDescriptionGranularityExample
exchangestringExchange that provided the orderbook snapshot—"binance"
symbolstringFull symbol as sent to the exchange—"BTCUSDT"
bids[].pricenumberBid price level in USD (descending order)Real-time snapshot71000.00
bids[].quantitynumberOrder quantity at this bid level (base asset)Real-time snapshot1.500
asks[].pricenumberAsk price level in USD (ascending order)Real-time snapshot71001.00
asks[].quantitynumberOrder quantity at this ask level (base asset)Real-time snapshot1.200
spread_pctnumberBid-ask spread as % of mid priceComputed per request0.0014
mid_pricenumberMidpoint: (best_bid + best_ask) / 2Computed per request71000.50

​
Data Sources

Orderbook data fetched directly from each exchange’s REST API in real-time (no caching). Supported on 17 exchanges: Binance, Binance US, Binance COIN-M, BingX, Tokocrypto, Bitget, MEXC, OKX, Bybit, Bybit Spot, Gate.io, KuCoin, KuCoin Futures, Bitfinex, BitMEX, Deribit, Coinbase, Coinbase International, Hyperliquid, dYdX. Depth limited to 20/50 levels depending on exchange API.

​
Live Testing

# Binance BTC orderbook (5 levels)
curl -s "https://api.crypton.dev/v1/orderbook?symbol=BTC&exchange=binance&depth=5" | jq .

# Hyperliquid ETH orderbook
curl -s "https://api.crypton.dev/v1/orderbook?symbol=ETH&exchange=hyperliquid&depth=10" | jq .