Orderbook Data (ob )

Orderbook Data (ob_) is a read-focused API surface that provides access to markets and orderbook activity without requiring clients to run their own indexer or interact with the orderbook contracts directly. It is powered by a native indexer built into the Pod protocol, ensuring fast, consistent, and up-to-date views of on-chain state.

The API exposes live orderbook snapshots, historical OHLCV candles, account-level order history and positions, making it ideal for trading interfaces, analytics, and monitoring services.

📝 This is a JSON-RPC 2.0 API. The request path is not important; the method to execute is defined by the method field in the request body. You can send all requests to /, and any path after / is optional and used only for documentation clarity.

Get All Markets

post

Retrieves a list of all available markets/orderbooks with their metadata and statistics. Each market includes token information, current pricing, 24-hour statistics, and fee structure.

Body

jsonrpcstringRequiredDefault: 2.0

methodstringRequiredDefault: ob_getMarkets

idintegerRequiredDefault: 1

paramsarrayOptionalDefault: []

Responses

200

Array of market objects with metadata and statistics

application/json

jsonrpcstringOptional

idintegerOptional

post/ob_getMarkets

POST /ob_getMarkets HTTP/1.1
Host: rpc.podtestnet.dev/
Content-Type: application/json
Accept: */*
Content-Length: 61

{
  "jsonrpc": "2.0",
  "method": "ob_getMarkets",
  "params": [],
  "id": 1
}

200

Array of market objects with metadata and statistics

{
  "jsonrpc": "2.0",
  "result": [
    {
      "id": "0x0000000000000000000000000000000000000000000000000000000000000001",
      "name": "NVDAx/USD",
      "base_token_address": "0x0000000000000000000000000000000000000001",
      "quote_token_address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
      "base_token_symbol": "NVDAx",
      "quote_token_symbol": "USD",
      "base_token_name": "Nvidia",
      "quote_token_name": "USD",
      "market_type": "spot",
      "last_clearing_price": "0x6f05b59d3b200000",
      "auction_interval": 500000,
      "volume_24h": "0x2386f26fc10000",
      "high_24h": "0x1158e460913d00000",
      "low_24h": "0x6f05b59d3b200000",
      "price_change_24h": 0,
      "maker_fee": "0x0",
      "taker_fee": "0x0",
      "tick_precision": "0x1",
      "lot_size": "0x1",
      "max_leverage": 1,
      "oracle_price": null,
      "mark_price": null,
      "funding_rate": null,
      "funding_index": null,
      "funding_last_updated": null,
      "open_interest": null
    },
    {
      "id": "0x0000000000000000000000000000000000000000000000000000000000000007",
      "name": "NVDA/USD",
      "base_token_address": "0x0000000000000000000000000000000000000007",
      "quote_token_address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
      "base_token_symbol": "NVDA",
      "quote_token_symbol": "USD",
      "base_token_name": "Nvidia Perpetual",
      "quote_token_name": "USD",
      "market_type": "perpetual",
      "last_clearing_price": "0x796e3ea3f8ab00000",
      "auction_interval": 500000,
      "volume_24h": "0x0",
      "high_24h": "0x0",
      "low_24h": "0x0",
      "price_change_24h": 0,
      "maker_fee": "0x0",
      "taker_fee": "0x0",
      "tick_precision": "0x1",
      "lot_size": "0x1",
      "max_leverage": 20,
      "oracle_price": "0x796e3ea3f8ab00000",
      "mark_price": "0x796e3ea3f8ab00000",
      "funding_rate": "0",
      "funding_index": "0",
      "funding_last_updated": 1704153600000000,
      "open_interest": "0x0"
    }
  ],
  "id": 1
}

Get Orderbook Snapshot

post

Retrieves the current orderbook snapshot for a specified market, showing buy and sell orders aggregated by price level.

Orders are grouped by price and include total volume and minimum expiry at each level. Buy orders are sorted by price descending (best bid first), sell orders by price ascending (best ask first).

Body

jsonrpcstringRequiredDefault: 2.0

methodstringRequiredDefault: ob_getOrderbook

idintegerRequiredDefault: 1

Responses

200

Orderbook snapshot with aggregated buy and sell orders

application/json

jsonrpcstringOptional

idintegerOptional

post/ob_getOrderbook

POST /ob_getOrderbook HTTP/1.1
Host: rpc.podtestnet.dev/
Content-Type: application/json
Accept: */*
Content-Length: 134

