# 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
> 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.
```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"tags":[{"name":"Orderbook Data (ob_)","description":"Orderbook Data (`ob_`) is a read-focused API surface that provides access to\nmarkets and orderbook activity without requiring clients to run their own\nindexer or interact with the orderbook contracts directly. It is powered\nby a native indexer built into the Pod protocol, ensuring fast, consistent,\nand up-to-date views of on-chain state.\n\nThe API exposes live orderbook snapshots, historical OHLCV candles,\naccount-level order history and positions, making it ideal for trading\ninterfaces, analytics, and monitoring services.\n\nš This is a JSON-RPC 2.0 API. The request path is not important; the\nmethod to execute is defined by the method field in the request body. You\ncan send all requests to /, and any path after / is optional and used only\nfor documentation clarity.\n\n \n"}],"servers":[{"url":"https://rpc.podtestnet.dev/","description":"Pod testnet"}],"paths":{"/ob_getMarkets":{"post":{"tags":["Orderbook Data (ob_)"],"summary":"Get All Markets","operationId":"ob_getMarkets","description":"Retrieves a list of all available markets/orderbooks with their metadata\nand statistics. Each market includes token information, current pricing,\n24-hour statistics, and fee structure.\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method","id"],"properties":{"jsonrpc":{"type":"string","default":"2.0"},"method":{"type":"string","default":"ob_getMarkets"},"id":{"type":"integer","default":1},"params":{"type":"array","default":[]}}}}}},"responses":{"200":{"description":"Array of market objects with metadata and statistics","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string"},"result":{"type":"array","items":{"$ref":"#/components/schemas/Market"}},"id":{"type":"integer"}}}}}}}}}},"components":{"schemas":{"Market":{"type":"object","description":"Market/orderbook metadata and 24-hour statistics","properties":{"id":{"$ref":"#/components/schemas/Bytes32","description":"Unique 32-byte orderbook identifier"},"name":{"type":"string","description":"Market name in format `{base_token}/{quote_token}` (e.g. \"NVDAx/USD\")"},"base_token_address":{"$ref":"#/components/schemas/Address","description":"Contract address of the base token"},"quote_token_address":{"$ref":"#/components/schemas/Address","description":"Contract address of the quote token"},"base_token_symbol":{"type":"string","description":"Symbol of the base token (e.g., \"NVDAx\")"},"quote_token_symbol":{"type":"string","description":"Symbol of the quote token (e.g., \"USD\")"},"base_token_name":{"type":"string","description":"Full name of the base token"},"quote_token_name":{"type":"string","description":"Full name of the quote token"},"market_type":{"$ref":"#/components/schemas/MarketType"},"last_clearing_price":{"$ref":"#/components/schemas/HexUint256","description":"Last auction clearing price (quote/base with 1e18 scale)"},"auction_interval":{"type":"string","pattern":"^[0-9]+$","description":"Length of a matching round. Serialized as a decimal string because the value is a `u128` on the wire."},"volume_24h":{"$ref":"#/components/schemas/HexUint256","description":"24-hour trading volume"},"high_24h":{"$ref":"#/components/schemas/HexUint256","description":"24-hour highest price"},"low_24h":{"$ref":"#/components/schemas/HexUint256","description":"24-hour lowest price"},"price_change_24h":{"type":"integer","format":"int64","description":"24-hour price change (signed integer)"},"tick_precision":{"$ref":"#/components/schemas/HexUint256","description":"Minimum price tick size, hex-encoded with `1e18` scale (e.g. `0xde0b6b3a7640000` = `1e18` = one whole tick)."},"lot_size":{"$ref":"#/components/schemas/HexUint256","description":"Minimum order size increment, hex-encoded with `1e18` scale. Order sizes must be multiples of this value."},"maker_fee":{"$ref":"#/components/schemas/HexUint256","description":"Maker fee rate (1e18-scaled)"},"taker_fee":{"$ref":"#/components/schemas/HexUint256","description":"Taker fee rate (1e18-scaled)"},"max_leverage":{"type":"integer","description":"Maximum allowed leverage. Returned for both spot and perp markets, but only meaningful for perp."},"oracle_price":{"type":"string","nullable":true,"description":"Perp markets only. Latest Pyth oracle price as a hex-encoded\nunsigned 256-bit integer (1e18-scaled), used as the mark for funding\nand liquidation. `null` for spot markets.\n"},"funding_rate_8h":{"type":"string","nullable":true,"description":"Perp markets only. Per-8-hour funding rate as a signed decimal\nstring (1e18-scaled, may be negative). `null` for spot markets.\n"},"funding_index":{"type":"string","nullable":true,"description":"Perp markets only. Cumulative per-unit-size funding accumulator as\na signed decimal string (1e18-scaled, may be negative). `null` for\nspot markets.\n"},"funding_last_updated":{"type":"integer","format":"int64","nullable":true,"description":"Perp markets only. Microsecond Unix timestamp of the batch that produced\nthe most recent funding update. `null` for spot markets.\n"},"open_interest":{"type":"string","nullable":true,"description":"Perp markets only. Open interest in 1e18-scaled USD notional as a\nhex-encoded unsigned 256-bit integer ā\n`mark_price * Ī£ |position.size|` across every open cross-margin\nposition on this market. `null` for spot markets.\n"}}},"Bytes32":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$","description":"32-byte value (hex-encoded with 0x prefix). Used for transaction hashes, orderbook IDs, etc."},"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"},"MarketType":{"type":"string","enum":["spot","perpetual"],"description":"Type of market - spot trading or perpetual futures"},"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"}}}}
```
## Get Orderbook Snapshot
> 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).
```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"tags":[{"name":"Orderbook Data (ob_)","description":"Orderbook Data (`ob_`) is a read-focused API surface that provides access to\nmarkets and orderbook activity without requiring clients to run their own\nindexer or interact with the orderbook contracts directly. It is powered\nby a native indexer built into the Pod protocol, ensuring fast, consistent,\nand up-to-date views of on-chain state.\n\nThe API exposes live orderbook snapshots, historical OHLCV candles,\naccount-level order history and positions, making it ideal for trading\ninterfaces, analytics, and monitoring services.\n\nš This is a JSON-RPC 2.0 API. The request path is not important; the\nmethod to execute is defined by the method field in the request body. You\ncan send all requests to /, and any path after / is optional and used only\nfor documentation clarity.\n\n \n"}],"servers":[{"url":"https://rpc.podtestnet.dev/","description":"Pod testnet"}],"paths":{"/ob_getOrderbook":{"post":{"tags":["Orderbook Data (ob_)"],"summary":"Get Orderbook Snapshot","operationId":"ob_getOrderbook","description":"Retrieves the current orderbook snapshot for a specified market, showing buy and sell orders aggregated by price level.\n\nOrders are grouped by price and include total volume and minimum expiry at each level.\nBuy orders are sorted by price descending (best bid first), sell orders by price ascending (best ask first).\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method","params","id"],"properties":{"jsonrpc":{"type":"string","default":"2.0"},"method":{"type":"string","default":"ob_getOrderbook"},"id":{"type":"integer","default":1},"params":{"type":"array","description":"Parameters:\n1. `orderbook_id` (bytes32): The 32-byte orderbook identifier\n2. `depth` (integer, optional): Maximum number of price levels to return for each side. If omitted, all available price levels are returned.\n","items":{"oneOf":[{"$ref":"#/components/schemas/Bytes32"},{"type":"integer","description":"Depth - maximum price levels per side"}]}}}}}}},"responses":{"200":{"description":"Orderbook snapshot with aggregated buy and sell orders","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string"},"result":{"$ref":"#/components/schemas/OrderbookSnapshot"},"id":{"type":"integer"}}}}}}}}}},"components":{"schemas":{"Bytes32":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$","description":"32-byte value (hex-encoded with 0x prefix). Used for transaction hashes, orderbook IDs, etc."},"OrderbookSnapshot":{"type":"object","description":"Current state of an orderbook with aggregated buy/sell levels.\nUses `clob_id` (same as orderbook_id); websocket subscriptions use `clob_ids` for consistency.\n","properties":{"clob_id":{"$ref":"#/components/schemas/Bytes32","description":"Orderbook identifier (synonym for orderbook_id)"},"buys":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/TickSnapshot"},"description":"Buy orders keyed by price (decimal string), sorted by price descending"},"sells":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/TickSnapshot"},"description":"Sell orders keyed by price (decimal string), sorted by price ascending"},"clearing_price":{"$ref":"#/components/schemas/HexUint256","description":"Current/last clearing price"},"grouping_precision":{"type":"string","description":"Price grouping precision used for aggregation"},"timestamp":{"type":"integer","description":"Snapshot timestamp in microseconds"},"new_orders_count":{"type":"integer","description":"Number of new orders since the last snapshot"},"buys_count":{"type":"integer","description":"Total number of buy orders in the orderbook (regardless of depth parameter)"},"sells_count":{"type":"integer","description":"Total number of sell orders in the orderbook (regardless of depth parameter)"}}},"TickSnapshot":{"type":"object","description":"Aggregated order volume at a specific price level","properties":{"volume":{"$ref":"#/components/schemas/DecimalUint256","description":"Total volume available at this price level"},"minimum_expiry":{"type":"integer","description":"Minimum expiry timestamp (microseconds) for orders at this price level"}}},"DecimalUint256":{"type":"string","pattern":"^[0-9]+$","description":"Unsigned 256-bit integer (decimal string representation)"},"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"}}}}
```
## Get Historical Candles
> 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).
```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"tags":[{"name":"Orderbook Data (ob_)","description":"Orderbook Data (`ob_`) is a read-focused API surface that provides access to\nmarkets and orderbook activity without requiring clients to run their own\nindexer or interact with the orderbook contracts directly. It is powered\nby a native indexer built into the Pod protocol, ensuring fast, consistent,\nand up-to-date views of on-chain state.\n\nThe API exposes live orderbook snapshots, historical OHLCV candles,\naccount-level order history and positions, making it ideal for trading\ninterfaces, analytics, and monitoring services.\n\nš This is a JSON-RPC 2.0 API. The request path is not important; the\nmethod to execute is defined by the method field in the request body. You\ncan send all requests to /, and any path after / is optional and used only\nfor documentation clarity.\n\n \n"}],"servers":[{"url":"https://rpc.podtestnet.dev/","description":"Pod testnet"}],"paths":{"/ob_getCandles":{"post":{"tags":["Orderbook Data (ob_)"],"summary":"Get Historical Candles","operationId":"ob_getCandles","description":"Retrieves historical candle (OHLCV) data for a specified orderbook.\n\nCandles represent aggregated price and volume data over specified time intervals.\nResults are returned sorted by timestamp in descending order (newest first).\n\nAll prices are in quote/base units with 1e18 scale (hex-encoded).\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method","params","id"],"properties":{"jsonrpc":{"type":"string","default":"2.0"},"method":{"type":"string","default":"ob_getCandles"},"id":{"type":"integer","default":1},"params":{"type":"array","description":"Parameters:\n1. `orderbook_id` (bytes32): The 32-byte orderbook identifier\n2. `query` (object): Query parameters with resolution, time range, and limit\n"}}}}}},"responses":{"200":{"description":"Array of candle objects sorted by timestamp (newest first)","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string"},"result":{"type":"array","items":{"$ref":"#/components/schemas/Candle"}},"id":{"type":"integer"}}}}}}}}}},"components":{"schemas":{"Candle":{"type":"object","description":"OHLCV candle representing price/volume data for a time period","properties":{"timestamp":{"$ref":"#/components/schemas/Timestamp","description":"Candle timestamp in microseconds"},"open":{"$ref":"#/components/schemas/HexUint256","description":"Opening price (quote/base with 1e18 scale)"},"close":{"$ref":"#/components/schemas/HexUint256","description":"Closing price (quote/base with 1e18 scale)"},"high":{"$ref":"#/components/schemas/HexUint256","description":"Highest price (quote/base with 1e18 scale)"},"low":{"$ref":"#/components/schemas/HexUint256","description":"Lowest price (quote/base with 1e18 scale)"},"volume":{"$ref":"#/components/schemas/HexUint256","description":"Total volume traded during this candle period"}}},"Timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in microseconds (not milliseconds or seconds)"},"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"}}}}
```
## Get Account Orders
> 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.
```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"tags":[{"name":"Orderbook Data (ob_)","description":"Orderbook Data (`ob_`) is a read-focused API surface that provides access to\nmarkets and orderbook activity without requiring clients to run their own\nindexer or interact with the orderbook contracts directly. It is powered\nby a native indexer built into the Pod protocol, ensuring fast, consistent,\nand up-to-date views of on-chain state.\n\nThe API exposes live orderbook snapshots, historical OHLCV candles,\naccount-level order history and positions, making it ideal for trading\ninterfaces, analytics, and monitoring services.\n\nš This is a JSON-RPC 2.0 API. The request path is not important; the\nmethod to execute is defined by the method field in the request body. You\ncan send all requests to /, and any path after / is optional and used only\nfor documentation clarity.\n\n \n"}],"servers":[{"url":"https://rpc.podtestnet.dev/","description":"Pod testnet"}],"paths":{"/ob_getOrders":{"post":{"tags":["Orderbook Data (ob_)"],"summary":"Get Account Orders","operationId":"ob_getOrders","description":"Retrieves orders for a specific address in a given orderbook, with support for cursor-based pagination.\n\nOrders are returned in descending order by timestamp/nonce.\nUse the `next_cursor` from the response to fetch subsequent pages.\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method","params","id"],"properties":{"jsonrpc":{"type":"string","default":"2.0"},"method":{"type":"string","default":"ob_getOrders"},"id":{"type":"integer","default":1},"params":{"type":"array","description":"Parameters:\n1. `address` (address): The address to get orders for\n2. `query` (object): Query parameters with optional orderbook_id, limit, cursor, and status filter\n"}}}}}},"responses":{"200":{"description":"Object containing orders array and pagination cursor","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string"},"result":{"type":"object","properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"total_count":{"type":"integer","description":"Total number of orders matching the query"},"next_cursor":{"type":"string","nullable":true,"description":"Cursor for fetching the next page. Null if no more results."}}},"id":{"type":"integer"}}}}}}}}}},"components":{"schemas":{"Order":{"type":"object","description":"An order returned by `ob_getOrders`. Carries spot and perp shapes ā perp-only fields (`reduce_only`, `ioc`, `direction`) are present only when `market_type = perpetual`. The `initial_size` is signed: positive for Buy/Long, negative for Sell/Short.\n","properties":{"orderbook_id":{"$ref":"#/components/schemas/Bytes32","description":"The orderbook this order belongs to"},"market_type":{"$ref":"#/components/schemas/MarketType"},"kind":{"$ref":"#/components/schemas/OrderKind"},"tx_hash":{"$ref":"#/components/schemas/Bytes32","description":"Transaction hash that created this order"},"bidder":{"$ref":"#/components/schemas/Address","description":"Address of the order creator"},"nonce":{"type":"integer","format":"int64","description":"Order nonce for the account"},"order_type":{"type":"string","enum":["limit","market"],"description":"Limit or market"},"status":{"$ref":"#/components/schemas/OrderStatus"},"side":{"type":"string","enum":["buy","sell"],"description":"Bid (buy) or ask (sell). For perps, prefer `direction` for the position-effect label."},"price":{"$ref":"#/components/schemas/HexUint256","description":"Limit price in quote/base units with 1e18 scale"},"initial_size":{"type":"string","description":"Original signed order size (positive = Buy/Long, negative = Sell/Short)"},"filled_base_amount":{"$ref":"#/components/schemas/HexUint256","description":"Cumulative amount of base tokens filled"},"filled_quote_amount":{"$ref":"#/components/schemas/HexUint256","description":"Cumulative amount of quote tokens filled"},"fee":{"$ref":"#/components/schemas/HexUint256","description":"Accumulated trading fee. Currently always zero."},"deadline":{"$ref":"#/components/schemas/TimestampString","description":"Timestamp by which order must be included in the orderbook (microseconds)"},"end":{"$ref":"#/components/schemas/TimestampString","description":"Timestamp when order expires (microseconds)"},"effective_price":{"$ref":"#/components/schemas/HexUint256","description":"Effective price the order has been filled at so far (filled_quote / filled_base, 1e18)"},"fills":{"type":"array","items":{"$ref":"#/components/schemas/PartialFill"},"description":"Per-batch partial fills against this order"},"reduce_only":{"type":"boolean","description":"Perp only. If true, the order can only reduce existing exposure. Omitted for spot orders.","nullable":true},"ioc":{"type":"boolean","description":"Perp only. Immediate-or-cancel ā any unfilled remainder is canceled at end of batch. Omitted for spot orders.","nullable":true},"direction":{"$ref":"#/components/schemas/OrderDirection","description":"Composite direction label (set for spot, and for perps once fills land or for liquidation/ADL orders).","nullable":true}}},"Bytes32":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$","description":"32-byte value (hex-encoded with 0x prefix). Used for transaction hashes, orderbook IDs, etc."},"MarketType":{"type":"string","enum":["spot","perpetual"],"description":"Type of market - spot trading or perpetual futures"},"OrderKind":{"type":"string","enum":["user_signed","liquidation","adl","backstop_transfer"],"description":"Origin of the order:\n- `user_signed`: a normal user-submitted order\n- `liquidation`: synthesized by the engine when liquidating a perp position\n- `adl`: synthesized for auto-deleveraging when equity goes negative\n- `backstop_transfer`: synthesized when the portfolio is transferred to the backstop vault\n"},"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"},"OrderStatus":{"type":"string","enum":["pending","active","filled","expired","canceled"],"description":"Current status of an order:\n- `pending`: Order submitted but not yet included in orderbook\n- `active`: Order is live in the orderbook\n- `filled`: Order completely filled\n- `expired`: Order expired (TTL exceeded)\n- `canceled`: Order was canceled by user\n"},"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"},"TimestampString":{"type":"string","pattern":"^[0-9]+$","description":"Unix timestamp in microseconds as a string"},"PartialFill":{"type":"object","description":"A single fill round against this order.","properties":{"base_amount":{"$ref":"#/components/schemas/HexUint256","description":"Base token amount filled in this round (1e18)"},"quote_amount":{"$ref":"#/components/schemas/HexUint256","description":"Quote token amount filled in this round (1e18)"},"timestamp":{"$ref":"#/components/schemas/Timestamp","description":"Batch settlement timestamp (microseconds)"},"price":{"$ref":"#/components/schemas/HexUint256","description":"Clearing price of the batch (1e18)"}}},"Timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in microseconds (not milliseconds or seconds)"},"OrderDirection":{"type":"string","enum":["buy","sell","open_long","add_long","reduce_long","close_long","open_short","add_short","reduce_short","close_short","long_to_short","short_to_long","liquidation"],"description":"Composite per-order direction for history and open-orders UIs.\nSpot orders use `buy`/`sell`. Perp orders use the position-effect labels (`open_long`, `reduce_long`, `close_long`, `long_to_short`, etc.) computed from the position before/after the fill. `liquidation` is set when `kind = liquidation`.\n"}}}}
```
## Get Account Positions
> 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.
```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"tags":[{"name":"Orderbook Data (ob_)","description":"Orderbook Data (`ob_`) is a read-focused API surface that provides access to\nmarkets and orderbook activity without requiring clients to run their own\nindexer or interact with the orderbook contracts directly. It is powered\nby a native indexer built into the Pod protocol, ensuring fast, consistent,\nand up-to-date views of on-chain state.\n\nThe API exposes live orderbook snapshots, historical OHLCV candles,\naccount-level order history and positions, making it ideal for trading\ninterfaces, analytics, and monitoring services.\n\nš This is a JSON-RPC 2.0 API. The request path is not important; the\nmethod to execute is defined by the method field in the request body. You\ncan send all requests to /, and any path after / is optional and used only\nfor documentation clarity.\n\n \n"}],"servers":[{"url":"https://rpc.podtestnet.dev/","description":"Pod testnet"}],"paths":{"/ob_getPositions":{"post":{"tags":["Orderbook Data (ob_)"],"summary":"Get Account Positions","operationId":"ob_getPositions","description":"Retrieves trading positions for a specific address across all orderbooks.\n\nPositions track the cost basis of acquired tokens (from buys and deposits) and compute\nunrealized PnL using the current clearing price. The response includes per-token positions\n(balance, position size, unrealized PnL) and aggregate metrics (total realized PnL,\ntotal invested, total unrealized PnL).\n\nAll amounts use 1e18 fixed-point scale.\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method","params","id"],"properties":{"jsonrpc":{"type":"string","default":"2.0"},"method":{"type":"string","default":"ob_getPositions"},"id":{"type":"integer","default":1},"params":{"type":"array","description":"Parameters:\n1. `address` (address): The address to get positions for\n","items":{"$ref":"#/components/schemas/Address"}}}}}}},"responses":{"200":{"description":"Positions response with per-token positions and aggregate PnL","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string"},"result":{"$ref":"#/components/schemas/PositionsResponse"},"id":{"type":"integer"}}}}}}}}}},"components":{"schemas":{"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"},"PositionsResponse":{"type":"object","description":"Account positions across all orderbooks with aggregate PnL.","properties":{"positions":{"type":"array","items":{"$ref":"#/components/schemas/Position"},"description":"Heterogeneous list of spot holdings and open perp positions."},"total_unrealized_pnl":{"type":"string","description":"Sum of `unrealized_pnl` across every spot holding and perp position (signed, 1e18 USD)."},"total_realized_pnl":{"type":"string","description":"Lifetime portfolio-wide spot realized PnL plus per-position realized PnL across currently-open perps. Closed perps' lifetime realized PnL is not retained (signed, 1e18 USD).\n"}}},"Position":{"description":"Tagged union: a single entry in `PositionsResponse.positions`. The `kind` field selects between a `SpotHolding` (one per token) or a `PerpPosition` (one per pair).\n","oneOf":[{"$ref":"#/components/schemas/SpotHolding"},{"$ref":"#/components/schemas/PerpPosition"}],"discriminator":{"propertyName":"kind","mapping":{"spot":"#/components/schemas/SpotHolding","perp":"#/components/schemas/PerpPosition"}}},"SpotHolding":{"type":"object","description":"A token balance with cost-basis tracking. One per token the wallet has touched on a spot market.","properties":{"kind":{"type":"string","enum":["spot"],"description":"Discriminator for the `Position` union."},"orderbook_id":{"$ref":"#/components/schemas/Bytes32"},"base_symbol":{"type":"string"},"quote_symbol":{"type":"string"},"balance":{"$ref":"#/components/schemas/HexUint256","description":"Total base tokens held for this market (free + locked, 1e18)."},"free_balance":{"$ref":"#/components/schemas/HexUint256","description":"Spendable portion of `balance` after sell-side order locks (1e18)."},"locked_balance":{"$ref":"#/components/schemas/HexUint256","description":"Base tokens locked in open sell orders (`balance - free_balance`, 1e18)."},"cost_basis":{"$ref":"#/components/schemas/HexUint256","description":"Total quote spent to acquire `balance` (1e18 USD)."},"mark_price":{"$ref":"#/components/schemas/HexUint256","description":"Last clearing price for this token's market (1e18)."},"unrealized_pnl":{"type":"string","description":"`(mark - avg_cost) Ć balance` (signed, 1e18 USD)."},"realized_pnl":{"type":"string","description":"Lifetime realized PnL on the user's spot trading (signed, 1e18 USD; portfolio-wide for v1)."}}},"Bytes32":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$","description":"32-byte value (hex-encoded with 0x prefix). Used for transaction hashes, orderbook IDs, etc."},"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"},"PerpPosition":{"type":"object","description":"A leveraged perp position. One per (user, pair).","properties":{"kind":{"type":"string","enum":["perp"],"description":"Discriminator for the `Position` union."},"orderbook_id":{"$ref":"#/components/schemas/Bytes32"},"base_symbol":{"type":"string"},"quote_symbol":{"type":"string"},"side":{"$ref":"#/components/schemas/PerpPositionSide"},"size":{"type":"string","description":"Signed position size in base units (1e18). Positive = long, negative = short."},"notional":{"$ref":"#/components/schemas/HexUint256","description":"`|size| Ć mark_price / 1e18` ā dollar value of exposure (1e18)."},"entry_price":{"$ref":"#/components/schemas/HexUint256","description":"Volume-weighted average entry price; updated only on opening fills (1e18)."},"mark_price":{"$ref":"#/components/schemas/HexUint256","description":"Latest mark price for the pair, post batch clearing (1e18)."},"margin":{"$ref":"#/components/schemas/HexUint256","description":"Allocated initial margin; cumulative across opens/increases, released proportionally on partial closes (1e18)."},"leverage":{"$ref":"#/components/schemas/HexUint256","description":"`notional Ć 1e18 / margin`. Effective leverage (0 if `margin` is 0)."},"funding_accrued":{"type":"string","description":"`(market.funding ā position.entry_funding) Ć size` (signed, 1e18 USD)."},"liquidation_price":{"$ref":"#/components/schemas/HexUint256","description":"Mark price at which this position would be liquidated against its own `margin` and the market's maintenance-margin rate. Funding ignored. 0 when position is empty."},"unrealized_pnl":{"type":"string","description":"`((mark ā entry) ā (funding ā entry_funding)) Ć size` (signed, 1e18 USD)."},"realized_pnl":{"type":"string","description":"Lifetime realized PnL on this position (signed, 1e18 USD). Resets to 0 when the position closes ā the next open of the same pair starts fresh."},"stop_loss":{"$ref":"#/components/schemas/HexUint256","description":"Reserved ā stop-loss not yet supported.","nullable":true},"take_profit":{"$ref":"#/components/schemas/HexUint256","description":"Reserved ā take-profit not yet supported.","nullable":true}}},"PerpPositionSide":{"type":"string","enum":["long","short"],"description":"Side of a perpetual position, derived from the sign of `size`."}}}}
```
## Get Account Fills
> 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).
```json
{"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"tags":[{"name":"Orderbook Data (ob_)","description":"Orderbook Data (`ob_`) is a read-focused API surface that provides access to\nmarkets and orderbook activity without requiring clients to run their own\nindexer or interact with the orderbook contracts directly. It is powered\nby a native indexer built into the Pod protocol, ensuring fast, consistent,\nand up-to-date views of on-chain state.\n\nThe API exposes live orderbook snapshots, historical OHLCV candles,\naccount-level order history and positions, making it ideal for trading\ninterfaces, analytics, and monitoring services.\n\nš This is a JSON-RPC 2.0 API. The request path is not important; the\nmethod to execute is defined by the method field in the request body. You\ncan send all requests to /, and any path after / is optional and used only\nfor documentation clarity.\n\n \n"}],"servers":[{"url":"https://rpc.podtestnet.dev/","description":"Pod testnet"}],"paths":{"/ob_getFills":{"post":{"tags":["Orderbook Data (ob_)"],"summary":"Get Account Fills","operationId":"ob_getFills","description":"Retrieves trade fills for a specific address within a time range.\n\nFills represent individual trade executions from batch auction settlements.\nA single order may produce multiple fills across different batches. Each fill\nincludes the clearing price, base and quote amounts, and the associated\norderbook and token addresses.\n\nResults are returned in descending order by timestamp (most recent first).\n","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method","params","id"],"properties":{"jsonrpc":{"type":"string","default":"2.0"},"method":{"type":"string","default":"ob_getFills"},"id":{"type":"integer","default":1},"params":{"type":"array","description":"Parameters:\n1. `address` (address): The address to get fills for\n2. `query` (object): Query parameters with required from_ts and optional to_ts, orderbook_id, and limit\n"}}}}}},"responses":{"200":{"description":"Object containing fills array","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string"},"result":{"$ref":"#/components/schemas/GetFillsResponse"},"id":{"type":"integer"}}}}}}}}}},"components":{"schemas":{"GetFillsResponse":{"type":"object","description":"Response containing a list of fills","properties":{"fills":{"type":"array","items":{"$ref":"#/components/schemas/FillResponse"},"description":"List of fills ordered by timestamp descending"}}},"FillResponse":{"type":"object","description":"A single trade fill from a batch auction settlement","properties":{"orderbook_id":{"$ref":"#/components/schemas/Bytes32","description":"The orderbook this fill belongs to"},"base_token":{"$ref":"#/components/schemas/Address","description":"Base token contract address"},"quote_token":{"$ref":"#/components/schemas/Address","description":"Quote token contract address"},"tx_hash":{"$ref":"#/components/schemas/Bytes32","description":"Transaction hash of the order that was filled"},"order_type":{"type":"string","enum":["limit","market"],"description":"Type of the order"},"initial_size":{"type":"string","description":"Initial order size (1e18); decimal string (signed int256). Positive for buy, negative for sell."},"fee":{"$ref":"#/components/schemas/HexUint256","description":"Accumulated fee for this order (1e18); hex-encoded. Currently always zero."},"base_amount":{"$ref":"#/components/schemas/HexUint256","description":"Base token amount filled in this settlement round (1e18); hex-encoded"},"quote_amount":{"$ref":"#/components/schemas/HexUint256","description":"Quote token amount filled in this settlement round (1e18); hex-encoded"},"timestamp":{"$ref":"#/components/schemas/Timestamp","description":"Timestamp of the batch settlement, in microseconds."},"price":{"$ref":"#/components/schemas/HexUint256","description":"Clearing price of the batch (1e18); hex-encoded"}}},"Bytes32":{"type":"string","pattern":"^0x[a-fA-F0-9]{64}$","description":"32-byte value (hex-encoded with 0x prefix). Used for transaction hashes, orderbook IDs, etc."},"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"},"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"},"Timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in microseconds (not milliseconds or seconds)"}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.v2.pod.network/guides-references/references/json-rpc/orderbook-data-ob_.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.