{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://trade8.xyz/websocket-reference.json", "title": "Trade8 WebSocket Channel Messages", "description": "Subscribe commands and channel data envelopes. Session control frames are described in the WebSocket guide. All example values are illustrative.", "x-server": "wss://ws.trade8.xyz/v1", "$defs": { "Pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page; null at the end." }, "has_more": { "type": "boolean", "description": "True when another page is available." } }, "required": [ "next_cursor", "has_more" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "request_id": { "type": "string", "description": "Support correlation identifier; also returned in X-Request-ID." }, "error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation." }, "retryable": { "type": "boolean", "description": "Whether the operation may be retried after the documented recovery steps." }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "JSON field or query parameter." }, "reason": { "type": "string", "description": "Validation or policy reason." } }, "required": [ "field", "reason" ], "additionalProperties": false }, "description": "Field-level details; empty for errors without a specific field." } }, "required": [ "code", "message", "retryable", "details" ], "additionalProperties": false } }, "required": [ "request_id", "error" ], "additionalProperties": false }, "VenueStatus": { "type": "object", "properties": { "id": { "type": "string", "description": "Exchange identifier from GET /v1/venues, such as binance, okx, bybit, hyperliquid, or dydx." }, "name": { "type": "string", "description": "Exchange display name." }, "type": { "type": "string", "enum": [ "centralized", "decentralized" ], "description": "Exchange category." }, "status": { "type": "string", "enum": [ "operational", "degraded", "maintenance", "offline" ], "description": "Connection state in a streaming update." }, "order_types": { "type": "array", "items": { "type": "string", "description": "Order type." }, "description": "Enabled order types." }, "margin_modes": { "type": "array", "items": { "type": "string", "enum": [ "cross", "isolated" ], "description": "Margin mode." }, "description": "Available margin modes." }, "updated_at": { "type": "string", "format": "date-time", "description": "UTC timestamp in RFC 3339 format." } }, "required": [ "id", "name", "type", "status", "order_types", "margin_modes", "updated_at" ], "additionalProperties": false }, "Venue": { "type": "object", "properties": { "id": { "type": "string", "description": "Exchange identifier from GET /v1/venues, such as binance, okx, bybit, hyperliquid, or dydx." }, "name": { "type": "string", "description": "Exchange display name." }, "type": { "type": "string", "enum": [ "centralized", "decentralized" ], "description": "Exchange category." }, "website": { "type": "string", "description": "Official exchange website.", "format": "uri" } }, "required": [ "id", "name", "type", "website" ], "additionalProperties": false }, "PriceRule": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "fixed_tick" }, "tick_size": { "type": "string", "pattern": "^(?=.*[1-9])(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Price increment in price_unit." } }, "required": [ "type", "tick_size" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "significant_figures" }, "max_significant_figures": { "type": "integer", "minimum": 1, "description": "Maximum significant figures for non-integer prices." }, "max_decimal_places": { "type": "integer", "minimum": 0, "description": "Maximum decimal places." }, "integer_prices_allowed": { "type": "boolean", "description": "Integer prices may exceed the significant-figure limit." } }, "required": [ "type", "max_significant_figures", "max_decimal_places", "integer_prices_allowed" ], "additionalProperties": false } ] }, "VenueContract": { "type": "object", "properties": { "venue": { "type": "string", "description": "Exchange identifier from GET /v1/venues, such as binance, okx, bybit, hyperliquid, or dydx." }, "venue_instrument": { "type": "string", "description": "Native exchange symbol, such as BTCUSDT or BTC." }, "settlement_asset": { "type": "string", "description": "Asset symbol, such as BTC, USDT, or USDC." }, "settlement_assets": { "type": "array", "items": { "type": "string", "description": "Asset symbol, such as BTC, USDT, or USDC." }, "description": "Settlement tokens for a pool with side-dependent collateral." }, "network": { "type": "string", "description": "Blockchain network for an onchain pool." }, "payoff_type": { "type": "string", "enum": [ "linear", "inverse" ], "description": "Contract payoff where specified by the exchange." }, "contract_size": { "type": "string", "pattern": "^(?=.*[1-9])(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Value represented by one native contract." }, "contract_size_unit": { "type": "string", "description": "Unit of contract_size; multiply native contract quantity by contract_size to express face value." }, "quantity_unit": { "type": "string", "description": "Native size unit: base asset, USD, or contract. Read contract_size for lot-based contracts." }, "price_unit": { "type": "string", "description": "Price quote unit." }, "price_rule": { "$ref": "#/$defs/PriceRule", "description": "Fixed increment or significant-figure pricing rule." }, "quantity_step": { "type": "string", "pattern": "^(?=.*[1-9])(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Size increment in quantity_unit." }, "minimum_quantity": { "type": "string", "pattern": "^(?=.*[1-9])(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Exchange LOT_SIZE minimum for limit orders." }, "maximum_quantity": { "type": "string", "pattern": "^(?=.*[1-9])(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Exchange LOT_SIZE maximum for limit orders; market-order limits may differ." }, "minimum_notional": { "type": "string", "pattern": "^(?=.*[1-9])(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Minimum order value in price_unit." }, "max_leverage": { "type": "string", "pattern": "^(?=.*[1-9])(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Published exchange ceiling at snapshot time; account risk tiers can lower it." } }, "required": [ "venue", "venue_instrument", "quantity_unit", "price_unit" ], "additionalProperties": false }, "Market": { "type": "object", "properties": { "instrument": { "type": "string", "description": "Normalized perpetual family, for example BTC-PERP. Select a settlement asset and exchange to identify a contract." }, "contract_type": { "type": "string", "enum": [ "perpetual" ], "description": "Perpetual futures instrument family; payoff details belong to each exchange contract." }, "base_asset": { "type": "string", "description": "Asset symbol, such as BTC, USDT, or USDC." }, "contracts": { "type": "array", "items": { "$ref": "#/$defs/VenueContract" }, "description": "Native contract mappings, grouped under one perpetual instrument." } }, "required": [ "instrument", "contract_type", "base_asset", "contracts" ], "additionalProperties": false }, "PriceLevel": { "type": "object", "properties": { "price": { "type": "string", "pattern": "^(?=.*[1-9])(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Price in the contract quote asset." }, "quantity": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Absolute resting quantity in the contract base unit. Zero removes a level in a delta." } }, "required": [ "price", "quantity" ], "additionalProperties": false }, "OrderBook": { "type": "object", "properties": { "instrument": { "type": "string", "description": "Normalized perpetual family, for example BTC-PERP. Select a settlement asset and exchange to identify a contract." }, "venue": { "type": "string", "description": "Exchange identifier from GET /v1/venues, such as binance, okx, bybit, hyperliquid, or dydx." }, "settlement_asset": { "type": "string", "description": "Asset symbol, such as BTC, USDT, or USDC." }, "book_sequence": { "type": "integer", "minimum": 0, "description": "Monotonic sequence for this exchange/instrument book." }, "bids": { "type": "array", "items": { "$ref": "#/$defs/PriceLevel" }, "description": "Bids, highest price first." }, "asks": { "type": "array", "items": { "$ref": "#/$defs/PriceLevel" }, "description": "Asks, lowest price first." }, "updated_at": { "type": "string", "format": "date-time", "description": "UTC timestamp in RFC 3339 format." } }, "required": [ "instrument", "venue", "settlement_asset", "book_sequence", "bids", "asks", "updated_at" ], "additionalProperties": false }, "Ticker": { "type": "object", "properties": { "instrument": { "type": "string", "description": "Normalized perpetual family, for example BTC-PERP. Select a settlement asset and exchange to identify a contract." }, "venue": { "type": "string", "description": "Exchange identifier from GET /v1/venues, such as binance, okx, bybit, hyperliquid, or dydx." }, "settlement_asset": { "type": "string", "description": "Asset symbol, such as BTC, USDT, or USDC." }, "bid": { "type": "string", "pattern": "^(?=.*[1-9])(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Best bid price." }, "ask": { "type": "string", "pattern": "^(?=.*[1-9])(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Best ask price." }, "last": { "type": "string", "pattern": "^(?=.*[1-9])(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Last traded price." }, "mark_price": { "type": "string", "pattern": "^(?=.*[1-9])(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Exchange mark price used for risk calculations." }, "index_price": { "type": "string", "pattern": "^(?=.*[1-9])(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Exchange index price." }, "updated_at": { "type": "string", "format": "date-time", "description": "UTC timestamp in RFC 3339 format." } }, "required": [ "instrument", "venue", "settlement_asset", "bid", "ask", "last", "mark_price", "index_price", "updated_at" ], "additionalProperties": false }, "Trade": { "type": "object", "properties": { "trade_id": { "type": "string", "description": "Exchange trade identifier; deduplicate with venue." }, "instrument": { "type": "string", "description": "Normalized perpetual family, for example BTC-PERP. Select a settlement asset and exchange to identify a contract." }, "venue": { "type": "string", "description": "Exchange identifier from GET /v1/venues, such as binance, okx, bybit, hyperliquid, or dydx." }, "settlement_asset": { "type": "string", "description": "Asset symbol, such as BTC, USDT, or USDC." }, "side": { "type": "string", "enum": [ "buy", "sell" ], "description": "Aggressor side." }, "price": { "type": "string", "pattern": "^(?=.*[1-9])(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Execution price in the contract quote asset." }, "quantity": { "type": "string", "pattern": "^(?=.*[1-9])(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Base quantity executed." }, "executed_at": { "type": "string", "format": "date-time", "description": "UTC timestamp in RFC 3339 format." } }, "required": [ "trade_id", "instrument", "venue", "settlement_asset", "side", "price", "quantity", "executed_at" ], "additionalProperties": false }, "Funding": { "type": "object", "properties": { "instrument": { "type": "string", "description": "Normalized perpetual family, for example BTC-PERP. Select a settlement asset and exchange to identify a contract." }, "venue": { "type": "string", "description": "Exchange identifier from GET /v1/venues, such as binance, okx, bybit, hyperliquid, or dydx." }, "settlement_asset": { "type": "string", "description": "Asset symbol, such as BTC, USDT, or USDC." }, "rate": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Decimal funding rate for the stated interval: 0.0001 = 0.01%." }, "interval_hours": { "type": "string", "pattern": "^(?=.*[1-9])(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Hours covered by this rate." }, "next_funding_at": { "type": "string", "format": "date-time", "description": "UTC timestamp in RFC 3339 format." }, "type": { "type": "string", "enum": [ "indicative", "final" ], "description": "Indicative rates can change before settlement." } }, "required": [ "instrument", "venue", "settlement_asset", "rate", "interval_hours", "next_funding_at", "type" ], "additionalProperties": false }, "Account": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Trading account identifier within the authorized account grant." }, "name": { "type": "string", "description": "Account display name." }, "type": { "type": "string", "enum": [ "main", "subaccount" ], "description": "Account hierarchy role." }, "status": { "type": "string", "enum": [ "active", "read_only", "suspended" ], "description": "Account access state." }, "reporting_asset": { "type": "string", "description": "Asset symbol, such as BTC, USDT, or USDC." }, "enabled_venues": { "type": "array", "items": { "type": "string", "description": "Exchange identifier from GET /v1/venues, such as binance, okx, bybit, hyperliquid, or dydx." }, "description": "Exchanges enabled for this account." }, "created_at": { "type": "string", "format": "date-time", "description": "UTC timestamp in RFC 3339 format." } }, "required": [ "account_id", "name", "type", "status", "reporting_asset", "enabled_venues", "created_at" ], "additionalProperties": false }, "Balance": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Trading account identifier within the authorized account grant." }, "asset": { "type": "string", "description": "Asset symbol, such as BTC, USDT, or USDC." }, "total": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Ledger balance in this asset, excluding unrealized P&L." }, "available": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Uncommitted ledger balance." }, "committed": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Amount allocated or reserved. available + committed = total." }, "updated_at": { "type": "string", "format": "date-time", "description": "UTC timestamp in RFC 3339 format." } }, "required": [ "account_id", "asset", "total", "available", "committed", "updated_at" ], "additionalProperties": false }, "Fee": { "type": "object", "properties": { "venue": { "type": "string", "description": "Exchange identifier from GET /v1/venues, such as binance, okx, bybit, hyperliquid, or dydx." }, "instrument": { "type": "string", "description": "Normalized perpetual family, for example BTC-PERP. Select a settlement asset and exchange to identify a contract." }, "settlement_asset": { "type": "string", "description": "Asset symbol, such as BTC, USDT, or USDC." }, "maker_rate": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Decimal maker fee rate. Negative values indicate rebates." }, "taker_rate": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Decimal taker fee rate." }, "trade8_rate": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Additional Trade8 trading charge as a decimal rate." }, "effective_at": { "type": "string", "format": "date-time", "description": "UTC timestamp in RFC 3339 format." } }, "required": [ "venue", "instrument", "settlement_asset", "maker_rate", "taker_rate", "trade8_rate", "effective_at" ], "additionalProperties": false }, "Limits": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Trading account identifier within the authorized account grant." }, "rest_requests_per_second": { "type": "integer", "minimum": 1, "description": "Account REST request budget." }, "order_requests_per_second": { "type": "integer", "minimum": 1, "description": "Shared budget for order mutations." }, "websocket_connections": { "type": "integer", "minimum": 1, "description": "Concurrent authenticated connection limit." }, "subscriptions_per_connection": { "type": "integer", "minimum": 1, "description": "Channel subscriptions allowed on each connection." }, "batch_order_limit": { "type": "integer", "minimum": 1, "description": "Maximum orders in one batch." }, "effective_at": { "type": "string", "format": "date-time", "description": "UTC timestamp in RFC 3339 format." } }, "required": [ "account_id", "rest_requests_per_second", "order_requests_per_second", "websocket_connections", "subscriptions_per_connection", "batch_order_limit", "effective_at" ], "additionalProperties": false }, "ApiKey": { "type": "object", "properties": { "key_id": { "type": "string", "description": "Public key identifier; the secret is never returned by this endpoint." }, "label": { "type": "string", "description": "Key display label." }, "scopes": { "type": "array", "items": { "type": "string", "description": "Permission scope." }, "description": "Granted scopes." }, "account_ids": { "type": "array", "items": { "type": "string", "description": "Trading account identifier within the authorized account grant." }, "description": "Accounts the key may access." }, "ip_allowlist": { "type": "array", "items": { "type": "string", "description": "Allowed IPv4/IPv6 address or CIDR." }, "description": "Permitted source IP ranges." }, "status": { "type": "string", "enum": [ "active", "revoked", "expired" ], "description": "Key status." }, "expires_at": { "type": "string", "format": "date-time", "description": "UTC timestamp in RFC 3339 format." } }, "required": [ "key_id", "label", "scopes", "account_ids", "ip_allowlist", "status", "expires_at" ], "additionalProperties": false }, "VenuePolicy": { "type": "object", "properties": { "allowed": { "type": "array", "items": { "type": "string", "description": "Exchange identifier from GET /v1/venues, such as binance, okx, bybit, hyperliquid, or dydx." }, "description": "Only these exchanges may receive child orders.", "minItems": 1 }, "excluded": { "type": "array", "items": { "type": "string", "description": "Exchange identifier from GET /v1/venues, such as binance, okx, bybit, hyperliquid, or dydx." }, "description": "Exchanges excluded from routing; must be disjoint from allowed." }, "max_slippage_bps": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Maximum market-order slippage from the consolidated best price at acceptance, in basis points. Execution stops at this boundary." } }, "required": [], "additionalProperties": false }, "OrderRequest": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Trading account identifier within the authorized account grant." }, "client_order_id": { "type": "string", "description": "Unique client identifier within the account. Retain it for reconciliation.", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "instrument": { "type": "string", "description": "Normalized perpetual family, for example BTC-PERP. Select a settlement asset and exchange to identify a contract." }, "settlement_asset": { "type": "string", "description": "Asset symbol, such as BTC, USDT, or USDC." }, "side": { "type": "string", "enum": [ "buy", "sell" ], "description": "Trade direction." }, "type": { "type": "string", "enum": [ "market", "limit", "stop_market", "stop_limit", "take_profit_market", "take_profit_limit" ], "description": "Order type." }, "quantity": { "type": "string", "pattern": "^(?=.*[1-9])(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Order size in the market base unit." }, "limit_price": { "type": "string", "pattern": "^(?=.*[1-9])(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Required for limit, stop_limit, and take_profit_limit." }, "trigger_price": { "type": "string", "pattern": "^(?=.*[1-9])(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Required for stop and take-profit orders." }, "trigger_source": { "type": "string", "enum": [ "mark", "last", "index" ], "description": "Price used by a conditional order." }, "trigger_venue": { "type": "string", "description": "Exchange identifier from GET /v1/venues, such as binance, okx, bybit, hyperliquid, or dydx." }, "time_in_force": { "type": "string", "enum": [ "GTC", "IOC", "FOK" ], "description": "Limit orders: GTC, IOC, or FOK. Market orders: IOC. Default GTC for limit variants and IOC for market variants." }, "post_only": { "type": "boolean", "description": "Default false. Supported on ordinary GTC limit orders; crossing orders are rejected." }, "reduce_only": { "type": "boolean", "description": "Default false. Restricts fills to reducing the current exchange position." }, "routing": { "type": "string", "enum": [ "auto", "direct" ], "description": "Auto chooses eligible exchanges; direct requires exactly one allowed exchange." }, "venue_policy": { "$ref": "#/$defs/VenuePolicy" }, "self_trade_prevention": { "type": "string", "enum": [ "cancel_newest", "cancel_oldest", "cancel_both" ], "description": "Action when orders from the same account would match. Default cancel_newest." } }, "required": [ "account_id", "client_order_id", "instrument", "settlement_asset", "side", "type", "quantity", "routing" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "time_in_force": { "const": "FOK" } }, "required": [ "time_in_force" ] }, "then": { "properties": { "routing": { "const": "direct" } } } }, { "if": { "properties": { "type": { "enum": [ "limit", "stop_limit", "take_profit_limit" ] } }, "required": [ "type" ] }, "then": { "required": [ "limit_price" ] } }, { "if": { "properties": { "type": { "enum": [ "stop_market", "stop_limit", "take_profit_market", "take_profit_limit" ] } }, "required": [ "type" ] }, "then": { "required": [ "trigger_price", "trigger_source", "trigger_venue" ] } }, { "if": { "properties": { "type": { "enum": [ "market", "stop_market", "take_profit_market" ] } }, "required": [ "type" ] }, "then": { "properties": { "time_in_force": { "const": "IOC" }, "post_only": { "const": false } } } }, { "if": { "properties": { "post_only": { "const": true } }, "required": [ "post_only" ] }, "then": { "properties": { "type": { "const": "limit" }, "time_in_force": { "const": "GTC" } } } }, { "if": { "properties": { "routing": { "const": "direct" } }, "required": [ "routing" ] }, "then": { "required": [ "venue_policy" ], "properties": { "venue_policy": { "required": [ "allowed" ], "properties": { "allowed": { "minItems": 1, "maxItems": 1 } } } } } } ] }, "Order": { "type": "object", "properties": { "order_id": { "type": "string", "description": "Trade8 parent order identifier." }, "account_id": { "type": "string", "description": "Trading account identifier within the authorized account grant." }, "client_order_id": { "type": "string", "description": "Unique client identifier within the account. Retain it for reconciliation.", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "instrument": { "type": "string", "description": "Normalized perpetual family, for example BTC-PERP. Select a settlement asset and exchange to identify a contract." }, "settlement_asset": { "type": "string", "description": "Asset symbol, such as BTC, USDT, or USDC." }, "side": { "type": "string", "enum": [ "buy", "sell" ], "description": "Direction." }, "type": { "type": "string", "description": "Order type." }, "status": { "type": "string", "enum": [ "pending", "accepted", "trigger_pending", "partially_filled", "filled", "cancelled", "rejected", "expired" ], "description": "Current order lifecycle state." }, "requested_quantity": { "type": "string", "pattern": "^(?=.*[1-9])(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Total requested base quantity." }, "filled_quantity": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Cumulative executed base quantity." }, "remaining_quantity": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Quantity still open or awaiting execution. Zero after a terminal state." }, "cancelled_quantity": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Quantity cancelled, rejected, or expired without a fill." }, "average_fill_price": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Quantity-weighted price of actual fills; null before the first fill." }, "revision": { "type": "integer", "minimum": 1, "description": "Monotonic order revision. Use for optimistic concurrency and event reconciliation." }, "created_at": { "type": "string", "format": "date-time", "description": "UTC timestamp in RFC 3339 format." }, "updated_at": { "type": "string", "format": "date-time", "description": "UTC timestamp in RFC 3339 format." } }, "required": [ "order_id", "account_id", "client_order_id", "instrument", "settlement_asset", "side", "type", "status", "requested_quantity", "filled_quantity", "remaining_quantity", "cancelled_quantity", "average_fill_price", "revision", "created_at", "updated_at" ], "additionalProperties": false }, "Fill": { "type": "object", "properties": { "fill_id": { "type": "string", "description": "Unique Trade8 fill identifier." }, "order_id": { "type": "string", "description": "Parent order identifier." }, "account_id": { "type": "string", "description": "Trading account identifier within the authorized account grant." }, "instrument": { "type": "string", "description": "Normalized perpetual family, for example BTC-PERP. Select a settlement asset and exchange to identify a contract." }, "venue": { "type": "string", "description": "Exchange identifier from GET /v1/venues, such as binance, okx, bybit, hyperliquid, or dydx." }, "venue_order_id": { "type": "string", "description": "Native exchange order identifier." }, "settlement_asset": { "type": "string", "description": "Asset symbol, such as BTC, USDT, or USDC." }, "quantity": { "type": "string", "pattern": "^(?=.*[1-9])(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Executed base quantity." }, "price": { "type": "string", "pattern": "^(?=.*[1-9])(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Execution price in the quote asset." }, "fee": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Trading charge for this fill; negative indicates a rebate." }, "fee_asset": { "type": "string", "description": "Asset symbol, such as BTC, USDT, or USDC." }, "liquidity": { "type": "string", "enum": [ "maker", "taker" ], "description": "Liquidity role at execution." }, "executed_at": { "type": "string", "format": "date-time", "description": "UTC timestamp in RFC 3339 format." } }, "required": [ "fill_id", "order_id", "account_id", "instrument", "venue", "venue_order_id", "settlement_asset", "quantity", "price", "fee", "fee_asset", "liquidity", "executed_at" ], "additionalProperties": false }, "ChildOrder": { "type": "object", "properties": { "child_order_id": { "type": "string", "description": "Trade8 child identifier." }, "order_id": { "type": "string", "description": "Parent identifier." }, "venue": { "type": "string", "description": "Exchange identifier from GET /v1/venues, such as binance, okx, bybit, hyperliquid, or dydx." }, "venue_order_id": { "type": "string", "description": "Exchange order identifier." }, "quantity": { "type": "string", "pattern": "^(?=.*[1-9])(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Base quantity routed to this exchange." }, "filled_quantity": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Cumulative executed base quantity." }, "status": { "type": "string", "description": "Child lifecycle state." }, "updated_at": { "type": "string", "format": "date-time", "description": "UTC timestamp in RFC 3339 format." } }, "required": [ "child_order_id", "order_id", "venue", "venue_order_id", "quantity", "filled_quantity", "status", "updated_at" ], "additionalProperties": false }, "Cancellation": { "type": "object", "properties": { "order_id": { "type": "string", "description": "Parent identifier." }, "cancellation_status": { "type": "string", "enum": [ "pending", "completed" ], "description": "Follow the order stream or order lookup for the final quantities." }, "requested_at": { "type": "string", "format": "date-time", "description": "UTC timestamp in RFC 3339 format." } }, "required": [ "order_id", "cancellation_status", "requested_at" ], "additionalProperties": false }, "Position": { "type": "object", "properties": { "position_id": { "type": "string", "description": "Position identifier." }, "account_id": { "type": "string", "description": "Trading account identifier within the authorized account grant." }, "instrument": { "type": "string", "description": "Normalized perpetual family, for example BTC-PERP. Select a settlement asset and exchange to identify a contract." }, "venue": { "type": "string", "description": "Exchange identifier from GET /v1/venues, such as binance, okx, bybit, hyperliquid, or dydx." }, "settlement_asset": { "type": "string", "description": "Asset symbol, such as BTC, USDT, or USDC." }, "side": { "type": "string", "enum": [ "long", "short" ], "description": "Position direction." }, "quantity": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Absolute base quantity; zero marks a closed position update." }, "entry_price": { "type": "string", "pattern": "^(?=.*[1-9])(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Quantity-weighted entry price." }, "mark_price": { "type": "string", "pattern": "^(?=.*[1-9])(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Current exchange mark price." }, "unrealized_pnl": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Unrealized P&L in the settlement asset." }, "liquidation_price": { "type": [ "string", "null" ], "description": "Estimated exchange liquidation price, or null when unavailable." }, "leverage": { "type": "string", "pattern": "^(?=.*[1-9])(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Configured leverage multiplier." }, "margin_mode": { "type": "string", "enum": [ "cross", "isolated" ], "description": "Exchange margin mode." }, "updated_at": { "type": "string", "format": "date-time", "description": "UTC timestamp in RFC 3339 format." } }, "required": [ "position_id", "account_id", "instrument", "venue", "settlement_asset", "side", "quantity", "entry_price", "mark_price", "unrealized_pnl", "liquidation_price", "leverage", "margin_mode", "updated_at" ], "additionalProperties": false }, "MarginSetting": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Trading account identifier within the authorized account grant." }, "instrument": { "type": "string", "description": "Normalized perpetual family, for example BTC-PERP. Select a settlement asset and exchange to identify a contract." }, "venue": { "type": "string", "description": "Exchange identifier from GET /v1/venues, such as binance, okx, bybit, hyperliquid, or dydx." }, "settlement_asset": { "type": "string", "description": "Asset symbol, such as BTC, USDT, or USDC." }, "margin_mode": { "type": "string", "enum": [ "cross", "isolated" ], "description": "Cross shares eligible collateral within this exchange account; isolated reserves it for the position." }, "leverage": { "type": "string", "pattern": "^(?=.*[1-9])(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Requested leverage multiplier; validated against exchange and account risk tiers." }, "updated_at": { "type": "string", "format": "date-time", "description": "UTC timestamp in RFC 3339 format." } }, "required": [ "account_id", "instrument", "venue", "settlement_asset", "margin_mode", "leverage", "updated_at" ], "additionalProperties": false }, "Risk": { "type": "object", "properties": { "account_id": { "type": "string", "description": "Trading account identifier within the authorized account grant." }, "venue": { "type": "string", "description": "Exchange identifier from GET /v1/venues, such as binance, okx, bybit, hyperliquid, or dydx." }, "settlement_asset": { "type": "string", "description": "Asset symbol, such as BTC, USDT, or USDC." }, "equity": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Equity in settlement_asset, including unrealized P&L." }, "initial_margin": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Initial margin requirement." }, "maintenance_margin": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Maintenance margin requirement." }, "available_margin": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Margin available for new positions after reservations." }, "margin_ratio": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Maintenance margin / equity. Rising values indicate less headroom." }, "state": { "type": "string", "enum": [ "normal", "warning", "reduce_only", "liquidating" ], "description": "Exchange risk state." }, "updated_at": { "type": "string", "format": "date-time", "description": "UTC timestamp in RFC 3339 format." } }, "required": [ "account_id", "venue", "settlement_asset", "equity", "initial_margin", "maintenance_margin", "available_margin", "margin_ratio", "state", "updated_at" ], "additionalProperties": false }, "Custodian": { "type": "object", "properties": { "id": { "type": "string", "description": "Custodian identifier from the integration catalog." }, "name": { "type": "string", "description": "Custodian display name." }, "services": { "type": "array", "items": { "type": "string", "enum": [ "custody", "off_exchange_collateral" ], "description": "Supported service." }, "description": "Services enabled for this integration." } }, "required": [ "id", "name", "services" ], "additionalProperties": false }, "CustodyAccount": { "type": "object", "properties": { "custody_account_id": { "type": "string", "description": "Linked custody account identifier." }, "account_id": { "type": "string", "description": "Trading account identifier within the authorized account grant." }, "custodian": { "type": "string", "description": "Custodian identifier, such as ceffu, copper, bitgo, or coinbase." }, "asset": { "type": "string", "description": "Asset symbol, such as BTC, USDT, or USDC." }, "balance": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Custody ledger balance in this asset." }, "allocated": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Amount committed to exchange collateral." }, "available": { "type": "string", "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Unallocated custody balance." }, "eligible_venues": { "type": "array", "items": { "type": "string", "description": "Exchange identifier from GET /v1/venues, such as binance, okx, bybit, hyperliquid, or dydx." }, "description": "Exchanges enabled for off-exchange allocation from this custody account." }, "updated_at": { "type": "string", "format": "date-time", "description": "UTC timestamp in RFC 3339 format." } }, "required": [ "custody_account_id", "account_id", "custodian", "asset", "balance", "allocated", "available", "eligible_venues", "updated_at" ], "additionalProperties": false }, "Allocation": { "type": "object", "properties": { "allocation_id": { "type": "string", "description": "Collateral allocation identifier." }, "account_id": { "type": "string", "description": "Trading account identifier within the authorized account grant." }, "client_allocation_id": { "type": "string", "description": "Unique client identifier within the account. Retain it for reconciliation.", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "custody_account_id": { "type": "string", "description": "Source custody account." }, "custodian": { "type": "string", "description": "Custodian identifier." }, "venue": { "type": "string", "description": "Exchange identifier from GET /v1/venues, such as binance, okx, bybit, hyperliquid, or dydx." }, "asset": { "type": "string", "description": "Asset symbol, such as BTC, USDT, or USDC." }, "amount": { "type": "string", "pattern": "^(?=.*[1-9])(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Amount in asset units." }, "status": { "type": "string", "enum": [ "pending", "active", "releasing", "released", "rejected" ], "description": "Active means the exchange has acknowledged usable collateral." }, "updated_at": { "type": "string", "format": "date-time", "description": "UTC timestamp in RFC 3339 format." } }, "required": [ "allocation_id", "account_id", "client_allocation_id", "custody_account_id", "custodian", "venue", "asset", "amount", "status", "updated_at" ], "additionalProperties": false }, "Settlement": { "type": "object", "properties": { "settlement_id": { "type": "string", "description": "Settlement record identifier." }, "account_id": { "type": "string", "description": "Trading account identifier within the authorized account grant." }, "custodian": { "type": "string", "description": "Custodian identifier." }, "venue": { "type": "string", "description": "Exchange identifier from GET /v1/venues, such as binance, okx, bybit, hyperliquid, or dydx." }, "asset": { "type": "string", "description": "Asset symbol, such as BTC, USDT, or USDC." }, "amount": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Positive credits the custody account; negative debits it." }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "failed" ], "description": "Settlement processing state." }, "cycle_start": { "type": "string", "format": "date-time", "description": "UTC timestamp in RFC 3339 format." }, "cycle_end": { "type": "string", "format": "date-time", "description": "UTC timestamp in RFC 3339 format." }, "updated_at": { "type": "string", "format": "date-time", "description": "UTC timestamp in RFC 3339 format." } }, "required": [ "settlement_id", "account_id", "custodian", "venue", "asset", "amount", "status", "cycle_start", "cycle_end", "updated_at" ], "additionalProperties": false }, "Deposit": { "type": "object", "properties": { "deposit_id": { "type": "string", "description": "Deposit identifier." }, "account_id": { "type": "string", "description": "Trading account identifier within the authorized account grant." }, "asset": { "type": "string", "description": "Asset symbol, such as BTC, USDT, or USDC." }, "network": { "type": "string", "description": "Blockchain network identifier, such as ethereum or bitcoin." }, "amount": { "type": "string", "pattern": "^(?=.*[1-9])(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Received amount in asset units." }, "confirmations": { "type": "integer", "minimum": 0, "description": "Observed confirmations." }, "required_confirmations": { "type": "integer", "minimum": 1, "description": "Confirmation threshold for this deposit." }, "status": { "type": "string", "enum": [ "detected", "confirming", "review", "credited", "rejected" ], "description": "Credited means the amount is included in the ledger balance." }, "updated_at": { "type": "string", "format": "date-time", "description": "UTC timestamp in RFC 3339 format." } }, "required": [ "deposit_id", "account_id", "asset", "network", "amount", "confirmations", "required_confirmations", "status", "updated_at" ], "additionalProperties": false }, "Transfer": { "type": "object", "properties": { "transfer_id": { "type": "string", "description": "Internal transfer identifier." }, "client_transfer_id": { "type": "string", "description": "Unique client identifier within the account. Retain it for reconciliation.", "pattern": "^[A-Za-z0-9_-]{1,64}$" }, "from_account_id": { "type": "string", "description": "Trading account identifier within the authorized account grant." }, "to_account_id": { "type": "string", "description": "Trading account identifier within the authorized account grant." }, "asset": { "type": "string", "description": "Asset symbol, such as BTC, USDT, or USDC." }, "amount": { "type": "string", "pattern": "^(?=.*[1-9])(0|[1-9][0-9]*)(\\.[0-9]+)?$", "description": "Transfer amount in asset units." }, "status": { "type": "string", "enum": [ "pending", "completed", "rejected" ], "description": "Internal transfer processing state." }, "created_at": { "type": "string", "format": "date-time", "description": "UTC timestamp in RFC 3339 format." }, "updated_at": { "type": "string", "format": "date-time", "description": "UTC timestamp in RFC 3339 format." } }, "required": [ "transfer_id", "client_transfer_id", "from_account_id", "to_account_id", "asset", "amount", "status", "created_at", "updated_at" ], "additionalProperties": false }, "MarketDetail": { "type": "object", "properties": { "instrument": { "type": "string", "description": "Normalized perpetual family, for example BTC-PERP. Select a settlement asset and exchange to identify a contract." }, "contract_type": { "type": "string", "enum": [ "perpetual" ], "description": "Perpetual futures instrument family; payoff details belong to each exchange contract." }, "base_asset": { "type": "string", "description": "Asset symbol, such as BTC, USDT, or USDC." }, "contracts": { "type": "array", "items": { "$ref": "#/$defs/VenueContract" }, "description": "Native contract mappings, grouped under one perpetual instrument." } }, "required": [ "instrument", "contract_type", "base_asset", "contracts" ], "additionalProperties": false }, "MarketCatalog": { "type": "object", "properties": { "markets": { "type": "array", "items": { "$ref": "#/$defs/Market" }, "description": "Instruments on this page." }, "pagination": { "$ref": "#/$defs/Pagination" } }, "required": [ "markets", "pagination" ], "additionalProperties": false }, "VenueCatalog": { "type": "object", "properties": { "venues": { "type": "array", "items": { "$ref": "#/$defs/Venue" }, "description": "Exchanges on this page." }, "pagination": { "$ref": "#/$defs/Pagination" } }, "required": [ "venues", "pagination" ], "additionalProperties": false } }, "oneOf": [ { "type": "object", "properties": { "op": { "const": "subscribe" }, "id": { "type": "string", "description": "Request ID unique on this connection.", "minLength": 1, "maxLength": 64 }, "channel": { "const": "ticker" }, "instrument": { "type": "string", "description": "Normalized perpetual family." }, "venue": { "type": "string", "description": "Exchange identifier." }, "settlement_asset": { "type": "string", "description": "Contract settlement asset." } }, "required": [ "op", "id", "channel", "instrument", "venue", "settlement_asset" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "const": "data" }, "subscription_id": { "type": "string", "description": "Connection-local subscription identifier." }, "channel": { "const": "ticker" }, "type": { "type": "string", "enum": [ "snapshot", "update" ], "description": "Snapshot replaces state; update semantics are defined per channel." }, "sequence": { "type": "integer", "minimum": 1, "description": "Monotonic per subscription; starts at 1." }, "previous_sequence": { "type": "integer", "minimum": 0, "description": "Preceding sequence, or 0 for the first message." }, "timestamp": { "type": "string", "format": "date-time", "description": "UTC envelope timestamp." }, "data": { "type": "array", "items": { "$ref": "#/$defs/Ticker" }, "description": "Zero or more channel records. An empty snapshot clears previous state." } }, "required": [ "op", "subscription_id", "channel", "type", "sequence", "previous_sequence", "timestamp", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "const": "subscribe" }, "id": { "type": "string", "description": "Request ID unique on this connection.", "minLength": 1, "maxLength": 64 }, "channel": { "const": "orderbook" }, "instrument": { "type": "string", "description": "Normalized perpetual family." }, "venue": { "type": "string", "description": "Exchange identifier." }, "settlement_asset": { "type": "string", "description": "Contract settlement asset." }, "depth": { "type": "integer", "enum": [ 10, 20, 50 ] } }, "required": [ "op", "id", "channel", "instrument", "venue", "settlement_asset" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "const": "data" }, "subscription_id": { "type": "string", "description": "Connection-local subscription identifier." }, "channel": { "const": "orderbook" }, "type": { "type": "string", "enum": [ "snapshot", "update" ], "description": "Snapshot replaces state; update semantics are defined per channel." }, "sequence": { "type": "integer", "minimum": 1, "description": "Monotonic per subscription; starts at 1." }, "previous_sequence": { "type": "integer", "minimum": 0, "description": "Preceding sequence, or 0 for the first message." }, "timestamp": { "type": "string", "format": "date-time", "description": "UTC envelope timestamp." }, "data": { "type": "array", "items": { "$ref": "#/$defs/OrderBook" }, "description": "Zero or more channel records. An empty snapshot clears previous state." } }, "required": [ "op", "subscription_id", "channel", "type", "sequence", "previous_sequence", "timestamp", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "const": "subscribe" }, "id": { "type": "string", "description": "Request ID unique on this connection.", "minLength": 1, "maxLength": 64 }, "channel": { "const": "trades" }, "instrument": { "type": "string", "description": "Normalized perpetual family." }, "venue": { "type": "string", "description": "Exchange identifier." }, "settlement_asset": { "type": "string", "description": "Contract settlement asset." } }, "required": [ "op", "id", "channel", "instrument", "venue", "settlement_asset" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "const": "data" }, "subscription_id": { "type": "string", "description": "Connection-local subscription identifier." }, "channel": { "const": "trades" }, "type": { "type": "string", "enum": [ "snapshot", "update" ], "description": "Snapshot replaces state; update semantics are defined per channel." }, "sequence": { "type": "integer", "minimum": 1, "description": "Monotonic per subscription; starts at 1." }, "previous_sequence": { "type": "integer", "minimum": 0, "description": "Preceding sequence, or 0 for the first message." }, "timestamp": { "type": "string", "format": "date-time", "description": "UTC envelope timestamp." }, "data": { "type": "array", "items": { "$ref": "#/$defs/Trade" }, "description": "Zero or more channel records. An empty snapshot clears previous state." } }, "required": [ "op", "subscription_id", "channel", "type", "sequence", "previous_sequence", "timestamp", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "const": "subscribe" }, "id": { "type": "string", "description": "Request ID unique on this connection.", "minLength": 1, "maxLength": 64 }, "channel": { "const": "funding" }, "instrument": { "type": "string", "description": "Normalized perpetual family." }, "venue": { "type": "string", "description": "Exchange identifier." }, "settlement_asset": { "type": "string", "description": "Contract settlement asset." } }, "required": [ "op", "id", "channel", "instrument", "venue", "settlement_asset" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "const": "data" }, "subscription_id": { "type": "string", "description": "Connection-local subscription identifier." }, "channel": { "const": "funding" }, "type": { "type": "string", "enum": [ "snapshot", "update" ], "description": "Snapshot replaces state; update semantics are defined per channel." }, "sequence": { "type": "integer", "minimum": 1, "description": "Monotonic per subscription; starts at 1." }, "previous_sequence": { "type": "integer", "minimum": 0, "description": "Preceding sequence, or 0 for the first message." }, "timestamp": { "type": "string", "format": "date-time", "description": "UTC envelope timestamp." }, "data": { "type": "array", "items": { "$ref": "#/$defs/Funding" }, "description": "Zero or more channel records. An empty snapshot clears previous state." } }, "required": [ "op", "subscription_id", "channel", "type", "sequence", "previous_sequence", "timestamp", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "const": "subscribe" }, "id": { "type": "string", "description": "Request ID unique on this connection.", "minLength": 1, "maxLength": 64 }, "channel": { "const": "venue_status" } }, "required": [ "op", "id", "channel" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "const": "data" }, "subscription_id": { "type": "string", "description": "Connection-local subscription identifier." }, "channel": { "const": "venue_status" }, "type": { "type": "string", "enum": [ "snapshot", "update" ], "description": "Snapshot replaces state; update semantics are defined per channel." }, "sequence": { "type": "integer", "minimum": 1, "description": "Monotonic per subscription; starts at 1." }, "previous_sequence": { "type": "integer", "minimum": 0, "description": "Preceding sequence, or 0 for the first message." }, "timestamp": { "type": "string", "format": "date-time", "description": "UTC envelope timestamp." }, "data": { "type": "array", "items": { "$ref": "#/$defs/VenueStatus" }, "description": "Zero or more channel records. An empty snapshot clears previous state." } }, "required": [ "op", "subscription_id", "channel", "type", "sequence", "previous_sequence", "timestamp", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "const": "subscribe" }, "id": { "type": "string", "description": "Request ID unique on this connection.", "minLength": 1, "maxLength": 64 }, "channel": { "const": "orders" }, "account_id": { "type": "string", "description": "An account authorized for the authenticated key." } }, "required": [ "op", "id", "channel", "account_id" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "const": "data" }, "subscription_id": { "type": "string", "description": "Connection-local subscription identifier." }, "channel": { "const": "orders" }, "type": { "type": "string", "enum": [ "snapshot", "update" ], "description": "Snapshot replaces state; update semantics are defined per channel." }, "sequence": { "type": "integer", "minimum": 1, "description": "Monotonic per subscription; starts at 1." }, "previous_sequence": { "type": "integer", "minimum": 0, "description": "Preceding sequence, or 0 for the first message." }, "timestamp": { "type": "string", "format": "date-time", "description": "UTC envelope timestamp." }, "data": { "type": "array", "items": { "$ref": "#/$defs/Order" }, "description": "Zero or more channel records. An empty snapshot clears previous state." } }, "required": [ "op", "subscription_id", "channel", "type", "sequence", "previous_sequence", "timestamp", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "const": "subscribe" }, "id": { "type": "string", "description": "Request ID unique on this connection.", "minLength": 1, "maxLength": 64 }, "channel": { "const": "fills" }, "account_id": { "type": "string", "description": "An account authorized for the authenticated key." } }, "required": [ "op", "id", "channel", "account_id" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "const": "data" }, "subscription_id": { "type": "string", "description": "Connection-local subscription identifier." }, "channel": { "const": "fills" }, "type": { "type": "string", "enum": [ "snapshot", "update" ], "description": "Snapshot replaces state; update semantics are defined per channel." }, "sequence": { "type": "integer", "minimum": 1, "description": "Monotonic per subscription; starts at 1." }, "previous_sequence": { "type": "integer", "minimum": 0, "description": "Preceding sequence, or 0 for the first message." }, "timestamp": { "type": "string", "format": "date-time", "description": "UTC envelope timestamp." }, "data": { "type": "array", "items": { "$ref": "#/$defs/Fill" }, "description": "Zero or more channel records. An empty snapshot clears previous state." } }, "required": [ "op", "subscription_id", "channel", "type", "sequence", "previous_sequence", "timestamp", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "const": "subscribe" }, "id": { "type": "string", "description": "Request ID unique on this connection.", "minLength": 1, "maxLength": 64 }, "channel": { "const": "positions" }, "account_id": { "type": "string", "description": "An account authorized for the authenticated key." } }, "required": [ "op", "id", "channel", "account_id" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "const": "data" }, "subscription_id": { "type": "string", "description": "Connection-local subscription identifier." }, "channel": { "const": "positions" }, "type": { "type": "string", "enum": [ "snapshot", "update" ], "description": "Snapshot replaces state; update semantics are defined per channel." }, "sequence": { "type": "integer", "minimum": 1, "description": "Monotonic per subscription; starts at 1." }, "previous_sequence": { "type": "integer", "minimum": 0, "description": "Preceding sequence, or 0 for the first message." }, "timestamp": { "type": "string", "format": "date-time", "description": "UTC envelope timestamp." }, "data": { "type": "array", "items": { "$ref": "#/$defs/Position" }, "description": "Zero or more channel records. An empty snapshot clears previous state." } }, "required": [ "op", "subscription_id", "channel", "type", "sequence", "previous_sequence", "timestamp", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "const": "subscribe" }, "id": { "type": "string", "description": "Request ID unique on this connection.", "minLength": 1, "maxLength": 64 }, "channel": { "const": "balances" }, "account_id": { "type": "string", "description": "An account authorized for the authenticated key." } }, "required": [ "op", "id", "channel", "account_id" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "const": "data" }, "subscription_id": { "type": "string", "description": "Connection-local subscription identifier." }, "channel": { "const": "balances" }, "type": { "type": "string", "enum": [ "snapshot", "update" ], "description": "Snapshot replaces state; update semantics are defined per channel." }, "sequence": { "type": "integer", "minimum": 1, "description": "Monotonic per subscription; starts at 1." }, "previous_sequence": { "type": "integer", "minimum": 0, "description": "Preceding sequence, or 0 for the first message." }, "timestamp": { "type": "string", "format": "date-time", "description": "UTC envelope timestamp." }, "data": { "type": "array", "items": { "$ref": "#/$defs/Balance" }, "description": "Zero or more channel records. An empty snapshot clears previous state." } }, "required": [ "op", "subscription_id", "channel", "type", "sequence", "previous_sequence", "timestamp", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "const": "subscribe" }, "id": { "type": "string", "description": "Request ID unique on this connection.", "minLength": 1, "maxLength": 64 }, "channel": { "const": "risk" }, "account_id": { "type": "string", "description": "An account authorized for the authenticated key." } }, "required": [ "op", "id", "channel", "account_id" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "const": "data" }, "subscription_id": { "type": "string", "description": "Connection-local subscription identifier." }, "channel": { "const": "risk" }, "type": { "type": "string", "enum": [ "snapshot", "update" ], "description": "Snapshot replaces state; update semantics are defined per channel." }, "sequence": { "type": "integer", "minimum": 1, "description": "Monotonic per subscription; starts at 1." }, "previous_sequence": { "type": "integer", "minimum": 0, "description": "Preceding sequence, or 0 for the first message." }, "timestamp": { "type": "string", "format": "date-time", "description": "UTC envelope timestamp." }, "data": { "type": "array", "items": { "$ref": "#/$defs/Risk" }, "description": "Zero or more channel records. An empty snapshot clears previous state." } }, "required": [ "op", "subscription_id", "channel", "type", "sequence", "previous_sequence", "timestamp", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "const": "subscribe" }, "id": { "type": "string", "description": "Request ID unique on this connection.", "minLength": 1, "maxLength": 64 }, "channel": { "const": "collateral" }, "account_id": { "type": "string", "description": "An account authorized for the authenticated key." } }, "required": [ "op", "id", "channel", "account_id" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "const": "data" }, "subscription_id": { "type": "string", "description": "Connection-local subscription identifier." }, "channel": { "const": "collateral" }, "type": { "type": "string", "enum": [ "snapshot", "update" ], "description": "Snapshot replaces state; update semantics are defined per channel." }, "sequence": { "type": "integer", "minimum": 1, "description": "Monotonic per subscription; starts at 1." }, "previous_sequence": { "type": "integer", "minimum": 0, "description": "Preceding sequence, or 0 for the first message." }, "timestamp": { "type": "string", "format": "date-time", "description": "UTC envelope timestamp." }, "data": { "type": "array", "items": { "$ref": "#/$defs/Allocation" }, "description": "Zero or more channel records. An empty snapshot clears previous state." } }, "required": [ "op", "subscription_id", "channel", "type", "sequence", "previous_sequence", "timestamp", "data" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "const": "subscribe" }, "id": { "type": "string", "description": "Request ID unique on this connection.", "minLength": 1, "maxLength": 64 }, "channel": { "const": "settlements" }, "account_id": { "type": "string", "description": "An account authorized for the authenticated key." } }, "required": [ "op", "id", "channel", "account_id" ], "additionalProperties": false }, { "type": "object", "properties": { "op": { "const": "data" }, "subscription_id": { "type": "string", "description": "Connection-local subscription identifier." }, "channel": { "const": "settlements" }, "type": { "type": "string", "enum": [ "snapshot", "update" ], "description": "Snapshot replaces state; update semantics are defined per channel." }, "sequence": { "type": "integer", "minimum": 1, "description": "Monotonic per subscription; starts at 1." }, "previous_sequence": { "type": "integer", "minimum": 0, "description": "Preceding sequence, or 0 for the first message." }, "timestamp": { "type": "string", "format": "date-time", "description": "UTC envelope timestamp." }, "data": { "type": "array", "items": { "$ref": "#/$defs/Settlement" }, "description": "Zero or more channel records. An empty snapshot clears previous state." } }, "required": [ "op", "subscription_id", "channel", "type", "sequence", "previous_sequence", "timestamp", "data" ], "additionalProperties": false } ], "x-channels": [ { "name": "ticker", "scope": "public", "initial": "Snapshot, followed by complete ticker replacements.", "recovery": "Resubscribe for a fresh snapshot.", "subscribe": { "op": "subscribe", "id": "subscribe-ticker", "channel": "ticker", "instrument": "BTC-PERP", "venue": "hyperliquid", "settlement_asset": "USDC" }, "message": { "op": "data", "subscription_id": "sub_example_ticker", "channel": "ticker", "type": "snapshot", "sequence": 1, "previous_sequence": 0, "timestamp": "2026-08-31T12:00:00.000Z", "data": [ { "instrument": "BTC-PERP", "venue": "hyperliquid", "settlement_asset": "USDC", "bid": "76999", "ask": "77001", "last": "77000", "mark_price": "77000", "index_price": "76998", "updated_at": "2026-08-31T12:00:00.000Z" } ] } }, { "name": "orderbook", "scope": "public", "initial": "Full snapshot, then price-level deltas. Zero quantity removes a price level. Each delta includes all changes needed to maintain the requested depth.", "recovery": "Pause book-dependent decisions after a gap. Resubscribe and replace the full book with the next snapshot.", "subscribe": { "op": "subscribe", "id": "subscribe-orderbook", "channel": "orderbook", "instrument": "BTC-PERP", "venue": "hyperliquid", "settlement_asset": "USDC", "depth": 20 }, "message": { "op": "data", "subscription_id": "sub_example_orderbook", "channel": "orderbook", "type": "snapshot", "sequence": 1, "previous_sequence": 0, "timestamp": "2026-08-31T12:00:00.000Z", "data": [ { "instrument": "BTC-PERP", "venue": "hyperliquid", "settlement_asset": "USDC", "book_sequence": 1042, "bids": [ { "price": "76999", "quantity": "1.25000" } ], "asks": [ { "price": "77001", "quantity": "0.90000" } ], "updated_at": "2026-08-31T12:00:00.000Z" } ] } }, { "name": "trades", "scope": "public", "initial": "Live updates after the subscription acknowledgement.", "recovery": "Backfill market trades from the last saved executed_at, then deduplicate by venue and trade_id.", "subscribe": { "op": "subscribe", "id": "subscribe-trades", "channel": "trades", "instrument": "BTC-PERP", "venue": "hyperliquid", "settlement_asset": "USDC" }, "message": { "op": "data", "subscription_id": "sub_example_trades", "channel": "trades", "type": "update", "sequence": 2, "previous_sequence": 1, "timestamp": "2026-08-31T12:00:00.000Z", "data": [ { "trade_id": "trade_example_01", "instrument": "BTC-PERP", "venue": "hyperliquid", "settlement_asset": "USDC", "side": "buy", "price": "77001", "quantity": "0.01000", "executed_at": "2026-08-31T12:00:00.000Z" } ] } }, { "name": "funding", "scope": "public", "initial": "Snapshot, followed by complete funding records.", "recovery": "Read the current rate and resubscribe.", "subscribe": { "op": "subscribe", "id": "subscribe-funding", "channel": "funding", "instrument": "BTC-PERP", "venue": "binance", "settlement_asset": "USDT" }, "message": { "op": "data", "subscription_id": "sub_example_funding", "channel": "funding", "type": "snapshot", "sequence": 1, "previous_sequence": 0, "timestamp": "2026-08-31T12:00:00.000Z", "data": [ { "instrument": "BTC-PERP", "venue": "binance", "settlement_asset": "USDT", "rate": "0.0001", "interval_hours": "8", "next_funding_at": "2026-08-31T16:00:00.000Z", "type": "indicative" } ] } }, { "name": "venue_status", "scope": "public", "initial": "Snapshot of all exchanges, then changed exchange records.", "recovery": "Use the directory for exchange IDs. Resubscribe and wait for a fresh connectivity snapshot before routing.", "subscribe": { "op": "subscribe", "id": "subscribe-venue_status", "channel": "venue_status" }, "message": { "op": "data", "subscription_id": "sub_example_venue_status", "channel": "venue_status", "type": "snapshot", "sequence": 1, "previous_sequence": 0, "timestamp": "2026-08-31T12:00:00.000Z", "data": [ { "id": "hyperliquid", "name": "Hyperliquid", "type": "decentralized", "status": "operational", "order_types": [ "market", "limit" ], "margin_modes": [ "cross", "isolated" ], "updated_at": "2026-08-31T12:00:00.000Z" } ] } }, { "name": "orders", "scope": "orders:read", "initial": "Snapshot of open orders, then complete records for changed orders, including terminal states.", "recovery": "Resubscribe for open orders, then reconcile tracked order IDs through REST. Keep the highest revision for each order.", "subscribe": { "op": "subscribe", "id": "subscribe-orders", "channel": "orders", "account_id": "acct_example_main" }, "message": { "op": "data", "subscription_id": "sub_example_orders", "channel": "orders", "type": "update", "sequence": 2, "previous_sequence": 1, "timestamp": "2026-08-31T12:00:00.000Z", "data": [ { "order_id": "ord_example_01", "account_id": "acct_example_main", "client_order_id": "strategy-a-0001", "instrument": "BTC-PERP", "settlement_asset": "USDT", "side": "buy", "type": "limit", "status": "partially_filled", "requested_quantity": "0.100", "filled_quantity": "0.060", "remaining_quantity": "0.040", "cancelled_quantity": "0.000", "average_fill_price": "77000.00", "revision": 2, "created_at": "2026-08-31T12:00:00.000Z", "updated_at": "2026-08-31T12:00:00.250Z" } ] } }, { "name": "fills", "scope": "orders:read", "initial": "Live updates after the subscription acknowledgement.", "recovery": "Buffer live events while paging GET /v1/fills from the last saved executed_at through the acknowledgement started_at. Deduplicate on fill_id.", "subscribe": { "op": "subscribe", "id": "subscribe-fills", "channel": "fills", "account_id": "acct_example_main" }, "message": { "op": "data", "subscription_id": "sub_example_fills", "channel": "fills", "type": "update", "sequence": 2, "previous_sequence": 1, "timestamp": "2026-08-31T12:00:00.000Z", "data": [ { "fill_id": "fill_example_01", "order_id": "ord_example_01", "account_id": "acct_example_main", "instrument": "BTC-PERP", "venue": "binance", "venue_order_id": "bn_example_01", "settlement_asset": "USDT", "quantity": "0.060", "price": "77000.00", "fee": "0.462", "fee_asset": "USDT", "liquidity": "maker", "executed_at": "2026-08-31T12:00:00.250Z" } ] } }, { "name": "positions", "scope": "accounts:read", "initial": "Snapshot of open positions, then complete changed position records.", "recovery": "Replace local open positions from a fresh subscription snapshot.", "subscribe": { "op": "subscribe", "id": "subscribe-positions", "channel": "positions", "account_id": "acct_example_main" }, "message": { "op": "data", "subscription_id": "sub_example_positions", "channel": "positions", "type": "snapshot", "sequence": 1, "previous_sequence": 0, "timestamp": "2026-08-31T12:00:00.000Z", "data": [ { "position_id": "pos_example_01", "account_id": "acct_example_main", "instrument": "BTC-PERP", "venue": "binance", "settlement_asset": "USDT", "side": "long", "quantity": "0.060", "entry_price": "77000.00", "mark_price": "77100.00", "unrealized_pnl": "6.00", "liquidation_price": "64000.00", "leverage": "5", "margin_mode": "isolated", "updated_at": "2026-08-31T12:00:00.000Z" } ] } }, { "name": "balances", "scope": "accounts:read", "initial": "Snapshot, then complete records for changed assets.", "recovery": "Replace local balances from a fresh snapshot and reconcile any pending transfers.", "subscribe": { "op": "subscribe", "id": "subscribe-balances", "channel": "balances", "account_id": "acct_example_main" }, "message": { "op": "data", "subscription_id": "sub_example_balances", "channel": "balances", "type": "snapshot", "sequence": 1, "previous_sequence": 0, "timestamp": "2026-08-31T12:00:00.000Z", "data": [ { "account_id": "acct_example_main", "asset": "USDT", "total": "10000.00", "available": "7500.00", "committed": "2500.00", "updated_at": "2026-08-31T12:00:00.000Z" } ] } }, { "name": "risk", "scope": "accounts:read", "initial": "Snapshot, then complete changed risk records.", "recovery": "Refresh risk before resuming order submission; resubscribe for subsequent updates.", "subscribe": { "op": "subscribe", "id": "subscribe-risk", "channel": "risk", "account_id": "acct_example_main" }, "message": { "op": "data", "subscription_id": "sub_example_risk", "channel": "risk", "type": "snapshot", "sequence": 1, "previous_sequence": 0, "timestamp": "2026-08-31T12:00:00.000Z", "data": [ { "account_id": "acct_example_main", "venue": "binance", "settlement_asset": "USDT", "equity": "2506.00", "initial_margin": "925.20", "maintenance_margin": "23.13", "available_margin": "1580.80", "margin_ratio": "0.009230", "state": "normal", "updated_at": "2026-08-31T12:00:00.000Z" } ] } }, { "name": "collateral", "scope": "custody:read", "initial": "Snapshot of pending, active, and releasing allocations, then all changed allocation records.", "recovery": "Refresh allocations and reconcile any request awaiting exchange acknowledgement.", "subscribe": { "op": "subscribe", "id": "subscribe-collateral", "channel": "collateral", "account_id": "acct_example_main" }, "message": { "op": "data", "subscription_id": "sub_example_collateral", "channel": "collateral", "type": "snapshot", "sequence": 1, "previous_sequence": 0, "timestamp": "2026-08-31T12:00:00.000Z", "data": [ { "allocation_id": "alloc_example_01", "account_id": "acct_example_main", "client_allocation_id": "collateral-0001", "custody_account_id": "cust_example_ceffu", "custodian": "ceffu", "venue": "binance", "asset": "USDT", "amount": "2500.00", "status": "active", "updated_at": "2026-08-31T12:00:00.000Z" } ] } }, { "name": "settlements", "scope": "custody:read", "initial": "Live updates after the subscription acknowledgement.", "recovery": "Page settlement history with an overlapping cycle window; retain the latest updated_at for each settlement_id.", "subscribe": { "op": "subscribe", "id": "subscribe-settlements", "channel": "settlements", "account_id": "acct_example_main" }, "message": { "op": "data", "subscription_id": "sub_example_settlements", "channel": "settlements", "type": "update", "sequence": 2, "previous_sequence": 1, "timestamp": "2026-08-31T12:00:00.000Z", "data": [ { "settlement_id": "settle_example_01", "account_id": "acct_example_main", "custodian": "copper", "venue": "okx", "asset": "USDT", "amount": "125.50", "status": "completed", "cycle_start": "2026-08-31T08:00:00.000Z", "cycle_end": "2026-08-31T12:00:00.000Z", "updated_at": "2026-08-31T12:00:00.000Z" } ] } } ] }