# Models ## The JsonRpcRequest object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"JsonRpcRequest":{"type":"object","description":"Standard JSON-RPC 2.0 request object","required":["jsonrpc","method","id"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"],"description":"JSON-RPC protocol version (always \"2.0\")"},"method":{"type":"string","description":"Name of the RPC method to invoke"},"params":{"type":"array","items":{},"description":"Method parameters as an array"},"id":{"oneOf":[{"type":"integer"},{"type":"string"}],"description":"Request identifier for correlating responses"}}}}}} ``` ## The JsonRpcResponse object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"JsonRpcResponse":{"type":"object","description":"Standard JSON-RPC 2.0 response object","required":["jsonrpc","id"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"result":{"description":"Result of the method call (mutually exclusive with error)"},"error":{"$ref":"#/components/schemas/JsonRpcError","description":"Error object if the call failed"},"id":{"oneOf":[{"type":"integer"},{"type":"string"}]}}},"JsonRpcError":{"type":"object","description":"JSON-RPC error object","required":["code","message"],"properties":{"code":{"type":"integer","description":"Numeric error code"},"message":{"type":"string","description":"Human-readable error message"},"data":{"description":"Additional error information"}}}}}} ``` ## The JsonRpcError object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"JsonRpcError":{"type":"object","description":"JSON-RPC error object","required":["code","message"],"properties":{"code":{"type":"integer","description":"Numeric error code"},"message":{"type":"string","description":"Human-readable error message"},"data":{"description":"Additional error information"}}}}}} ``` ## The Address object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"}}}} ``` ## The Bytes32 object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"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."}}}} ``` ## The HexBytes object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"HexBytes":{"type":"string","pattern":"^0x[a-fA-F0-9]*$","description":"Variable-length bytes (hex-encoded with 0x prefix). Length must be even."}}}} ``` ## The BridgeClaimProof object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"BridgeClaimProof":{"type":"object","description":"Proof data for claiming bridged assets on an external chain via the bridge contract's `claim` function.","required":["signatures","committee_epoch","proof"],"properties":{"signatures":{"$ref":"#/components/schemas/HexBytes","description":"Aggregated 65-byte ECDSA signatures (r, s, v) from validators, concatenated"},"committee_epoch":{"type":"integer","format":"uint64","description":"Committee epoch for signature verification"},"proof":{"$ref":"#/components/schemas/Bytes32","description":"Transaction hash (proof data for the claim)"}}},"HexBytes":{"type":"string","pattern":"^0x[a-fA-F0-9]*$","description":"Variable-length bytes (hex-encoded with 0x prefix). Length must be even."},"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."}}}} ``` ## The HexUint256 object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"}}}} ``` ## The DecimalUint256 object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"DecimalUint256":{"type":"string","pattern":"^[0-9]+$","description":"Unsigned 256-bit integer (decimal string representation)"}}}} ``` ## The Timestamp object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"Timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in microseconds (not milliseconds or seconds)"}}}} ``` ## The TimestampString object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"TimestampString":{"type":"string","pattern":"^[0-9]+$","description":"Unix timestamp in microseconds as a string"}}}} ``` ## The Side object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"Side":{"type":"string","enum":["Buy","Sell"],"description":"Order side - Buy (bid) or Sell (ask)"}}}} ``` ## The OrderStatus object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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"}}}} ``` ## The MarketType object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"MarketType":{"type":"string","enum":["spot","perpetual"],"description":"Type of market - spot trading or perpetual futures"}}}} ``` ## The CandleResolution object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"CandleResolution":{"type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time interval for OHLCV candles"}}}} ``` ## The OrderKind object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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"}}}} ``` ## The OrderDirection object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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"}}}} ``` ## The PartialFill object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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)"}}},"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)"}}}} ``` ## The Order object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"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"}}}} ``` ## The Candle object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"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)"}}}} ``` ## The Market object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"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)"}}}} ``` ## The TickSnapshot object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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)"}}}} ``` ## The OrderbookSnapshot object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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)"}}},"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."},"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)"}}}} ``` ## The PodAttestation object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"PodAttestation":{"type":"object","description":"Validator attestation for a transaction","properties":{"validator_address":{"$ref":"#/components/schemas/Address","description":"Address of the attesting validator"},"sequence_number":{"type":"integer","format":"int64","description":"Sequence number of the attestation"},"batch_index":{"type":"integer","description":"Index within the attestation batch"},"timestamp":{"$ref":"#/components/schemas/Timestamp","description":"Timestamp when the attestation was created (microseconds)"},"signature":{"type":"string","description":"Hex-encoded secp256k1 ECDSA signature"}}},"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"},"Timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in microseconds (not milliseconds or seconds)"}}}} ``` ## The PodMetadata object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"PodMetadata":{"type":"object","description":"Pod-specific metadata containing validator attestations for finality verification","properties":{"attestations":{"type":"array","items":{"$ref":"#/components/schemas/PodAttestation"},"description":"List of validator attestations for the transaction"},"committee_epoch":{"type":"integer","format":"int64","description":"The committee epoch during which the transaction was attested"}}},"PodAttestation":{"type":"object","description":"Validator attestation for a transaction","properties":{"validator_address":{"$ref":"#/components/schemas/Address","description":"Address of the attesting validator"},"sequence_number":{"type":"integer","format":"int64","description":"Sequence number of the attestation"},"batch_index":{"type":"integer","description":"Index within the attestation batch"},"timestamp":{"$ref":"#/components/schemas/Timestamp","description":"Timestamp when the attestation was created (microseconds)"},"signature":{"type":"string","description":"Hex-encoded secp256k1 ECDSA signature"}}},"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"},"Timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in microseconds (not milliseconds or seconds)"}}}} ``` ## The TransactionReceipt object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"TransactionReceipt":{"type":"object","description":"Transaction receipt with execution status, logs, and Pod-specific metadata","properties":{"type":{"type":"string","description":"Transaction type (EIP-2718)"},"status":{"type":"string","enum":["0x0","0x1"],"description":"Execution status - \"0x1\" for success, \"0x0\" for failure"},"cumulativeGasUsed":{"$ref":"#/components/schemas/HexUint256"},"logs":{"type":"array","items":{"$ref":"#/components/schemas/Log"}},"logsBloom":{"type":"string","description":"Bloom filter for logs (hex-encoded)"},"transactionHash":{"$ref":"#/components/schemas/Bytes32"},"transactionIndex":{"type":"string","description":"Transaction index in block (hex-encoded)"},"blockHash":{"$ref":"#/components/schemas/Bytes32"},"blockNumber":{"type":"string","description":"Block number (hex-encoded)"},"gasUsed":{"$ref":"#/components/schemas/HexUint256"},"effectiveGasPrice":{"$ref":"#/components/schemas/HexUint256"},"from":{"$ref":"#/components/schemas/Address"},"to":{"$ref":"#/components/schemas/Address"},"contractAddress":{"type":"string","nullable":true,"description":"Contract address if this was a contract creation (null otherwise)"},"pod_metadata":{"$ref":"#/components/schemas/PodMetadata","description":"Pod-specific attestation data for transaction finality verification"}}},"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"},"Log":{"type":"object","description":"Event log emitted during transaction execution","properties":{"address":{"$ref":"#/components/schemas/Address","description":"Address of the contract that emitted the log"},"topics":{"type":"array","items":{"$ref":"#/components/schemas/Bytes32"},"description":"Indexed event parameters"},"data":{"type":"string","description":"Non-indexed event data (hex-encoded)"}}},"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"},"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."},"PodMetadata":{"type":"object","description":"Pod-specific metadata containing validator attestations for finality verification","properties":{"attestations":{"type":"array","items":{"$ref":"#/components/schemas/PodAttestation"},"description":"List of validator attestations for the transaction"},"committee_epoch":{"type":"integer","format":"int64","description":"The committee epoch during which the transaction was attested"}}},"PodAttestation":{"type":"object","description":"Validator attestation for a transaction","properties":{"validator_address":{"$ref":"#/components/schemas/Address","description":"Address of the attesting validator"},"sequence_number":{"type":"integer","format":"int64","description":"Sequence number of the attestation"},"batch_index":{"type":"integer","description":"Index within the attestation batch"},"timestamp":{"$ref":"#/components/schemas/Timestamp","description":"Timestamp when the attestation was created (microseconds)"},"signature":{"type":"string","description":"Hex-encoded secp256k1 ECDSA signature"}}},"Timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in microseconds (not milliseconds or seconds)"}}}} ``` ## The Transaction object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"Transaction":{"type":"object","description":"Transaction object returned by eth_getTransactionByHash","properties":{"hash":{"$ref":"#/components/schemas/Bytes32"},"nonce":{"type":"string"},"blockHash":{"$ref":"#/components/schemas/Bytes32","nullable":true},"blockNumber":{"type":"string","nullable":true},"transactionIndex":{"type":"string","nullable":true},"from":{"$ref":"#/components/schemas/Address"},"to":{"$ref":"#/components/schemas/Address","nullable":true},"value":{"$ref":"#/components/schemas/HexUint256"},"gas":{"type":"string"},"gasPrice":{"type":"string"},"input":{"type":"string"},"v":{"type":"string"},"r":{"type":"string"},"s":{"type":"string"}}},"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)"}}}} ``` ## The Log object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"Log":{"type":"object","description":"Event log emitted during transaction execution","properties":{"address":{"$ref":"#/components/schemas/Address","description":"Address of the contract that emitted the log"},"topics":{"type":"array","items":{"$ref":"#/components/schemas/Bytes32"},"description":"Indexed event parameters"},"data":{"type":"string","description":"Non-indexed event data (hex-encoded)"}}},"Address":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$","description":"Ethereum address (20 bytes, hex-encoded with 0x prefix)"},"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."}}}} ``` ## The CandlesQuery object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"CandlesQuery":{"type":"object","description":"Query parameters for fetching historical candles","required":["resolution","from_ts"],"properties":{"resolution":{"$ref":"#/components/schemas/CandleResolution","description":"Candle time interval"},"from_ts":{"$ref":"#/components/schemas/Timestamp","description":"Start timestamp (inclusive) in microseconds"},"to_ts":{"$ref":"#/components/schemas/Timestamp","description":"End timestamp (inclusive) in microseconds. Defaults to current time if omitted."},"limit":{"type":"integer","description":"Maximum number of candles to return. No limit if omitted."}}},"CandleResolution":{"type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time interval for OHLCV candles"},"Timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in microseconds (not milliseconds or seconds)"}}}} ``` ## The OrdersQuery object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"OrdersQuery":{"type":"object","description":"Query parameters for ob_getOrders (address is passed as first param)","properties":{"orderbook_id":{"$ref":"#/components/schemas/Bytes32","description":"Optional filter by orderbook; omit for all orderbooks"},"limit":{"type":"integer","description":"Maximum number of orders to return"},"cursor":{"type":"string","description":"Pagination cursor from previous response"},"status":{"$ref":"#/components/schemas/OrderStatus","description":"Filter orders by status"}}},"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."},"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"}}}} ``` ## The FillsQuery object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"FillsQuery":{"type":"object","description":"Query parameters for ob_getFills (address is passed as first param)","required":["from_ts"],"properties":{"from_ts":{"$ref":"#/components/schemas/Timestamp","description":"Start timestamp (inclusive) in microseconds"},"to_ts":{"$ref":"#/components/schemas/Timestamp","description":"End timestamp (exclusive) in microseconds. Defaults to current time if omitted."},"orderbook_id":{"$ref":"#/components/schemas/Bytes32","description":"Optional filter by orderbook; omit for all orderbooks"},"limit":{"type":"integer","description":"Maximum number of fills to return (max 500). Defaults to 500."}}},"Timestamp":{"type":"integer","format":"int64","description":"Unix timestamp in microseconds (not milliseconds or seconds)"},"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."}}}} ``` ## The FillResponse object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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)"}}}} ``` ## The GetFillsResponse object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"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)"}}}} ``` ## The SubscriptionParams object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"SubscriptionParams":{"type":"object","description":"Parameters for WebSocket subscriptions","properties":{"depth":{"type":"integer","description":"Maximum price levels to include in orderbook snapshots"},"clob_ids":{"type":"array","items":{"$ref":"#/components/schemas/Bytes32"},"description":"List of orderbook (clob) IDs to subscribe to"}}},"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."}}}} ``` ## The PerpPositionSide object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"PerpPositionSide":{"type":"string","enum":["long","short"],"description":"Side of a perpetual position, derived from the sign of `size`."}}}} ``` ## The SpotHolding object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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)"}}}} ``` ## The PerpPosition object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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}}},"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."},"PerpPositionSide":{"type":"string","enum":["long","short"],"description":"Side of a perpetual position, derived from the sign of `size`."},"HexUint256":{"type":"string","pattern":"^0x[a-fA-F0-9]+$","description":"Unsigned 256-bit integer (hex-encoded with 0x prefix)"}}}} ``` ## The Position object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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`."}}}} ``` ## The PositionsResponse object ```json {"openapi":"3.0.0","info":{"title":"JSON-RPC API","version":"1.0.0"},"components":{"schemas":{"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`."}}}} ``` --- # 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/models.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.