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

application/json

jsonrpcstringRequiredDefault: 2.0

methodstringRequiredDefault: ob_getMarkets

idintegerRequiredDefault: 1

paramsarrayOptionalDefault: []

Responses

200

Array of market objects with metadata and statistics

application/json

post

/ob_getMarkets

HTTPcURLJavaScriptPython

POST /ob_getMarkets HTTP/1.1
Host: tapforce-rpc.pod.network/
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": "PETH/USDT",
      "base_token_address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
      "quote_token_address": "0x0000000000000000000000000000000000000001",
      "base_token_symbol": "PETH",
      "quote_token_symbol": "USDT",
      "base_token_name": "Wrapped ETH",
      "quote_token_name": "Test USDT",
      "market_type": "spot",
      "last_clearing_price": "0x6f05b59d3b200000",
      "auction_interval": 500,
      "volume_24h": "0x2386f26fc10000",
      "high_24h": "0x1158e460913d00000",
      "low_24h": "0x6f05b59d3b200000",
      "price_change_24h": 0,
      "maker_fee": "0x0",
      "taker_fee": "0x0",
      "tick_precision": "0x1"
    }
  ],
  "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

application/json

jsonrpcstringRequiredDefault: 2.0

methodstringRequiredDefault: ob_getOrderbook

idintegerRequiredDefault: 1

paramsarrayRequired

Parameters:

1. orderbook_id (bytes32): The 32-byte orderbook identifier
2. depth (integer, optional): Maximum number of price levels to return for each side. If omitted, all available price levels are returned.

Example: ["0x0000000000000000000000000000000000000000000000000000000000000001",20]

Responses

200

Orderbook snapshot with aggregated buy and sell orders

application/json

post

/ob_getOrderbook

HTTPcURLJavaScriptPython

POST /ob_getOrderbook HTTP/1.1
Host: tapforce-rpc.pod.network/
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": {
    "clob_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
      }
    },
    "grouping_precision": "1",
    "timestamp": 1704153600000000,
    "new_orders_count": 5,
    "buys_count": 2,
    "sells_count": 2
  },
  "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

application/json

jsonrpcstringRequiredDefault: 2.0

methodstringRequiredDefault: ob_getCandles

idintegerRequiredDefault: 1

paramsarrayRequired

Parameters:

1. orderbook_id (bytes32): The 32-byte orderbook identifier
2. query (object): Query parameters with resolution, time range, and limit

Example: ["0x0000000000000000000000000000000000000000000000000000000000000001",{"resolution":"1h","from_ts":1704067200000000,"to_ts":1704153600000000,"limit":100}]

Responses

200

Array of candle objects sorted by timestamp (newest first)

application/json

post

/ob_getCandles

HTTPcURLJavaScriptPython

POST /ob_getCandles HTTP/1.1
Host: tapforce-rpc.pod.network/
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

application/json

jsonrpcstringRequiredDefault: 2.0

methodstringRequiredDefault: ob_getOrders

idintegerRequiredDefault: 1

paramsarrayRequired

Parameters:

1. address (address): The address to get orders for
2. query (object): Query parameters with optional orderbook_id, limit, cursor, and status filter

Example: ["0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28",{"orderbook_id":"0x0000000000000000000000000000000000000000000000000000000000000001","limit":10,"status":"active"}]

Responses

200

Object containing orders array and pagination cursor

application/json

post

/ob_getOrders

HTTPcURLJavaScriptPython

POST /ob_getOrders HTTP/1.1
Host: tapforce-rpc.pod.network/
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": [
      {
        "tx_hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
        "nonce": 42,
        "bidder": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28",
        "initial_size": "1000000000000000000",
        "filled_base_amount": "500000000000000000",
        "filled_quote_amount": "2500000000000000000",
        "price": "5000000000000000000",
        "deadline": "1704153600000000",
        "end": "1704240000000000",
        "fee": "1000000000000000",
        "status": "active"
      }
    ],
    "total_count": 42,
    "next_cursor": "1704153600000000:42"
  },
  "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

application/json

jsonrpcstringRequiredDefault: 2.0

methodstringRequiredDefault: ob_getPositions

idintegerRequiredDefault: 1

paramsstring[]Required

Parameters:

1. address (address): The address to get positions for

Example: ["0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28"]

Responses

200

Positions response with per-token positions and aggregate PnL

application/json

post

/ob_getPositions

HTTPcURLJavaScriptPython

POST /ob_getPositions HTTP/1.1
Host: tapforce-rpc.pod.network/
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": [
      {
        "symbol": "PETH",
        "address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
        "balance": "0x21e19e0c9bab2400000",
        "position": "0x21e19e0c9bab2400000",
        "unrealized_pnl": "-99900099900099900100"
      },
      {
        "symbol": "USDT",
        "address": "0x0000000000000000000000000000000000000001",
        "balance": "0x20dd68aaf3289100000",
        "position": "0x0",
        "unrealized_pnl": "0"
      }
    ],
    "total_unrealized_pnl": "-99900099900099900100",
    "total_realized_pnl": "99900099900099900100",
    "total_invested": "0x56bc75e2d63100000"
  },
  "id": 1
}