{
  "jsonrpc": "2.0",
  "method": "ob_getOrderbook",
  "id": 1,
  "params": [
    "0x0000000000000000000000000000000000000000000000000000000000000001",
    20
  ]
}

200

Orderbook snapshot with aggregated buy and sell orders

{
  "jsonrpc": "2.0",
  "result": {
    "orderbook_id": "0x0000000000000000000000000000000000000000000000000000000000000001",
    "buys": {
      "5000000000000000000": {
        "volume": "0xde0b6b3a7640000",
        "minimum_expiry": 1704153600000000
      },
      "4900000000000000000": {
        "volume": "0x1bc16d674ec80000",
        "minimum_expiry": 1704153600000000
      }
    },
    "sells": {
      "5100000000000000000": {
        "volume": "0x14d1120d7b160000",
        "minimum_expiry": 1704153600000000
      },
      "5200000000000000000": {
        "volume": "0x22b1c8c1227a0000",
        "minimum_expiry": 1704153600000000
      }
    },
    "clearing_price": "0x4563918244f40000",
    "grouping_precision": "0x1",
    "timestamp": 1704153600000000,
    "new_orders_count": 5,
    "buys_count": 2,
    "sells_count": 2,
    "oracle_price": null,
    "funding_rate": null,
    "funding_index": null,
    "funding_last_updated": null
  },
  "id": 1
}

Get Historical Candles

post

Retrieves historical candle (OHLCV) data for a specified orderbook.

Candles represent aggregated price and volume data over specified time intervals. Results are returned sorted by timestamp in descending order (newest first).

All prices are in quote/base units with 1e18 scale (hex-encoded).

Body

jsonrpcstringRequiredDefault: 2.0

methodstringRequiredDefault: ob_getCandles

idintegerRequiredDefault: 1

Responses

200

Array of candle objects sorted by timestamp (newest first)

application/json

jsonrpcstringOptional

idintegerOptional

post/ob_getCandles

POST /ob_getCandles HTTP/1.1
Host: rpc.podtestnet.dev/
Content-Type: application/json
Accept: */*
Content-Length: 213

{
  "jsonrpc": "2.0",
  "method": "ob_getCandles",
  "id": 1,
  "params": [
    "0x0000000000000000000000000000000000000000000000000000000000000001",
    {
      "resolution": "1h",
      "from_ts": 1704067200000000,
      "to_ts": 1704153600000000,
      "limit": 100
    }
  ]
}

200

Array of candle objects sorted by timestamp (newest first)

{
  "jsonrpc": "2.0",
  "result": [
    {
      "timestamp": 1704153600000000,
      "open": "0x6f05b59d3b200000",
      "close": "0x6f05b59d3b200000",
      "high": "0x6f05b59d3b200000",
      "low": "0x6f05b59d3b200000",
      "volume": "0x2386f26fc10000"
    },
    {
      "timestamp": 1704150000000000,
      "open": "0x6f05b59d3b200000",
      "close": "0x6f05b59d3b200000",
      "high": "0x6f05b59d3b200000",
      "low": "0x6f05b59d3b200000",
      "volume": "0x2386f26fc10000"
    }
  ],
  "id": 1
}

Get Account Orders

post

Retrieves orders for a specific address in a given orderbook, with support for cursor-based pagination.

Orders are returned in descending order by timestamp/nonce. Use the next_cursor from the response to fetch subsequent pages.

Body

jsonrpcstringRequiredDefault: 2.0

methodstringRequiredDefault: ob_getOrders

idintegerRequiredDefault: 1

Responses

200

Object containing orders array and pagination cursor

application/json

jsonrpcstringOptional

idintegerOptional

post/ob_getOrders

POST /ob_getOrders HTTP/1.1
Host: rpc.podtestnet.dev/
Content-Type: application/json
Accept: */*
Content-Length: 219

