> For the complete documentation index, see [llms.txt](https://docs.nexus.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexus.xyz/api-reference/guides/schemas.md). # Schema Reference Shared response and request types for the Nexus Exchange API (OpenAPI **v0.9.27**). 58 of the contract's 87 `components.schemas` entries are documented here, once each; the generated endpoint pages link into these anchors instead of repeating field tables. For a schema not listed below, read it from `/openapi.json` — the contract is authoritative and complete, this page is not yet. The machine-readable contract is served at `/openapi.json` and is the authoritative source. ## Conventions * **Decimals are strings.** Every monetary and quantity field is an arbitrary-precision decimal serialized as a JSON string (see [Decimal](#decimal)). Parse it with a decimal type, never a float — a float round-trip loses precision on prices and sizes. * **Timestamps are Unix milliseconds.** Integer epoch milliseconds (see [TimestampMs](#timestampms)). Fields named `*_ms`, `*_at_ms`, or `timestamp` follow this convention. A few CCXT-shaped schemas also carry a `datetime` field, which is an ISO 8601 date-time string alongside the numeric timestamp. `ThroughputSample.timestamp` is the one exception: it is Unix **seconds**, as its field description states. * **Nullability** is expressed two ways in the contract and both mean the same thing on the wire: a JSON Schema type union (`"type": ["string", "null"]`) for inline types, and `oneOf` / `anyOf` with a `null` branch where the non-null branch is a `$ref` (most often [Decimal](#decimal) or [TimestampMs](#timestampms)). A single-element `allOf` around a `$ref` is not nullability — it is the OpenAPI idiom for attaching a field-level description to a referenced type. * **Null carries a reason, not a fabricated number.** Where a derived field can be unavailable, [Position](#position) pairs it with a companion `_error` string holding a machine-readable reason (e.g. `mark_price_unavailable`). When the value is populated, the companion is `null`. * **Two naming families.** Native Nexus schemas use `snake_case` keys and decimal strings. The CCXT-compatible schemas ([Ticker](#ticker), [OrderBook](#orderbook), [Trade](#trade)) use CCXT's `camelCase` keys and JSON numbers instead, for drop-in compatibility with existing CCXT tooling. * **Requiredness.** The `Required` column reflects the schema's `required` array. Where a schema declares no `required` array at all the column shows `—`: the contract does not commit to per-field presence for that type, so treat every field as optional and check for absence. ## Index * [AccountFees](#accountfees) * [AccountFunding](#accountfunding) * [AccountPortfolioSummary](#accountportfoliosummary) * [AccountState](#accountstate) * [AccountSummary](#accountsummary) * [AdlClosureRecord](#adlclosurerecord) * [AdlEventRecord](#adleventrecord) * [AgentInfo](#agentinfo) * [AgentRegistrationRequest](#agentregistrationrequest) * [AmendOrderRequest](#amendorderrequest) * [BridgeAsset](#bridgeasset) * [BridgeAssetsResponse](#bridgeassetsresponse) * [BridgeChainAssets](#bridgechainassets) * [BridgeDeposit](#bridgedeposit) * [BridgeDepositAddress](#bridgedepositaddress) * [BridgeError](#bridgeerror) * [CancelOnDisconnectStatus](#cancelondisconnectstatus) * [ClosedPosition](#closedposition) * [CreateBridgeDepositAddressRequest](#createbridgedepositaddressrequest) * [CreditRequest](#creditrequest) * [CreditResponse](#creditresponse) * [Decimal](#decimal) * [DepositRequest](#depositrequest) * [DepositResponse](#depositresponse) * [EquityPoint](#equitypoint) * [FaucetResponse](#faucetresponse) * [FeeDiscount](#feediscount) * [Fill](#fill) * [FundingSample](#fundingsample) * [FundsEntry](#fundsentry) * [LoginRequest](#loginrequest) * [LoginResponse](#loginresponse) * [Market](#market) * [MarketRiskParams](#marketriskparams) * [MarketStatus](#marketstatus) * [MarketSummary](#marketsummary) * [Order](#order) * [OrderBook](#orderbook) * [OrderHistoryEntry](#orderhistoryentry) * [OrderRequest](#orderrequest) * [OrderResponse](#orderresponse) * [OrderResult](#orderresult) * [OrderResultErr](#orderresulterr) * [OrderResultOk](#orderresultok) * [PortfolioHistory](#portfoliohistory) * [PortfolioPoint](#portfoliopoint) * [PortfolioWindow](#portfoliowindow) * [Position](#position) * [PreviewResponse](#previewresponse) * [RateLimitStatus](#ratelimitstatus) * [ServiceHealth](#servicehealth) * [SetCancelOnDisconnectRequest](#setcancelondisconnectrequest) * [StatsSnapshot](#statssnapshot) * [ThroughputSample](#throughputsample) * [Ticker](#ticker) * [TimestampMs](#timestampms) * [Trade](#trade) * [Withdrawal](#withdrawal) ## AccountFees The authenticated account's effective fee schedule, mirroring Hyperliquid `userFees`. Reports what the venue charges today: there are no per-account fee tiers or discounts yet (fee model still a draft), so `tier` is `base` and `discounts` is empty. The rate is the forward-looking schedule rate scoped by `schedule`, not a realized per-fill average. | Field | Type | Required | Description | | ---------------------- | -------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `maker_fee_bps` | `integer` | Yes | Effective maker fee in basis points. Negative means the maker is *paid* a rebate — e.g. -2 is a 0.02% rebate. | | `taker_fee_bps` | `integer` | Yes | Effective taker fee in basis points — e.g. 5 is a 0.05% fee. | | `tier` | `string` | Yes | Fee tier for the account. Currently always `base`: there are no per-account fee tiers yet (distinct from rate-limit tiers). New values may appear when the fee model lands, so treat this as an open string. | | `schedule` | `string` | Yes | Scope of the reported rate. Currently always `standard`. The venue charges a per-market schedule (standard crypto, mid-cap crypto, FX, commodities/indices all differ, and the split varies by deploy config), but this endpoint takes no market parameter, so it reports the standard crypto-group schedule and marks it here. Treat the rate as scoped by this value, not a venue-wide guarantee; per-market effective rates are a planned follow-up. Treat as an open string — new scopes may appear. | | `volume_30d` | [Decimal](#decimal) | Yes | Rolling 30-day traded notional for the account, as a decimal string. Best-effort — see `volume_30d_estimated`. | | `volume_30d_estimated` | `boolean` | Yes | `true` when `volume_30d` may undercount: the source fill buffer was at capacity, so some older in-window fills may have been evicted. `false` when the full 30-day window is covered. | | `discounts` | `array` of [FeeDiscount](#feediscount) | Yes | Active fee discounts applied to the account. Currently always empty — no discount program exists yet. | ## AccountFunding A funding payment for the account. | Field | Type | Required | Description | | --------------- | --------------------------- | -------- | --------------------------- | | `market_id` | `string` | — | — | | `amount` | [Decimal](#decimal) | — | Signed funding amount. | | `direction` | `string` | — | One of: `paid`, `received`. | | `funding_rate` | [Decimal](#decimal) | — | — | | `position_size` | [Decimal](#decimal) | — | — | | `timestamp` | [TimestampMs](#timestampms) | — | — | ## AccountPortfolioSummary Portfolio summary for the authenticated account (aggregate equity, PnL, volume, open counts). | Field | Type | Required | Description | | ------------------------ | ------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `collateral` | [Decimal](#decimal) | — | — | | `total_equity` | [Decimal](#decimal) | — | — | | `total_unrealized_pnl` | [Decimal](#decimal) | — | — | | `total_realized_pnl_24h` | [Decimal](#decimal) | — | — | | `total_volume_24h` | [Decimal](#decimal) | — | — | | `open_positions_count` | `integer` | — | — | | `open_orders_count` | `integer` | — | — | | `margin_used` | [Decimal](#decimal) | — | — | | `available_margin` | [Decimal](#decimal) | — | — | | `withdrawable` | [Decimal](#decimal) | — | Wallet-withdrawable balance: engine-authoritative free margin floored at zero (`max(0, available_margin)`). Free margin already nets each position's initial margin and pre-trade order reservations out of equity, so this is exactly what can leave the account. A negative free margin (an underwater account) is clamped to `"0"` and never surfaced negative. Derived from the authoritative margin view — the endpoint fails closed with `502` rather than reporting a local estimate when that view is unavailable. Example `8500.00`. | | `early_access_allowed` | `boolean` | — | Present only when the early-access gate is active. | ## AccountState Consolidated single-call account snapshot — the portfolio summary aggregates plus all open positions — matching Hyperliquid `clearinghouseState` ergonomics. Both parts are built from one coherent read, so `summary.open_positions_count` always equals the length of `positions`, and the embedded `summary` is identical to the standalone `/account/summary` response. | Field | Type | Required | Description | | ----------- | --------------------------------------------------- | -------- | ----------------------------------- | | `summary` | [AccountPortfolioSummary](#accountportfoliosummary) | Yes | — | | `positions` | `array` of [Position](#position) | Yes | All open positions for the account. | ## AccountSummary | Field | Type | Required | Description | | ------------------ | -------------------------------- | -------- | ----------- | | `balance` | [Decimal](#decimal) | — | — | | `collateral` | [Decimal](#decimal) | — | — | | `equity` | [Decimal](#decimal) | — | — | | `available_margin` | [Decimal](#decimal) | — | — | | `positions` | `array` of [Position](#position) | — | — | ## AdlClosureRecord One counterparty's forced closure within an ADL settlement. | Field | Type | Required | Description | | ------------------- | ------------------- | -------- | ----------------------------------------------------------------- | | `account_id` | `string` | — | 0x-prefixed address of the counterparty whose position was closed | | `position_closed` | [Decimal](#decimal) | — | Decimal quantity closed | | `settlement_amount` | [Decimal](#decimal) | — | Decimal amount charged to the counterparty | ## AdlEventRecord Single ADL settlement (insurance fund depleted → counterparty closures). v0.21. | Field | Type | Required | Description | | --------------------------- | ------------------------------------------------ | -------- | ---------------------------- | | `market_id` | `string` | — | — | | `target_account` | `string` | — | 0x-prefixed bankrupt account | | `bankruptcy_price` | [Decimal](#decimal) | — | — | | `bad_debt_absorbed_by_fund` | [Decimal](#decimal) | — | — | | `counterparty_closures` | `array` of [AdlClosureRecord](#adlclosurerecord) | — | — | | `sequence` | `integer` | — | Engine event sequence number | | `timestamp` | [TimestampMs](#timestampms) | — | Unix ms | ## AgentInfo | Field | Type | Required | Description | | -------------- | --------------------------- | -------- | --------------------------- | | `address` | `string` | — | Agent address (0x-prefixed) | | `expiresAt` | [TimestampMs](#timestampms) | — | Expiry Unix ms | | `registeredAt` | [TimestampMs](#timestampms) | — | Registration time Unix ms | | `label` | `string` \| `null` | — | Optional label | ## AgentRegistrationRequest | Field | Type | Required | Description | | ------------ | --------- | -------- | ------------------------------------------------------------------------------------------------------- | | `wallet` | `string` | Yes | Owner wallet address (0x-prefixed, 20 bytes) | | `agent` | `string` | Yes | Agent Ethereum address (0x-prefixed, 20 bytes) derived from the agent keypair | | `expires_at` | `integer` | No | Expiry as Unix ms. Optional — defaults to now+30d. Must be in \[now+1d, now+90d]. | | `nonce` | `integer` | Yes | Monotonic nonce. Use the current Unix timestamp in ms as a safe starting value. | | `signature` | `string` | Yes | EIP-712 signature over RegisterAgent{agent, expiresAt, nonce} from the wallet private key (0x-prefixed) | | `label` | `string` | No | Optional human-readable label for the agent (e.g. 'my-bot') | ## AmendOrderRequest Atomic cancel-replace amend of a resting order. At least one of `price` (new limit price) or `size` (new quantity) must be present; an empty body is rejected with InvalidAmend. | Field | Type | Required | Description | | ------- | ------------------- | -------- | ----------- | | `price` | [Decimal](#decimal) | — | — | | `size` | [Decimal](#decimal) | — | — | ## BridgeAsset A bridgeable asset on a specific chain. | Field | Type | Required | Description | | ------------------ | ------------------- | -------- | -------------------------------------------------------------------------------------------------------------- | | `symbol` | `string` | Yes | Asset symbol. Phase A supports USDC and USDX only (USDT is out of scope for this cut). One of: `USDC`, `USDX`. | | `decimals` | `integer` | Yes | On-chain token decimals for this asset on this chain. | | `min_amount` | [Decimal](#decimal) | Yes | Minimum amount accepted for a single deposit. | | `confirmations` | `integer` | Yes | Block confirmations required before a deposit is credited. | | `fee` | [Decimal](#decimal) | No | Flat fee charged in units of the asset (may be "0"). | | `contract_address` | `string` \| `null` | No | 0x token contract address on the chain; null for a chain-native representation. | ## BridgeAssetsResponse Supported bridge chains and their deposit/withdraw assets. | Field | Type | Required | Description | | -------- | -------------------------------------------------- | -------- | ----------- | | `chains` | `array` of [BridgeChainAssets](#bridgechainassets) | Yes | — | ## BridgeChainAssets Bridgeable assets for one chain. | Field | Type | Required | Description | | ----------------- | -------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | | `chain` | `string` | Yes | Chain identifier, e.g. `ethereum` or `base`. | | `chain_id` | `integer` \| `null` | No | EVM chain ID, when applicable. | | `deposit_assets` | `array` of [BridgeAsset](#bridgeasset) | Yes | Assets that can be deposited from this chain (USDC, USDX). | | `withdraw_assets` | `array` of [BridgeAsset](#bridgeasset) | Yes | Assets that can be withdrawn to this chain (USDX). Withdrawal endpoints are a later phase; this lists the eventual capability. | ## BridgeDeposit A cross-chain deposit tracked by the watcher (read model). | Field | Type | Required | Description | | ------------------------ | ------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | Yes | Opaque, stable deposit identifier. | | `account_id` | `string` | Yes | 0x-prefixed Nexus account being credited. | | `chain` | `string` | Yes | Source chain. | | `asset` | `string` | Yes | Deposited asset. One of: `USDC`, `USDX`. | | `amount` | [Decimal](#decimal) | Yes | Deposit amount in units of `asset`. | | `address` | `string` | Yes | Deposit address the funds arrived at. | | `status` | `string` | Yes | Lifecycle: `detected` → `confirming` → `credited` \| `failed`. One of: `detected`, `confirming`, `credited`, `failed`. | | `confirmations` | `integer` \| `null` | No | Confirmations observed so far; null before the tx is seen on chain. | | `required_confirmations` | `integer` \| `null` | No | Confirmations required before crediting. | | `tx_hash` | `string` \| `null` | No | Source-chain transaction hash; null until detected. | | `created_at` | [TimestampMs](#timestampms) | Yes | — | | `updated_at` | [TimestampMs](#timestampms) | No | — | | `credited_at` | [TimestampMs](#timestampms) \| `null` | No | Unix ms when the deposit was credited; null until `status` is `credited`. | ## BridgeDepositAddress A per-account deposit address on a specific chain. | Field | Type | Required | Description | | ------------ | --------------------------- | -------- | ------------------------------------------------------------------------------------------------------------- | | `address` | `string` | Yes | Deposit address on `chain` for the authenticated account. Sending a supported asset here credits the account. | | `chain` | `string` | Yes | Chain this address belongs to. | | `accepts` | `array` of `string` | Yes | Assets creditable via this address. One of: `USDC`, `USDX`. | | `account_id` | `string` | Yes | 0x-prefixed Nexus account the address credits. | | `created_at` | [TimestampMs](#timestampms) | Yes | — | ## BridgeError Error envelope returned by all non-2xx /v1/bridge responses. | Field | Type | Required | Description | | ------- | -------- | -------- | ----------- | | `error` | `object` | Yes | — | `error` object: | Field | Type | Required | Description | | --------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------- | | `code` | `string` | Yes | Machine-readable, stable error code (snake\_case), e.g. `unsupported_chain`, `amount_below_minimum`, `deposit_not_found`. | | `message` | `string` | Yes | Human-readable description; not intended for programmatic matching. | | `details` | `object` | No | Optional structured context for the error. | ## CancelOnDisconnectStatus Cancel-on-disconnect status for the authenticated account. | Field | Type | Required | Description | | ------------ | ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `enabled` | `boolean` | Yes | The account's own COD opt-in setting. | | `active` | `boolean` | Yes | Whether COD will actually fire for this account: the account opt-in AND the exchange-side feature switch. When `enabled` is true but `active` is false, the exchange has the feature switched off and no cancel fires on disconnect. | | `grace_secs` | `integer` \| `null` | No | Seconds the exchange waits after the last `/ws` disconnect before cancelling; a reconnect within the window disarms the cancel. Null when the feature is unavailable on this deployment. | ## ClosedPosition A closed position record. | Field | Type | Required | Description | | -------------- | --------------------------- | -------- | -------------------------------------------------------------------- | | `market_id` | `string` | — | — | | `side` | `string` | — | The side the position was before it closed. One of: `Long`, `Short`. | | `size` | [Decimal](#decimal) | — | Absolute size at close. | | `entry_price` | [Decimal](#decimal) | — | — | | `exit_price` | [Decimal](#decimal) | — | — | | `realized_pnl` | [Decimal](#decimal) | — | — | | `closed_at_ms` | [TimestampMs](#timestampms) | — | — | ## CreateBridgeDepositAddressRequest | Field | Type | Required | Description | | ------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `chain` | `string` | Yes | Chain to get-or-create a deposit address on. The operation is idempotent per `(account, chain)`: repeated calls return the same address. | ## CreditRequest | Field | Type | Required | Description | | -------- | ------------------- | -------- | -------------------------------------------------------------------------------------------- | | `amount` | [Decimal](#decimal) | — | Synthetic USDX to credit (decimal string). Omit to claim the full remaining daily allowance. | ## CreditResponse | Field | Type | Required | Description | | ---------------- | ------------------- | -------- | ------------------------------------------------------------------ | | `amount` | [Decimal](#decimal) | Yes | USDX credited by this request (decimal string). | | `credited_today` | [Decimal](#decimal) | Yes | Total USDX credited to this API key so far today (decimal string). | | `daily_limit` | [Decimal](#decimal) | Yes | Per-API-key daily credit allowance in USDX (decimal string). | ## Decimal Arbitrary-precision decimal serialized as a string (lossless). Parse with a decimal type, never a float. **Type:** `string` ## DepositRequest | Field | Type | Required | Description | | -------- | ------------------- | -------- | ----------------------------------------------- | | `amount` | [Decimal](#decimal) | Yes | Deposit amount (positive decimal string). | | `asset` | `string` | No | Asset symbol; defaults to USDX. Default `USDX`. | ## DepositResponse Engine deposit acknowledgement (forwarded). Includes the updated authoritative balance. | Field | Type | Required | Description | | --------- | ------------------- | -------- | ----------------------------------- | | `balance` | [Decimal](#decimal) | — | Authoritative post-deposit balance. | The contract permits additional properties beyond those listed. ## EquityPoint One equity sample (balance + unrealized PnL) for the account, 5s cadence. | Field | Type | Required | Description | | -------------- | --------------------------- | -------- | ------------------------------ | | `timestamp_ms` | [TimestampMs](#timestampms) | — | — | | `equity` | `number` | — | Account equity at sample time. | ## FaucetResponse Testnet faucet credit result. | Field | Type | Required | Description | | ----------------- | --------------------------- | -------- | ---------------------------------------------- | | `amount` | [Decimal](#decimal) | — | Amount credited. | | `available_at_ms` | [TimestampMs](#timestampms) | — | Earliest time the faucet may be claimed again. | ## FeeDiscount An active fee discount applied to the account. The concrete shape is provisional and finalizes with the fee model (tiers and discounts are still a draft); `discounts` is currently always empty, so no properties are guaranteed yet. Additional properties may be added additively once the model lands. **Type:** `object` with no declared properties. The contract permits additional properties. ## Fill A single trade execution for the authenticated account | Field | Type | Required | Description | | ---------------- | --------------------------- | -------- | ------------------------------------ | | `id` | `string` | — | Fill ID. Format `uuid`. | | `order_id` | `string` | — | Parent order ID | | `market_id` | `string` | — | Market (e.g. BTC-USDX-PERP) | | `side` | `string` | — | One of: `buy`, `sell`. | | `price` | [Decimal](#decimal) | — | Executed price (decimal string) | | `size` | [Decimal](#decimal) | — | Executed quantity (decimal string) | | `fee` | [Decimal](#decimal) | — | Fee charged in USDX (decimal string) | | `taker_or_maker` | `string` | — | One of: `taker`, `maker`. | | `timestamp` | [TimestampMs](#timestampms) | — | Unix ms | | `is_liquidation` | `boolean` | — | — | ## FundingSample | Field | Type | Required | Description | | --------------- | --------------------------- | -------- | ----------- | | `timestamp` | [TimestampMs](#timestampms) | — | — | | `funding_rate` | [Decimal](#decimal) | — | — | | `premium_index` | [Decimal](#decimal) | — | — | | `mark_price` | [Decimal](#decimal) | — | — | | `oracle_price` | [Decimal](#decimal) | — | — | ## FundsEntry A deposit or withdrawal ledger entry. | Field | Type | Required | Description | | ----------- | --------------------------- | -------- | ------------------------------------------ | | `id` | `integer` | — | — | | `kind` | `string` | — | One of: `deposit`, `withdrawal`, `faucet`. | | `account` | `string` | — | 0x-prefixed account address. | | `amount` | [Decimal](#decimal) | — | — | | `asset` | `string` | — | — | | `timestamp` | [TimestampMs](#timestampms) | — | — | | `status` | `string` | — | One of: `pending`, `confirmed`, `failed`. | | `tx_hash` | `string` \| `null` | — | — | ## LoginRequest | Field | Type | Required | Description | | ----------- | -------- | -------- | -------------------------------------------------- | | `message` | `string` | Yes | Must be exactly: "Sign in to Nexus Exchange" | | `signature` | `string` | Yes | EIP-191 personal\_sign hex (0x-prefixed, 65 bytes) | ## LoginResponse | Field | Type | Required | Description | | --------- | -------- | -------- | --------------------------------------------------------------------- | | `token` | `string` | — | Session token (64-char hex). Use as Bearer token for /keys endpoints. | | `address` | `string` | — | Recovered Ethereum address (0x-prefixed) | ## Market | Field | Type | Required | Description | | ------------------------- | ------------------- | -------- | ----------- | | `market_id` | `string` | — | — | | `base_asset` | `string` | — | — | | `quote_asset` | `string` | — | — | | `tick_size` | [Decimal](#decimal) | — | — | | `lot_size` | [Decimal](#decimal) | — | — | | `min_order_size` | [Decimal](#decimal) | — | — | | `max_order_size` | [Decimal](#decimal) | — | — | | `initial_margin_rate` | [Decimal](#decimal) | — | — | | `maintenance_margin_rate` | [Decimal](#decimal) | — | — | | `max_leverage` | `integer` | — | — | ## MarketRiskParams Per-market risk parameters: margin rates and maximum leverage. | Field | Type | Required | Description | | ------------------------- | ------------------- | -------- | ---------------------------------------------------------------------- | | `market_id` | `string` | — | — | | `max_leverage` | `integer` | — | Maximum leverage allowed for this market | | `initial_margin_rate` | [Decimal](#decimal) | — | Initial margin requirement as a decimal ratio (e.g., 0.05 = 5%) | | `maintenance_margin_rate` | [Decimal](#decimal) | — | Maintenance margin requirement as a decimal ratio (e.g., 0.025 = 2.5%) | ## MarketStatus Per-market halt status (v0.21). | Field | Type | Required | Description | | ----------------- | ------------------- | -------- | --------------------------- | | `market_id` | `string` | — | — | | `status` | `string` | — | One of: `active`, `halted`. | | `halt_reason` | `string` \| `null` | — | — | | `halted_at` | `integer` \| `null` | — | — | | `adl_event_count` | `integer` | — | — | ## MarketSummary | Field | Type | Required | Description | | ------------------ | ------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- | | `market_id` | `string` | — | — | | `last_trade_price` | `number` \| `null` | — | Last trade price ("what the market is trading at"). NOT the mark; the engine-derived mark is exposed separately. | | `volume_24h` | `number` | — | — | | `trade_count` | `integer` | — | — | | `status` | `string` | — | v0.21: halted when ADL pool exhausted. One of: `active`, `halted`. | | `halt_reason` | `string` \| `null` | — | — | | `halted_at` | `integer` \| `null` | — | Unix ms timestamp when market was halted | | `adl_event_count` | `integer` | — | Cumulative ADL settlement events for this market | ## Order | Field | Type | Required | Description | | ------------------ | --------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | — | Format `uuid`. | | `market_id` | `string` | — | — | | `account_id` | `string` | — | — | | `side` | `string` | — | One of: `Buy`, `Sell`. | | `order_type` | `string` | — | — | | `limit_offset_bps` | `integer` \| `null` | — | Fire-time limit offset in basis points, echoed for `TrailingLimit` orders (see the `OrderRequest.limit_offset_bps` placement field); null for other order types. | | `price` | [Decimal](#decimal) | — | — | | `quantity` | [Decimal](#decimal) | — | — | | `filled_qty` | [Decimal](#decimal) | — | — | | `status` | `string` | — | One of: `Open`, `PartiallyFilled`, `Filled`, `Cancelled`, `Expired`, `Rejected`. | | `time_in_force` | `string` | — | — | | `created_at` | [TimestampMs](#timestampms) | — | — | | `updated_at` | [TimestampMs](#timestampms) | — | — | ## OrderBook CCXT-compatible order book. Bids/asks are \[price, amount] arrays. | Field | Type | Required | Description | | ----------- | ----------------------------- | -------- | ------------------- | | `symbol` | `string` | — | — | | `bids` | `array` of `[number, number]` | — | — | | `asks` | `array` of `[number, number]` | — | — | | `timestamp` | [TimestampMs](#timestampms) | — | — | | `datetime` | `string` | — | Format `date-time`. | | `nonce` | `integer` | — | — | ## OrderHistoryEntry A terminal-status order (filled / cancelled / rejected / expired). | Field | Type | Required | Description | | --------------------- | ----------------------------- | -------- | ------------------------------------------------------------------------------------ | | `id` | `string` | — | Format `uuid`. | | `market_id` | `string` | — | — | | `side` | `string` | — | One of: `buy`, `sell`. | | `order_type` | `string` | — | limit \| market \| stop\_\* \| take\_profit\_\* \| trailing\_stop \| trailing\_limit | | `price` | [Decimal](#decimal) \| `null` | — | Limit price; null for market orders. | | `size` | [Decimal](#decimal) | — | Original quantity. | | `filled_qty` | [Decimal](#decimal) | — | — | | `status` | `string` | — | One of: `Filled`, `Cancelled`, `Rejected`, `Expired`. | | `cancellation_reason` | `string` \| `null` | — | — | | `created_at_ms` | [TimestampMs](#timestampms) | — | — | | `completed_at_ms` | [TimestampMs](#timestampms) | — | — | ## OrderRequest Order placement request. Supports plain `Limit` / `Market` orders and six conditional order types (`StopLimit`, `StopMarket`, `TakeProfitLimit`, `TakeProfitMarket`, `TrailingStop`, `TrailingLimit`). Field requirements depend on `order_type`: * **Limit-family** (`Limit`, `StopLimit`, `TakeProfitLimit`) require a limit `price`. * **Triggerable, non-trailing** orders (`StopLimit`, `StopMarket`, `TakeProfitLimit`, `TakeProfitMarket`) require a `trigger_price` (the legacy `stop_price` field is accepted as a fallback when `trigger_price` is absent). * **`TrailingStop`** is market-only — it fires as a market order — and requires `trailing_offset_bps`. It does not take a limit `price` or a `trigger_price` (the trigger anchor is derived from the mark price and the offset). * **`TrailingLimit`** trails like `TrailingStop` but fires a limit order instead of a market order. It requires both `trailing_offset_bps` (the trailing trigger) and `limit_offset_bps` (the fire-time limit offset). It does not take `price`, `trigger_price`, or `stop_price`; the limit price is computed at fire time from the mark that crossed the offset. | Field | Type | Required | Description | | --------------------- | ----------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `market_id` | `string` | Yes | — | | `side` | `string` | Yes | One of: `Buy`, `Sell`. | | `order_type` | `string` | Yes | Order type. `Limit` and `Market` are unconditional. The remaining six are conditional: `StopLimit` / `StopMarket` fire when the mark price crosses `trigger_price` in the adverse direction; `TakeProfitLimit` / `TakeProfitMarket` fire on the favorable direction; `TrailingStop` fires as a market order when the mark retraces from its best-seen extreme by `trailing_offset_bps`; `TrailingLimit` fires the same way but rests a limit order priced off the fire price by `limit_offset_bps`. See the schema description for per-type field requirements. One of: `Limit`, `Market`, `StopLimit`, `StopMarket`, `TakeProfitLimit`, `TakeProfitMarket`, `TrailingStop`, `TrailingLimit`. | | `price` | [Decimal](#decimal) | No | Limit price. Required for limit-family orders (`Limit`, `StopLimit`, `TakeProfitLimit`); omit for market-family and trailing orders. | | `quantity` | [Decimal](#decimal) | Yes | — | | `time_in_force` | `string` | Yes | Time-in-force policy. `PostOnly` rejects the order if it would take liquidity (cross the book) on entry, guaranteeing it rests as a maker. One of: `GTC`, `IOC`, `FOK`, `PostOnly`. | | `reduce_only` | `boolean` | No | — | | `stop_price` | [Decimal](#decimal) \| `null` | No | **Deprecated** — use `trigger_price` instead. Legacy trigger threshold for the stop / take-profit family. Accepted as a fallback only when `trigger_price` is absent; when both are supplied, `trigger_price` wins. Ignored for `Limit`, `Market`, `TrailingStop`, and `TrailingLimit` orders. **Deprecated.** | | `trigger_price` | [Decimal](#decimal) \| `null` | No | Canonical trigger threshold for triggerable, non-trailing orders (`StopLimit`, `StopMarket`, `TakeProfitLimit`, `TakeProfitMarket`), which require it (the legacy `stop_price` field is accepted as a fallback when this is omitted). Not used by `Limit`, `Market`, `TrailingStop`, or `TrailingLimit` orders. | | `trailing_offset_bps` | `integer` \| `null` | No | Trailing offset in basis points (1 bp = 0.01%). Required for `TrailingStop` and `TrailingLimit` orders; ignored for all other order types. The trailing trigger fires once the mark price retraces from its best-seen extreme by this many basis points: `TrailingStop` fires a market order, `TrailingLimit` fires a limit order priced by `limit_offset_bps`. A value of `0` is accepted and fires the trigger at the first mark-price evaluation after placement (no retracement required). Minimum `0`. | | `limit_offset_bps` | `integer` \| `null` | No | Offset in basis points for the fired limit price (`TrailingLimit` only; required together with `trailing_offset_bps`). When the trailing trigger fires at `fire_price`, the injected limit order rests at `fire_price` \* (1 + offset) for buys / \* (1 - offset) for sells, tick-rounded toward the tighter bound. A value of 0 rests the limit exactly at `fire_price`. Ignored for other order types. Minimum `0`. Maximum `9999`. | ## OrderResponse | Field | Type | Required | Description | | ------- | ------------------------ | -------- | ----------- | | `order` | [Order](#order) | — | — | | `fills` | `array` of [Fill](#fill) | — | — | ## OrderResult One entry in the array returned by POST /orders/batch. The batch is sequential and non-atomic, so each entry independently reports either a placed order or a per-order rejection, in request order. Internally tagged by `outcome`: `ok` carries the same `{ order, fills }` shape as POST /orders, `err` carries the same `{ error, message }` shape as the global error envelope. **One of:** [OrderResultOk](#orderresultok) or [OrderResultErr](#orderresulterr) Discriminated by the `outcome` property: `ok` → [OrderResultOk](#orderresultok), `err` → [OrderResultErr](#orderresulterr). ## OrderResultErr A rejected order in a batch result (outcome `err`). Mirrors the global error envelope. | Field | Type | Required | Description | | --------- | -------- | -------- | ----------------------------- | | `outcome` | `string` | Yes | One of: `err`. | | `error` | `string` | Yes | Machine-readable error code. | | `message` | `string` | Yes | Human-readable error message. | ## OrderResultOk A placed order in a batch result (outcome `ok`). | Field | Type | Required | Description | | --------- | ------------------------ | -------- | ------------- | | `outcome` | `string` | Yes | One of: `ok`. | | `order` | [Order](#order) | Yes | — | | `fills` | `array` of [Fill](#fill) | No | — | ## PortfolioHistory Portfolio time-series for the authenticated account over the requested window: equity, cumulative PnL, and cumulative volume, downsampled at a fixed per-window cadence and returned oldest first. | Field | Type | Required | Description | | ------------ | -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `window` | [PortfolioWindow](#portfoliowindow) | Yes | The window that was served — echoes the `window` query parameter, or its `day` default. | | `cadence_ms` | `integer` | Yes | Downsample interval between adjacent points, in milliseconds (e.g. 300000 for `day`, 86400000 for `all`). | | `points` | `array` of [PortfolioPoint](#portfoliopoint) | Yes | Samples for the window, oldest first. Length is bounded by the window's capacity (day 288, week 168, month 120, all 366) and by the `limit` parameter. | ## PortfolioPoint One downsampled portfolio sample. Monetary fields are lossless decimal strings — parse with a decimal type, never a float. | Field | Type | Required | Description | | -------------- | --------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `timestamp_ms` | [TimestampMs](#timestampms) | Yes | — | | `equity` | [Decimal](#decimal) | Yes | Account equity at sample time (collateral balance + Σ unrealized PnL). Derived from the same underlying value as `EquityPoint.equity`; note `EquityPoint` serializes equity as a JSON number, whereas this is a lossless decimal string, so compare by decimal value rather than by wire representation. | | `pnl` | [Decimal](#decimal) | Yes | Cumulative trading PnL up to this sample: Σ realized PnL on position close (including liquidation and ADL closes) + Σ funding (signed) + current unrealized PnL. Deposit-neutral — wallet deposits and withdrawals never move it — so the curve reflects trading performance only. | | `volume` | [Decimal](#decimal) | Yes | Cumulative traded notional (Σ price × size) up to this sample, across taker and maker fills; a self-trade is counted once. Monotonically non-decreasing. | ## PortfolioWindow Portfolio time-series window selector: `day`, `week`, `month`, or `all`. Shared by the `window` query parameter and the `window` echoed in the response. **Type:** `string` **Values:** * `day` * `week` * `month` * `all` ## Position An open position with per-position risk detail. Enriched risk fields are derived strictly from indexer-mirrored state (no engine round-trip, to stay on the low-latency read path): when an input is not mirrored, the field is `null` and its companion `_error` carries a machine-readable reason rather than a fabricated number. Monetary fields are lossless decimal strings; leverage fields are JSON numbers. | Field | Type | Required | Description | | ---------------------- | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `market_id` | `string` | — | — | | `side` | `string` | — | One of: `Long`, `Short`. | | `size` | [Decimal](#decimal) | — | — | | `entry_price` | [Decimal](#decimal) | — | — | | `unrealized_pnl` | [Decimal](#decimal) | — | — | | `realized_pnl` | [Decimal](#decimal) | — | — | | `liquidation_price` | [Decimal](#decimal) | — | — | | `leverage` | `number` \| `null` | — | Position leverage (the account's leverage multiplier for this position). Currently always `null`: deriving it needs the user's leverage setting or account equity/allocated margin, which the indexer does not mirror; when `null`, `leverage_error` carries the reason. Do not infer leverage from `margin_used` — that collapses to `1/initial_margin_rate`, a per-market constant, not the real leverage. | | `leverage_error` | `string` \| `null` | — | Machine-readable reason `leverage` is `null`, or `null` when `leverage` is populated. Currently always `margin_state_not_mirrored`. | | `notional_value` | [Decimal](#decimal) \| `null` | — | Position notional value (\|size\| × mark price), as a decimal string. `null` when the mark price is unavailable — see `notional_value_error`. | | `notional_value_error` | `string` \| `null` | — | Machine-readable reason `notional_value` is `null` (e.g. `mark_price_unavailable`), or `null` when populated. | | `roe` | [Decimal](#decimal) \| `null` | — | Return on equity: `unrealized_pnl / margin_used` (return on initial margin), as a decimal string. `null` when a required input is unavailable or margin is zero — see `roe_error`. | | `roe_error` | `string` \| `null` | — | Machine-readable reason `roe` is `null` (e.g. `mark_price_unavailable`, `margin_rate_unavailable`, `margin_used_zero`), or `null` when populated. | | `margin_used` | [Decimal](#decimal) \| `null` | — | Initial-margin requirement held against this position (`notional_value × initial_margin_rate`, under the engine's cross-margin model), as a decimal string. Isolated/custom margin allocations are not mirrored by the indexer. `null` when a required input is unavailable — see `margin_used_error`. | | `margin_used_error` | `string` \| `null` | — | Machine-readable reason `margin_used` is `null` (e.g. `mark_price_unavailable`, `margin_rate_unavailable`), or `null` when populated. | | `max_leverage` | `integer` \| `null` | — | Maximum leverage allowed for this market (from market risk params), as an integer matching `max_leverage` on `/markets/{market_id}/risk-params`. `null` when market params are unavailable — see `max_leverage_error`. | | `max_leverage_error` | `string` \| `null` | — | Machine-readable reason `max_leverage` is `null` (e.g. `market_params_unavailable`), or `null` when populated. | | `funding_paid` | [Decimal](#decimal) | — | Cumulative funding paid on this position, as a decimal string. Sign is **paid-positive**: a positive value means the position has paid funding, a negative value means it has received funding. Always present: `"0"` when no funding has accrued. Bounded by the funding history the indexer retains. | ## PreviewResponse Pre-trade preview: projects the margin/equity/fee impact of an order without submitting it. | Field | Type | Required | Description | | ---------------------------------------- | ----------------------------- | -------- | ----------- | | `accepted` | `boolean` | — | — | | `reject_reason` | `string` \| `null` | — | — | | `required_initial_margin` | [Decimal](#decimal) | — | — | | `projected_post_trade_equity` | [Decimal](#decimal) | — | — | | `projected_post_trade_liquidation_price` | [Decimal](#decimal) \| `null` | — | — | | `projected_post_trade_leverage` | [Decimal](#decimal) | — | — | | `expected_fill_vwap` | [Decimal](#decimal) \| `null` | — | — | | `projected_fees` | [Decimal](#decimal) | — | — | ## RateLimitStatus | Field | Type | Required | Description | | ------------- | ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tier` | `string` | Yes | Rate limit tier name (e.g. `pro`, `marketmaker`, `unlimited`). | | `limit` | `integer` \| `null` | Yes | Maximum requests per second. Also the burst capacity — the token bucket holds one second's worth of tokens — so `remaining` never exceeds it. Null for the unlimited tier. | | `remaining` | `integer` \| `null` | Yes | Requests that can be made right now before throttling (tokens currently in the bucket). Null for the unlimited tier. | | `reset_at_ms` | `integer` \| `null` | Yes | Unix timestamp in milliseconds when the bucket refills back to `limit`; `0` when it is already full. Null for the unlimited tier. | ## ServiceHealth Aggregate health for the indexer/engine/oracle/bots, consumed by status.nexus.xyz. The `services` object carries per-component detail; only the common fields are documented here. | Field | Type | Required | Description | | -------------- | --------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `status` | `string` | — | Worst-of across all components. One of: `ok`, `degraded`, `down`, `starting`. | | `timestamp_ms` | [TimestampMs](#timestampms) | — | — | | `services` | `object` | — | Per-component status (indexer, engine, oracle, bots). Component detail is informational and may evolve; clients should rely on the top-level `status`. | ## SetCancelOnDisconnectRequest Cancel-on-disconnect opt-in change for the authenticated account. | Field | Type | Required | Description | | --------- | --------- | -------- | ----------------------------------------------------- | | `enabled` | `boolean` | Yes | True to enable COD for the account, false to disable. | ## StatsSnapshot Aggregate venue statistics. `/stats` augments the snapshot with rolling unique-trader counts. | Field | Type | Required | Description | | ----------------------- | ------------------------------------- | -------- | ------------------------------------------------------------ | | `events_received` | `integer` | — | — | | `fills_total` | `integer` | — | — | | `liquidations_total` | `integer` | — | — | | `gap_count` | `integer` | — | — | | `connected` | `boolean` | — | — | | `last_event_ms` | [TimestampMs](#timestampms) \| `null` | — | — | | `uptime_seconds` | `integer` | — | — | | `events_per_sec` | `number` | — | — | | `health` | `string` | — | Health classification (e.g. Healthy / Degraded / Unhealthy). | | `highest_sequence_seen` | `integer` | — | — | | `unique_traders_24h` | `integer` | — | Rolling 24h unique traders (DAU). Present on `/stats`. | | `unique_traders_7d` | `integer` | — | Rolling 7d unique traders (WAU). Present on `/stats`. | | `unique_traders_30d` | `integer` | — | Rolling 30d unique traders (MAU). Present on `/stats`. | ## ThroughputSample One point in the venue throughput ring buffer (1s cadence, capped at 3600 points). | Field | Type | Required | Description | | ----------- | --------- | -------- | ------------- | | `timestamp` | `integer` | — | Unix seconds. | | `fills` | `integer` | — | — | ## Ticker CCXT-compatible ticker with 24h statistics | Field | Type | Required | Description | | ------------- | --------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `symbol` | `string` | — | — | | `timestamp` | [TimestampMs](#timestampms) | — | Unix ms | | `datetime` | `string` | — | Format `date-time`. | | `high` | `number` \| `null` | — | — | | `low` | `number` \| `null` | — | — | | `bid` | `number` \| `null` | — | — | | `bidVolume` | `number` \| `null` | — | — | | `ask` | `number` \| `null` | — | — | | `askVolume` | `number` \| `null` | — | — | | `open` | `number` \| `null` | — | — | | `close` | `number` \| `null` | — | — | | `last` | `number` \| `null` | — | — | | `change` | `number` \| `null` | — | — | | `percentage` | `number` \| `null` | — | — | | `baseVolume` | `number` \| `null` | — | — | | `quoteVolume` | `number` \| `null` | — | — | | `markPrice` | `number` \| `null` | — | Engine-derived mark price (oracle + premium-index), falling back to the last trade until the first mark-price poll lands. The raw last trade is carried by `last`. | | `indexPrice` | `number` \| `null` | — | — | | `info` | `object` | — | — | ## TimestampMs Unix epoch timestamp in milliseconds. **Type:** `integer` (format `int64`) ## Trade CCXT-compatible trade record | Field | Type | Required | Description | | ---------------- | --------------------------- | -------- | ---------------------- | | `id` | `string` | — | Format `uuid`. | | `symbol` | `string` | — | — | | `price` | `number` | — | — | | `amount` | `number` | — | — | | `cost` | `number` | — | — | | `side` | `string` | — | One of: `buy`, `sell`. | | `timestamp` | [TimestampMs](#timestampms) | — | — | | `datetime` | `string` | — | Format `date-time`. | | `takerOrMaker` | `string` \| `null` | — | — | | `is_liquidation` | `boolean` | — | — | | `info` | `object` | — | — | ## Withdrawal A single withdrawal record for the authenticated account | Field | Type | Required | Description | | ----------- | --------------------------- | -------- | -------------------------------------------------------------------- | | `id` | `string` | Yes | Withdrawal ID | | `amount` | [Decimal](#decimal) | Yes | Withdrawn amount in USDX (decimal string) | | `timestamp` | [TimestampMs](#timestampms) | Yes | Unix ms | | `status` | `string` | Yes | Withdrawal lifecycle status. One of: `pending`, `settled`, `failed`. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://docs.nexus.xyz/api-reference/guides/schemas.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.