{
  "jsonrpc": "2.0",
  "method": "ob_getOrders",
  "id": 1,
  "params": [
    "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28",
    {
      "orderbook_id": "0x0000000000000000000000000000000000000000000000000000000000000001",
      "limit": 10,
      "status": "active"
    }
  ]
}

200

Object containing orders array and pagination cursor

{
  "jsonrpc": "2.0",
  "result": {
    "orders": [
      {
        "orderbook_id": "0x0000000000000000000000000000000000000000000000000000000000000001",
        "market_type": "spot",
        "kind": "user_signed",
        "order_id": "0x9a8b7c6d5e4f30211a2b3c4d5e6f70819a8b7c6d5e4f30211a2b3c4d5e6f7081",
        "tx_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
        "bidder": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28",
        "nonce": 42,
        "order_type": "limit",
        "status": "active",
        "side": "buy",
        "price": "0x4563918244f40000",
        "initial_size": "1000000000000000000",
        "filled_base_amount": "0x6f05b59d3b20000",
        "filled_quote_amount": "0x22b1c8c1227a0000",
        "fee": "0x0",
        "deadline": 1704153600000000,
        "end": 1704240000000000,
        "effective_price": "0x4563918244f40000",
        "fills": [],
        "direction": "buy"
      }
    ],
    "total_count": 42,
    "next_cursor": "1704153600000000:42:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
  },
  "id": 1
}

Get Account Positions

post

Retrieves trading positions for a specific address across all orderbooks.

Positions track the cost basis of acquired tokens (from buys and deposits) and compute unrealized PnL using the current clearing price. The response includes per-token positions (balance, position size, unrealized PnL) and aggregate metrics (total realized PnL, total invested, total unrealized PnL).

All amounts use 1e18 fixed-point scale.

Body

jsonrpcstringRequiredDefault: 2.0

methodstringRequiredDefault: ob_getPositions

idintegerRequiredDefault: 1

paramsstring[]Required

Parameters:

address (address): The address to get positions for

Example: ["0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28"]

Responses

200

Positions response with per-token positions and aggregate PnL

application/json

jsonrpcstringOptional

idintegerOptional

post/ob_getPositions

POST /ob_getPositions HTTP/1.1
Host: rpc.podtestnet.dev/
Content-Type: application/json
Accept: */*
Content-Length: 107

{
  "jsonrpc": "2.0",
  "method": "ob_getPositions",
  "id": 1,
  "params": [
    "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28"
  ]
}

200

Positions response with per-token positions and aggregate PnL

{
  "jsonrpc": "2.0",
  "result": {
    "positions": [
      {
        "kind": "spot",
        "orderbook_id": "0x0000000000000000000000000000000000000000000000000000000000000001",
        "base_symbol": "NVDAx",
        "quote_symbol": "USD",
        "balance": "0x6c6b935b8bbd400000",
        "free_balance": "0x6c6b935b8bbd400000",
        "locked_balance": "0x0",
        "cost_basis": "0x21e19e0c9bab2400000",
        "mark_price": "0x4563918244f40000",
        "unrealized_pnl": "0",
        "realized_pnl": "0"
      },
      {
        "kind": "perp",
        "orderbook_id": "0x0000000000000000000000000000000000000000000000000000000000000007",
        "base_symbol": "NVDA",
        "quote_symbol": "USD",
        "side": "long",
        "size": "10000000000000000",
        "notional": "0x4f0d4f7e7a3e0000",
        "entry_price": "0x130ee8e7179044a0000",
        "mark_price": "0x130ee8e7179044a0000",
        "margin": "0xc7d713b49da00000",
        "leverage": "0x4563918244f40000",
        "funding_accrued": "0",
        "liquidation_price": "0x115ad84a8ad03c00000",
        "unrealized_pnl": "0",
        "realized_pnl": "0",
        "stop_loss": null,
        "take_profit": null
      }
    ],
    "total_unrealized_pnl": "0",
    "total_realized_pnl": "0",
    "perps_equity": "0",
    "account_value": "0x21e19e0c9bab2400000",
    "cash": "0",
    "withdrawable_cash": "0x0"
  },
  "id": 1
}

Get Account Fills

post

Retrieves trade fills for a specific address within a time range.

Fills represent individual trade executions from batch auction settlements. A single order may produce multiple fills across different batches. Each fill includes the clearing price, base and quote amounts, and the associated orderbook and token addresses.

Results are returned in descending order by timestamp (most recent first).

Body

jsonrpcstringRequiredDefault: 2.0

methodstringRequiredDefault: ob_getFills

idintegerRequiredDefault: 1

Responses

200

Object containing fills array

application/json

jsonrpcstringOptional

idintegerOptional

post/ob_getFills

POST /ob_getFills HTTP/1.1
Host: rpc.podtestnet.dev/
Content-Type: application/json
Accept: */*
Content-Length: 253

{
  "jsonrpc": "2.0",
  "method": "ob_getFills",
  "id": 1,
  "params": [
    "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28",
    {
      "from_ts": 1704067200000000,
      "to_ts": 1704153600000000,
      "orderbook_id": "0x0000000000000000000000000000000000000000000000000000000000000001",
      "limit": 100
    }
  ]
}

200

Object containing fills array

{
  "jsonrpc": "2.0",
  "result": {
    "fills": [
      {
        "orderbook_id": "0x0000000000000000000000000000000000000000000000000000000000000001",
        "base_token": "0x0000000000000000000000000000000000000001",
        "quote_token": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
        "order_id": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
        "order_type": "limit",
        "initial_size": "1000000000000000000",
        "fee": "0",
        "base_amount": "500000000000000000",
        "quote_amount": "2500000000000000000",
        "timestamp": 1704153600000000,
        "price": "5000000000000000000"
      }
    ]
  },
  "id": 1
}

Get Account Backstop Transfers

post

Retrieves the backstop transfers for a specific address, with cursor-based pagination.

A backstop transfer is recorded when a perp position is swept to the backstop during liquidation: the position's remaining size and cash are moved off the account. Each entry captures the swept size, cash, the mark price at the sweep, and the account equity at that moment.

Results are returned in descending order by timestamp (most recent first). Use next_cursor from the response to fetch subsequent pages.

Body

jsonrpcstringRequiredDefault: 2.0

methodstringRequiredDefault: ob_getBackstopTransfers

idintegerRequiredDefault: 1

Responses

200

Object containing the backstop transfers array, total count, and pagination cursor

application/json

jsonrpcstringOptional

idintegerOptional

post/ob_getBackstopTransfers

POST /ob_getBackstopTransfers HTTP/1.1
Host: rpc.podtestnet.dev/
Content-Type: application/json
Accept: */*
Content-Length: 212

{
  "jsonrpc": "2.0",
  "method": "ob_getBackstopTransfers",
  "id": 1,
  "params": [
    "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28",
    {
      "orderbook_id": "0x0000000000000000000000000000000000000000000000000000000000000007",
      "limit": 50
    }
  ]
}

200

Object containing the backstop transfers array, total count, and pagination cursor

{
  "jsonrpc": "2.0",
  "result": {
    "transfers": [
      {
        "user": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28",
        "orderbook_id": "0x0000000000000000000000000000000000000000000000000000000000000007",
        "size": "-10000000000000000",
        "cash": "-5000000000000000000",
        "mark_price": "0x130ee8e7179044a0000",
        "equity": "-1000000000000000000",
        "timestamp": 1704153600000000
      }
    ],
    "total_count": 1,
    "next_cursor": null
  },
  "id": 1
}

Get Account Triggers

post

Retrieves the armed TP/SL trigger orders owned by an address, with cursor-based pagination.

Triggers are conditional perp orders: when the pair's mark price crosses trigger_price in the direction implied by trigger_type and the sign of size, the engine emits a synthetic order (surfaced through ob_getOrders with kind = triggered). Triggers themselves have no fill history, so this response is leaner than ob_getOrders.

Triggers are returned sorted by (orderbook_id, order_id). Use next_cursor from the response to fetch subsequent pages.

Body

jsonrpcstringRequiredDefault: 2.0

methodstringRequiredDefault: ob_getTriggers

idintegerRequiredDefault: 1

Responses

200

Object containing the triggers array, total count, and pagination cursor

application/json

jsonrpcstringOptional

idintegerOptional

post/ob_getTriggers

POST /ob_getTriggers HTTP/1.1
Host: rpc.podtestnet.dev/
Content-Type: application/json
Accept: */*
Content-Length: 203

{
  "jsonrpc": "2.0",
  "method": "ob_getTriggers",
  "id": 1,
  "params": [
    "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28",
    {
      "orderbook_id": "0x0000000000000000000000000000000000000000000000000000000000000007",
      "limit": 50
    }
  ]
}

200

Object containing the triggers array, total count, and pagination cursor

{
  "jsonrpc": "2.0",
  "result": {
    "triggers": [
      {
        "orderbook_id": "0x0000000000000000000000000000000000000000000000000000000000000007",
        "order_id": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
        "tx_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
        "bidder": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28",
        "nonce": 7,
        "size": "-10000000000000000",
        "limit_price": "0x115ad84a8ad03c00000",
        "trigger_price": "0x120a871cc0020a00000",
        "trigger_type": "take_profit",
        "grouping": "position",
        "reduce_only": true,
        "ioc": false,
        "deadline": "1704153600000000",
        "end": "1704240000000000"
      }
    ],
    "total_count": 1,
    "next_cursor": null
  },
  "id": 1
}

Get Ranked Positions (Leaderboard)

post

Returns accounts ranked by combined realized + unrealized PnL (total_realized_pnl + total_unrealized_pnl) descending, paginated by offset/limit.

Because the unrealized component moves with mark prices, the ordering can shift between calls even without trades. When an address is supplied, the response also includes that account's own positions and rank (queried), independent of the returned page.

Body

jsonrpcstringRequiredDefault: 2.0

methodstringRequiredDefault: ob_getRankedPositions

idintegerRequiredDefault: 1

Responses

200

Ranked window of accounts plus the total count and optional queried account

application/json

jsonrpcstringOptional

idintegerOptional

post/ob_getRankedPositions

POST /ob_getRankedPositions HTTP/1.1
Host: rpc.podtestnet.dev/
Content-Type: application/json
Accept: */*
Content-Length: 118

{
  "jsonrpc": "2.0",
  "method": "ob_getRankedPositions",
  "id": 1,
  "params": [
    10,
    0,
    "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28"
  ]
}

200

Ranked window of accounts plus the total count and optional queried account

{
  "jsonrpc": "text",
  "result": {
    "ranked": [
      {
        "account": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28",
        "positions": {
          "positions": [
            {
              "kind": "spot",
              "orderbook_id": "0x0000000000000000000000000000000000000000000000000000000000000001",
              "base_symbol": "text",
              "quote_symbol": "text",
              "balance": "0x6f05b59d3b200000",
              "free_balance": "0x6f05b59d3b200000",
              "locked_balance": "0x6f05b59d3b200000",
              "cost_basis": "0x6f05b59d3b200000",
              "mark_price": "0x6f05b59d3b200000",
              "unrealized_pnl": "text",
              "realized_pnl": "text"
            }
          ],
          "total_unrealized_pnl": "text",
          "total_realized_pnl": "text",
          "perps_equity": "text",
          "account_value": "text",
          "cash": "text",
          "withdrawable_cash": "0x6f05b59d3b200000"
        }
      }
    ],
    "total": 1,
    "queried": {
      "account": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28",
      "rank": 1,
      "positions": {
        "positions": [
          {
            "kind": "spot",
            "orderbook_id": "0x0000000000000000000000000000000000000000000000000000000000000001",
            "base_symbol": "text",
            "quote_symbol": "text",
            "balance": "0x6f05b59d3b200000",
            "free_balance": "0x6f05b59d3b200000",
            "locked_balance": "0x6f05b59d3b200000",
            "cost_basis": "0x6f05b59d3b200000",
            "mark_price": "0x6f05b59d3b200000",
            "unrealized_pnl": "text",
            "realized_pnl": "text"
          }
        ],
        "total_unrealized_pnl": "text",
        "total_realized_pnl": "text",
        "perps_equity": "text",
        "account_value": "text",
        "cash": "text",
        "withdrawable_cash": "0x6f05b59d3b200000"
      }
    }
  },
  "id": 1
}

Get Oracle & Mark Prices

post

Returns the latest oracle and mark prices recorded for perp orderbooks by the indexer.

Pass an orderbook_id to fetch a single orderbook, or omit it for every perp orderbook. Numeric fields are 0 and as_of is epoch until the orderbook has run a perp batch. Funding state is not included here — call ob_getFundingRates for that.

Body

jsonrpcstringRequiredDefault: 2.0

methodstringRequiredDefault: ob_getOraclePrices

idintegerRequiredDefault: 1

paramsstring[]Optional

Positional parameters:

orderbook_id (Bytes32, optional): Restrict to a single orderbook; omit for all perp orderbooks

Example: ["0x0000000000000000000000000000000000000000000000000000000000000007"]

Responses

200

Array of oracle/mark price objects

application/json

jsonrpcstringOptional

idintegerOptional

post/ob_getOraclePrices

POST /ob_getOraclePrices HTTP/1.1
Host: rpc.podtestnet.dev/
Content-Type: application/json
Accept: */*
Content-Length: 134

{
  "jsonrpc": "2.0",
  "method": "ob_getOraclePrices",
  "id": 1,
  "params": [
    "0x0000000000000000000000000000000000000000000000000000000000000007"
  ]
}

200

Array of oracle/mark price objects

{
  "jsonrpc": "text",
  "result": [
    {
      "orderbook_id": "0x0000000000000000000000000000000000000000000000000000000000000001",
      "oracle_price": "0x6f05b59d3b200000",
      "mark_price": "0x6f05b59d3b200000",
      "as_of": 1704153600000000
    }
  ],
  "id": 1
}

Get Funding Rates

post

Returns the latest funding state for perp orderbooks, with the mark and oracle prices included for context.

Pass an orderbook_id to fetch a single orderbook, or omit it for every perp orderbook.

Body

jsonrpcstringRequiredDefault: 2.0

methodstringRequiredDefault: ob_getFundingRates

idintegerRequiredDefault: 1

paramsstring[]Optional

Positional parameters:

orderbook_id (Bytes32, optional): Restrict to a single orderbook; omit for all perp orderbooks

Example: ["0x0000000000000000000000000000000000000000000000000000000000000007"]

Responses

200

Array of funding rate objects

application/json

jsonrpcstringOptional

idintegerOptional

post/ob_getFundingRates

POST /ob_getFundingRates HTTP/1.1
Host: rpc.podtestnet.dev/
Content-Type: application/json
Accept: */*
Content-Length: 134

{
  "jsonrpc": "2.0",
  "method": "ob_getFundingRates",
  "id": 1,
  "params": [
    "0x0000000000000000000000000000000000000000000000000000000000000007"
  ]
}

200

Array of funding rate objects

{
  "jsonrpc": "text",
  "result": [
    {
      "orderbook_id": "0x0000000000000000000000000000000000000000000000000000000000000001",
      "funding_rate": "text",
      "funding_index": "text",
      "mark_price": "0x6f05b59d3b200000",
      "oracle_price": "0x6f05b59d3b200000",
      "as_of": 1704153600000000
    }
  ],
  "id": 1
}

PreviousJSON-RPC NextEthereum Interface (eth )

Last updated 27 days ago