> 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.70**). Every one of the 100 schemas an operation can reach is documented here, once each; the endpoint pages link into these anchors instead of repeating field tables. The contract at `/openapi.json` remains authoritative — this page is generated from it, so the two cannot disagree. 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, and casing does not imply value type.** Native Nexus schemas use `snake_case` keys and decimal strings. The CCXT-compatible schemas ([Ticker](#ticker), [OrderBook](#orderbook), [Trade](#trade), [Order](#order)) use CCXT's `camelCase` keys for the fields CCXT defines and keep `snake_case` for the Nexus extensions it does not, so one schema carries both. Their value types are not uniform: `Ticker`, `OrderBook` and `Trade` serialize numbers as JSON numbers for drop-in compatibility with existing CCXT tooling, while `Order` keeps every monetary and quantity field a decimal string (EDR-012). Read each schema's own field types rather than inferring them from its casing. * **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) * [AccountFundingRequestError](#accountfundingrequesterror) * [AccountFundingSnapshot](#accountfundingsnapshot) * [AccountFundingSourceError](#accountfundingsourceerror) * [AccountFundingWindow](#accountfundingwindow) * [AccountMarketFee](#accountmarketfee) * [AccountPortfolioSummary](#accountportfoliosummary) * [AccountReferralsSummary](#accountreferralssummary) * [AccountState](#accountstate) * [AccountSummary](#accountsummary) * [ActivityEntry](#activityentry) * [AdjustMarginResponse](#adjustmarginresponse) * [AdlClosureRecord](#adlclosurerecord) * [AdlEventRecord](#adleventrecord) * [AgentInfo](#agentinfo) * [AgentRegistrationRequest](#agentregistrationrequest) * [AgentRegistrationResponse](#agentregistrationresponse) * [AmendOrderRequest](#amendorderrequest) * [ApiVersionMetadata](#apiversionmetadata) * [BalanceBucket](#balancebucket) * [BalanceDistribution](#balancedistribution) * [BridgeAssetsResponse](#bridgeassetsresponse) * [BridgeChainAssets](#bridgechainassets) * [BridgeDeposit](#bridgedeposit) * [BridgeDepositAsset](#bridgedepositasset) * [BridgeError](#bridgeerror) * [BridgeWithdrawAsset](#bridgewithdrawasset) * [BridgeWithdrawal](#bridgewithdrawal) * [BridgeWithdrawalRequest](#bridgewithdrawalrequest) * [CancelOnDisconnectStatus](#cancelondisconnectstatus) * [ClosedPosition](#closedposition) * [CreateKeyResponse](#createkeyresponse) * [CreditRequest](#creditrequest) * [CreditResponse](#creditresponse) * [CumulativeVolume](#cumulativevolume) * [Decimal](#decimal) * [DepositRequest](#depositrequest) * [DepositResponse](#depositresponse) * [DepositTarget](#deposittarget) * [DepositTargetConfirm](#deposittargetconfirm) * [DepositTargetOnchain](#deposittargetonchain) * [DepositTargetTestnetFaucet](#deposittargettestnetfaucet) * [EquityPoint](#equitypoint) * [ExecutionFill](#executionfill) * [FaucetResponse](#faucetresponse) * [FeeDiscount](#feediscount) * [Fill](#fill) * [FundingPremiumSample](#fundingpremiumsample) * [FundingSample](#fundingsample) * [FundsEntry](#fundsentry) * [KeyInfo](#keyinfo) * [LeverageResponse](#leverageresponse) * [LoginRequest](#loginrequest) * [LoginResponse](#loginresponse) * [MarkPriceResponse](#markpriceresponse) * [Market](#market) * [MarketCumulativeVolume](#marketcumulativevolume) * [MarketOpenInterest](#marketopeninterest) * [MarketRiskParams](#marketriskparams) * [MarketStatus](#marketstatus) * [MarketSummary](#marketsummary) * [OpenInterest](#openinterest) * [Order](#order) * [OrderBook](#orderbook) * [OrderHistoryEntry](#orderhistoryentry) * [OrderRequest](#orderrequest) * [OrderResponse](#orderresponse) * [OrderResult](#orderresult) * [OrderResultErr](#orderresulterr) * [OrderResultOk](#orderresultok) * [OrdinaryTransferEnrollment](#ordinarytransferenrollment) * [OrdinaryTransferEnrollmentResponse](#ordinarytransferenrollmentresponse) * [OrdinaryTransferError](#ordinarytransfererror) * [OrdinaryTransferHistory](#ordinarytransferhistory) * [OrdinaryTransferReceipt](#ordinarytransferreceipt) * [OrdinaryTransferRequest](#ordinarytransferrequest) * [PortfolioHistory](#portfoliohistory) * [PortfolioPoint](#portfoliopoint) * [PortfolioWindow](#portfoliowindow) * [Position](#position) * [PositionPnl](#positionpnl) * [PreviewResponse](#previewresponse) * [RateLimitBucketStatus](#ratelimitbucketstatus) * [RateLimitStatus](#ratelimitstatus) * [ReferralStats](#referralstats) * [ServiceHealth](#servicehealth) * [SetCancelOnDisconnectRequest](#setcancelondisconnectrequest) * [StatsSnapshot](#statssnapshot) * [ThroughputSample](#throughputsample) * [Ticker](#ticker) * [Tier](#tier) * [TierEntry](#tierentry) * [TimestampMs](#timestampms) * [Trade](#trade) * [WithdrawalError](#withdrawalerror) * [WithdrawalRequest](#withdrawalrequest) * [WithdrawalResponse](#withdrawalresponse) * [WsTokenLegacyResponse](#wstokenlegacyresponse) * [WsTokenResponse](#wstokenresponse) ## AccountFees The authenticated account's most recently mirrored fee schedule, mirroring Hyperliquid `userFees`. Reports the forward-looking schedule rate, not a realized per-fill average. There are no per-account fee tiers or discounts today, so `tier` is `base` and `discounts` is empty. Without a selector, `markets` is the per-market breakdown available from the current mirror for currently listed markets represented in the currently retained fill buffer and the top-level bps pair is only its modal summary. With `market_id`, `markets` contains only that exact target when currently listed and available, and the headline is its pair. Absence from an unfiltered `markets` list is not evidence that the account never traded a market; absence for a selected target means the exact target is unavailable, delisted, or the mirror is stale and the response fails closed as `unknown`. This response carries no source timestamp; consumers must not infer freshness from a successful read. | Field | Type | Required | Description | | ---------------------- | ------------------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `maker_fee_bps` | `integer` | Yes | Headline maker fee in basis points. Negative means the maker is *paid* a rebate. When `schedule` is `per_market`, inspect `markets` for each available per-market rate; when it is `unknown`, zero is a sentinel rather than a known fee. | | `taker_fee_bps` | `integer` | Yes | Headline taker fee in basis points. When `schedule` is `per_market`, inspect `markets` for each available per-market rate; when it is `unknown`, zero is a sentinel rather than a known 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 top-level bps pair. With `market_id`, `per_market` means the exact target is currently listed and mirrored: `markets` contains its sole row and the headline is that row's pair; `unknown` means that target is unavailable, delisted, or the mirror is stale, so zero headline values are sentinels and `markets` is empty. Without a selector, `per_market` means the currently retained account-fill buffer represents at least one currently listed market with mirrored fee parameters: `markets` contains those rows and the headline is their deterministic modal pair. `reference` is unfiltered-only: the retained buffer contains no currently listed market with a mirrored schedule, so the headline is the deterministic modal pair across all available currently listed venue markets and `markets` is empty; it does not prove the account never traded a market. For both unfiltered modal calculations, the pair with the highest occurrence count wins and a tie chooses the lexicographically smallest `(maker_fee_bps, taker_fee_bps)` pair. Unfiltered `unknown` means no currently listed market fee parameters are available yet. Treat this as an open string because new scopes may appear. | | `markets` | array of [`AccountMarketFee`](#accountmarketfee) | Yes | Without `market_id`, the most recently mirrored schedule for each distinct currently listed market represented in the account's currently retained fill buffer whose fee parameters are available, sorted by `market_id`. With `market_id`, exactly one row for that target when it is currently listed and its current schedule is available. A delisted market is omitted even while its historical fills and last mirrored parameters remain retained. Returned rows are authoritative for the response's schedule scope, but the response carries no source timestamp; the unfiltered, capped in-memory fill buffer can reset or evict old markets, so neither freshness nor lifetime trading may be inferred from that mode. Empty for `reference` and `unknown`. | | `volume_30d` | [`Decimal`](#decimal) | Yes | Rolling 30-day traded notional for the account, as a decimal string. Served from one of two sources, and `volume_30d_estimated` says what guarantee applies. Where the durable fee projection is available and caught up, this is an aggregate over a per-fill ledger sourced from the Cold Data fills tape — uncapped and durable across restarts. Otherwise it is summed from a bounded in-memory fill buffer that resets on restart, which is the only source in deployments where cold-data capture is off. Parse this string; do not compare it. The scale is not part of the contract, and the two sources spell the same figure differently. | | `volume_30d_estimated` | `boolean` | Yes | `false` means `volume_30d` is not known to undercount. What that is worth depends on which source answered, and this field deliberately does not say which — a client needing a completeness guarantee should assume the weaker of the two readings below. **Durable projection:** `false` is a statement about backfill coverage, not a real-time guarantee — it means the ingest has caught up to within a few minutes of now, which implies the 30-day window is covered back to its start. It does **not** promise the most recent few minutes are included: the ingest advances in ticks, so a `false` figure can still exclude fills from just before the request. A client polling for a value to change the instant a trade lands should expect a short delay on this path. **In-memory fallback:** `true` when the source fill buffer was at capacity, so older in-window fills were evicted. `false` means no eviction was detected — it is **not** a guarantee that the full 30-day window is covered. A buffer that started empty or partial (a service instance with no history to hydrate from) undercounts too, and from the server's side that is indistinguishable from an account that simply traded little. Read the flag as a floor on the doubt, not a completeness certificate — the same semantics `total_realized_pnl_30d_estimated` carries on `GET /account/summary`. | | `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) | — | — | ## AccountFundingRequestError | Field | Type | Required | Description | | --------- | ----------------------------------------------------- | -------- | ----------- | | `code` | `string` — one of `INVALID_QUERY` \| `MarketNotFound` | Yes | — | | `message` | `string` | Yes | — | ## AccountFundingSnapshot One coherent engine-owned account/market observation, including closed pending obligations. All nullable fields must be present. A complete status requires complete=true and all three monetary fields to be non-null. Unsampled or unavailable status requires complete=false and open\_integral, closed\_pending\_integral, and settled\_cash all null, including when the source would otherwise report a zero string. Contradictory source responses are rejected with FUNDING\_SOURCE\_INVALID (502). Monetary values are decimal strings or null; absent support is never a zero-cost response. For same-generation baselines B0/U0 and current settled cash B / sum of integrals U, interval cost is -(B-B0)+(U-U0). Actual settled cost is -(B-B0), final only once attributable pending obligations have settled. | Field | Type | Required | Description | | ------------------------- | ------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `owner` | `string` | Yes | Owner resolved from authentication; account selection is not accepted. | | `market_id` | `string` | Yes | — | | `settlement_asset` | `string` — one of `USDX` | Yes | — | | `generation` | `string` | Yes | Cash-counter generation. Restart, restoration or market reinitialization may replace this token; do not difference counters across generations. | | `cursor` | `string` | Yes | Monotonic observation sequence within a generation, encoded as a string for lossless clients. Not a WAL offset. | | `observed_at_ms` | `integer` | Yes | UTC Unix milliseconds when the authoritative actor read the coherent state. Edge refuses observations older than 5000 ms or over 1000 ms in the future. | | `accrued_through_ms` | `integer` \| `null` | Yes | Last committed funding tick or settlement covered by the integrals, UTC Unix milliseconds. This is not the HTTP time or funding-rate sampling cadence; consumers must apply their own funding freshness budget. Null means unsampled. A complete response requires a nonzero time no later than observation and scheduled window end. After early forced settlement, the actual boundary may precede the next scheduled window start. | | `funding_window` | [`AccountFundingWindow`](#accountfundingwindow) | Yes | — | | `complete` | `boolean` | Yes | True only with complete risk state through accrued\_through\_ms. It does not assert that no accrual exists after that boundary. | | `status` | `string` — one of `complete` \| `unsampled` \| `unavailable` | Yes | — | | `open_integral` | `string` \| `null` | Yes | Signed USDX integral for the open position; positive is owed. Null is unknown. | | `closed_pending_integral` | `string` \| `null` | Yes | Signed USDX integral retained after positions close; positive is owed. Flat accounts can have a nonzero value. Null is unknown. | | `settled_cash` | `string` \| `null` | Yes | Cumulative actual USDX collateral cash from all committed funding settlement contributions within this generation. Positive is received, negative paid; payer caps are already reflected. Null is unknown. | ## AccountFundingSourceError | Field | Type | Required | Description | | --------- | ---------------------------------------------------------------------------------------------------- | -------- | ----------- | | `code` | `string` — one of `FUNDING_SOURCE_UNAVAILABLE` \| `FUNDING_SOURCE_INVALID` \| `FUNDING_SOURCE_STALE` | Yes | — | | `message` | `string` | Yes | — | ## AccountFundingWindow Currently scheduled authoritative funding window. Bounds are UTC Unix milliseconds, start inclusive and end exclusive. An early forced settlement can advance this schedule ahead of the actual accrued\_through\_ms boundary. | Field | Type | Required | Description | | ---------- | --------- | -------- | ----------- | | `id` | `string` | Yes | — | | `start_ms` | `integer` | Yes | — | | `end_ms` | `integer` | Yes | — | ## AccountMarketFee The most recently mirrored maker/taker schedule for one market. In an unfiltered response the account's retained fill buffer selected the market; with `market_id` the caller selected it directly. The parent response carries no source timestamp, so consumers must not infer freshness from this row alone. | Field | Type | Required | Description | | --------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `symbol` | `string` | Yes | Market identifier, using uppercase ASCII alphanumeric segments joined by single hyphens. Named `market_id` until ENG-13528 renamed it to CCXT's `symbol`. `/account/fees` spans markets, so a row has to say which one it belongs to — the same reason `Trade.symbol` is native. | | `maker_fee_bps` | `integer` | Yes | Maker fee in basis points for this market. Negative means the maker is paid a rebate. | | `taker_fee_bps` | `integer` | Yes | Taker fee in basis points for this market. | ## 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) | — | Rolling 24-hour realized PnL for the account, as a decimal string: PnL booked when a position closes, funding excluded. Best-effort — see `total_realized_pnl_24h_estimated`. | | `total_realized_pnl_24h_estimated` | `boolean` | — | `true` when `total_realized_pnl_24h` is known to undercount: the source closed-positions buffer was at capacity **and** its oldest retained close still falls inside the 24-hour window, so closes inside that window were evicted. Both conditions are required — a full buffer whose oldest entry is already older than the window has lost nothing inside it, and reports `false`. `false` is **not** a guarantee that the window is complete: a buffer that started empty or partial (a service instance with no history to hydrate from) undercounts too, and from the server's side that is indistinguishable from an account that simply closed few positions. Read the flag as a floor on the doubt, not a completeness certificate. | | `total_realized_pnl_30d` | [`Decimal`](#decimal) | — | Rolling 30-day realized PnL for the account, as a decimal string. Counts exactly what `total_realized_pnl_24h` counts, over a longer window: PnL booked when a position closes. Funding settlements are excluded from both, so neither field matches a lifetime realized-PnL figure that folds funding in. Best-effort — see `total_realized_pnl_30d_estimated`. | | `total_realized_pnl_30d_estimated` | `boolean` | — | `true` when `total_realized_pnl_30d` is known to undercount: the source closed-positions buffer was at capacity **and** its oldest retained close still falls inside the 30-day window, so closes inside that window were evicted. Same two-part test as `total_realized_pnl_24h_estimated`, against the longer cutoff — so this field can be `true` while the 24-hour one is `false` (the buffer reaches back past a day but not past a month), and whenever the 24-hour flag is `true` this one is too. `false` is **not** a guarantee that the full 30-day window is covered: a buffer that started empty or partial (a service instance with no history to hydrate from) undercounts too, and from the server's side that is indistinguishable from an account that simply closed few positions. Read the flag as a floor on the doubt, not a completeness certificate. | | `total_volume_24h` | [`Decimal`](#decimal) | — | Traded notional (price × size, summed) over the last 24 hours, as a decimal string. Best-effort — see `total_volume_24h_estimated`. | | `total_volume_24h_estimated` | `boolean` | — | `true` when `total_volume_24h` is known to undercount: the source fills buffer was at capacity **and** its oldest retained fill still falls inside the 24-hour window, so fills inside that window were evicted. Both conditions are required — a full buffer holding a fortnight of fills has an intact 24-hour window and reports `false`. `false` means no in-window eviction was detected, not that the window is certified complete. | | `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. | | `early_access_allowed` | `boolean` | — | Present only when the early-access gate is active. | ## AccountReferralsSummary The authenticated account's own referrals summary (ENG-14757): its own referral code, plus how many accounts used it. `referred_count` is every account that redeemed the code; `active_referred_count` is the subset that has also traded at least once (a qualifying `account_activity` row) — referral-edge existence alone is never a qualifying signal for any metric beyond a raw count. **Any metric-shaped surface (a headline count, a leaderboard, a reward-adjacent badge) must render `active_referred_count`, never `referred_count`** — per PRD A-7, an unqualified referral count must never be presented as "a real referred user." `referred_count` exists for a literal "codes redeemed" display only, if that is ever shown separately from the qualified figure. | Field | Type | Required | Description | | ----------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `code` | `string` | Yes | This account's own 22-character referral code. `null` if no code has ever been minted for this account — a real, permanent state for any account that completed registration before ENG-13624 shipped `ensure_code_and_bind` on POST /agents/register, since nothing on this read path mints a code retroactively. | | `referred_count` | `integer` | Yes | Every account that redeemed this account's code, regardless of trading activity. A raw count, not a metric — see this schema's description before rendering it as one. | | `active_referred_count` | `integer` | Yes | The subset of referred\_count that has also traded at least once. This is the field any metric-shaped UI must use per PRD A-7 (a referral count read as a metric requires qualifying activity), not referred\_count. | ## 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 The authenticated account's balances and open positions in one read, as served by `GET /account`. Monetary fields are lossless decimal strings. `positions` carries the full `Position` objects, including their `_error` companions, so a caller does not need a second call to `/positions` — and inherits the same rule that an unavailable derived field is `null` with a reason rather than a fabricated number. | Field | Type | Required | Description | | ------------------ | -------------------------------- | -------- | ----------- | | `balance` | [`Decimal`](#decimal) | — | — | | `collateral` | [`Decimal`](#decimal) | — | — | | `equity` | [`Decimal`](#decimal) | — | — | | `available_margin` | [`Decimal`](#decimal) | — | — | | `positions` | array of [`Position`](#position) | — | — | ## ActivityEntry One row of the account's activity, as returned by `GET /account/activity`. The four single-purpose histories — `/deposits`, `/withdrawals`, `/fills` and `/funding` — projected onto one heterogeneous row type and merged into one time order. **Every field is always present**, with `null` where the field does not apply to the row's `cause`. That is deliberate: this list is heterogeneous by construction, so a client rendering a table needs a fixed column set it can address on every row without branching on the cause first. **Field names are native, not CCXT's.** `FundsEntry` spells the same two facts `currency` and `txid` because that schema is CCXT-badged (`fetchDeposits` / `fetchWithdrawals`) and its names follow CCXT's `Transaction`. This operation carries no badge — see its `x-ccxt-scope-reason` — so it keeps the venue's own spelling. ### What `amount` means, per cause Signed from the account's point of view: negative is value leaving, positive is value arriving. | Cause | `amount` is | | ----------------------------- | --------------------------------------------------------------- | | `deposit`, `faucet`, `credit` | the credited amount, positive | | `withdrawal` | the debited amount, negative | | `fee` | the fee, negative; a maker rebate is a positive row | | `funding` | the settled funding payment, signed | | `trade`, `liquidation` | the fill's **quote notional** (price × size), negative on a buy | **The `trade` row is not a cash movement, and this is the one thing to internalize about this schema.** On a perpetual, a fill moves exposure rather than collateral: what moves the balance is the fee — its own row, beside it — plus realized PnL — now its own field, `realized_pnl`. **`amount` is unchanged and still states the quote notional** on a `trade`/`liquidation` row, not the balance movement; repurposing it would be a breaking change for existing callers, so realized PnL is served additively instead. **Summing `amount` down the page is still not a balance reconciliation** and must not be presented as one. Nor does `realized_pnl` turn this into CCXT's `fetchLedger`: that operation's `amount` means the balance movement itself, and this schema still splits that movement across three places (the fee row, `realized_pnl`, and the notional `amount`) rather than stating it as one number — see this operation's `x-ccxt-scope-reason`. | Field | Type | Required | Description | | -------------- | --------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | Yes | Unique within one answer, and stable for as long as the source retains the record: the source's own identifier behind a `:` prefix — `funds:<20-digit id>`, `fill:`, `fee:` or `funding::`. **Treat it as this list's row key, not as a durable receipt.** A funding row has no identifier of its own in the venue's record, so its id is composed here; it addresses the row and nothing else. Use `reference_id` or `tx_hash` to join back to the underlying object. | | `timestamp` | [`TimestampMs`](#timestampms) | Yes | Unix ms. For a `funding` row this is the settlement window close; for `fee` it is its fill's timestamp, so the pair sorts adjacently. | | `cause` | `string` — one of `deposit` \| `withdrawal` \| `faucet` \| `credit` \| `trade` \| `liquidation` \| `fee` \| `funding` | Yes | What the row is attributed to. `faucet` and `credit` are the two non-deposit `kind`s the funds ledger carries (`FundsEntry.kind`). They are kept distinct rather than folded into `deposit`, which would report a testnet faucet claim or an operator credit as a user deposit. `liquidation` is a fill whose `Fill.is_liquidation` is true; it replaces `trade` on that row rather than accompanying it. **The enum is open to additions.** A new cause is a new value here, so branch with a default rather than exhaustively. | | `asset` | `string` | Yes | The asset the movement is denominated in. Always `USDX` today — it is the venue's only quote and margin asset — and stated per row rather than once per response so the shape survives a second asset. | | `amount` | `string` \| `null` | Yes | Signed decimal string; see the per-cause table in this schema's description for what it measures. Parse with a decimal type, never a float. `null` **only** when `amount_error` is set, and never as a stand-in for zero. | | `amount_error` | `string` \| `null` | Yes | Why `amount` could not be stated; `null` on every healthy row. A row whose source amount does not read as a decimal keeps its place in the list and names the failure here, rather than being dropped or published with a guessed sign — a silently missing money row is the failure this view exists to prevent. Render such a row as unknown; do not treat it as zero and do not include it in a total presented as complete. | | `realized_pnl` | `string` \| `null` | Yes | This fill's settled realized PnL, signed from the account's point of view — present only on `trade` and `liquidation` rows sourced from the durable Cold Data trade-history projection. `null` on every other cause, and `null` on a `trade`/`liquidation` row whose source fill predates that projection or simply stated none — `null` is not zero here, the same convention `amount_error` documents for `amount`. **Does not change what `amount` means.** `amount` keeps stating the fill's quote notional on these rows; this is an additive field, not a replacement — see the per-cause `amount` table above. **A `null` here can also mean the durable projection is temporarily lagging**, not that the fill realized nothing: when that happens every trade row in the same response reads `realized_pnl: null` at once, for that response only. There is currently no separate signal distinguishing the two cases on the wire. | | `market_id` | `string` \| `null` | Yes | The market the movement belongs to, for `trade`, `liquidation`, `fee` and `funding` rows. `null` for funds movements, which are not per-market. | | `reference_id` | `string` \| `null` | Yes | The originating object: the parent order id for `trade`, `liquidation` and `fee` rows. `null` where the source has nothing to point at. | | `status` | `string` \| `null` | Yes | The funds-ledger lifecycle status, for funds rows only — the same values `FundsEntry.status` carries. `null` on `trade`, `liquidation`, `fee` and `funding` rows, which have no pending state: they are recorded once, already settled. **A row is listed whatever its status**, `failed` included, so do not sum `amount` across a page without filtering on this field. | | `tx_hash` | `string` \| `null` | Yes | On-chain transaction hash (0x-prefixed hex) for a funds row that has one; `null` until the movement is submitted on-chain, and `null` on every non-funds row. `FundsEntry` spells this same field `txid`. | ## AdjustMarginResponse Allocated margin and free collateral after an isolated-margin adjustment. A `200` means the engine committed both legs, and all three fields are always present. | Field | Type | Required | Description | | ------------------ | --------------------- | -------- | -------------------------------------------------------------- | | `market_id` | `string` | Yes | The market whose position was adjusted. | | `allocated_margin` | [`Decimal`](#decimal) | Yes | The position's allocated isolated margin AFTER the adjustment. | | `collateral` | [`Decimal`](#decimal) | Yes | Free collateral AFTER the adjustment. | ## 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 A registered agent key as `GET /agents` reports it. **This schema is camelCase**, unlike the snake\_case native Nexus schemas around it: `expiresAt` and `registeredAt`, not `expires_at` and `registered_at`. It is not one of the CCXT-compatible schemas either, so it matches neither naming family the Schema Reference's conventions describe. Read the field names here literally rather than inferring them from the rest of the API. | 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 Delegates trading to an agent keypair without handing over the owner wallet's key. The signature is EIP-712 over `RegisterAgent{agent, expiresAt, nonce}`, produced by the **wallet** key, and the signing domain is per-network — a payload signed for one network is invalid on another and must never be replayed across them. Only `wallet`, `agent`, `nonce` and `signature` are required; note that `label` and `referral_code` sit outside the signed struct. | 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') | | `referral_code` | `string` | No | Referral code captured from a nexus.xyz/ref/ `landing, if any. Not part of the signed EIP-712 payload. A missing or invalid code never fails registration; see the response's has_referrer/bound_by_this_call.` | ## AgentRegistrationResponse | Field | Type | Required | Description | | -------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `agent_address` | `string` | Yes | The registered agent address (0x-prefixed) | | `expires_at` | `integer` | Yes | Expiry as Unix ms, echoing the effective value (request value or the now+30d default) | | `scope` | `string` | Yes | Always "trade\_only" today — echoed so the client can show the user exactly what authority the key was granted. | | `has_referrer` | `boolean` | Yes | Whether this wallet has any referral edge at all, from this call or an earlier one. Never reveals the referrer's own identity. | | `bound_by_this_call` | `boolean` | Yes | True only the one time this exact call performed the referral bind. A retry of the same request, or a later registration on an already-bound wallet, reports has\_referrer=true with bound\_by\_this\_call=false — never a bare false that could be misread as "binding failed" when an edge already exists. | ## 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. `size` is the new TOTAL quantity, including whatever the order has already filled, and must be greater than its `filled` — an amend cannot take back an execution, so a size at or below it is rejected with InvalidAmend. | Field | Type | Required | Description | | ------- | --------------------- | -------- | ----------- | | `price` | [`Decimal`](#decimal) | — | — | | `size` | [`Decimal`](#decimal) | — | — | ## ApiVersionMetadata Body of `GET /metadata`: the exchange network declared by required runtime configuration and the API version window this deployment accepts. Rendered once at boot, so every field is always present — an unset `deprecated_below` or `sunset` is serialized as `null` rather than omitted. Version strings are bare `MAJOR.MINOR.PATCH`. They are not the `v`-prefixed released spec tags, so compare them after stripping any prefix of your own. | Field | Type | Required | Description | | ------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `network` | `string` | Yes | Exchange network declared by the instance's required `auth.network` runtime configuration. Known values are `mainnet`, `testnet`, and `local`; clients must tolerate future values. This value is not inferred from deployment environment, hostname, or wallet state. | | `api_version` | `object` | Yes | The version window, and the pointers a rejected client needs in order to recover. | ## BalanceBucket One balance band and the number of accounts in it. | Field | Type | Required | Description | | ------- | --------------------- | -------- | ------------------------------------------------------------------------------------------ | | `min` | [`Decimal`](#decimal) | Yes | Inclusive lower bound of the band, in USDX collateral. | | `max` | [`Decimal`](#decimal) | No | Exclusive upper bound. ABSENT on the open-ended top band, which means `>= min` — not zero. | | `count` | `integer` | Yes | Accounts whose current balance falls in `[min, max)`. | ## BalanceDistribution Aggregate balance distribution. Carries no per-account values by construction. | Field | Type | Required | Description | | --------------- | ------------------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `buckets` | array of [`BalanceBucket`](#balancebucket) | Yes | Ascending bands. | | `account_count` | `integer` | Yes | Accounts summed across all bands. | | `network` | `string` | Yes | The chain network THIS indexer serves, taken from its required `auth.network` configuration (ENG-6443) rather than asserted by the handler. Gate on this rather than on the hostname you happened to fetch: the route lives per environment, so a URL change that nobody remembers to reflect in a downstream config would otherwise relabel the figure silently. Known values: `mainnet` (real funds), `testnet` (play funds), `local`. Deliberately an open string rather than an enum, matching `NetworkTarget.network` and `Metadata.network`, so a network added later cannot break deserialization — but treat an identifier you do not recognize as **real funds** rather than assuming play funds. `local` and `testnet` are distinct values and both report `testnet: true` — synthetic funds either way — so this is the only field that tells a local instance apart from the public testnet. | | `testnet` | `boolean` | Yes | `true` on every network whose funds are not real — the boolean reading of `network`. Kept beside it so consumers written before ENG-12796 keep working; `network` is the more precise field and the one to prefer. It was a hardcoded `true` until ENG-12796. | | `note` | `string` | Yes | Disclaimer. Unlike the other two stats notes, this sentence is swapped outright by network rather than given a leading qualifier, because every clause of the synthetic-funds variant is false on mainnet. On a synthetic-funds network (`testnet`, `local`) it states that the balances are faucet-funded, that the projection is in-memory and resets on redeploy, and that the figures are not real funds. On `mainnet` it states the aggregation and the redeploy reset without the faucet and not-real-funds clauses. | ## 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`. | | `chain_id` | `integer` \| `null` | Yes | EVM chain ID of the serving network (`1` mainnet, `11155111` Sepolia/testnet); `null` on a local instance that serves no numbered chain. | | `deposit_assets` | array of [`BridgeDepositAsset`](#bridgedepositasset) | Yes | Assets that can be deposited from this chain (USDC, USDX). | | `withdraw_assets` | array of [`BridgeWithdrawAsset`](#bridgewithdrawasset) | Yes | Assets that can be withdrawn to this chain (USDX). | ## BridgeDeposit A cross-chain deposit tracked by the watcher (read model). Because a deposit is created only when the watcher observes an on-chain transfer, `tx_hash`, `log_index` and `confirmations` are always present — there is no pre-arrival record. | Field | Type | Required | Description | | ------------------------ | ------------------------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | `string` | Yes | Opaque, stable deposit id: `{tx_hash}:{log_index}`. This is the watcher's dedup key, which is what makes replays harmless. | | `account_id` | `string` | Yes | 0x-prefixed Nexus account being credited. | | `chain` | `string` | Yes | Source chain, e.g. `ethereum`. | | `asset` | `string` — one of `USDC` \| `USDX` | Yes | Deposited asset. USDT is out of scope in this cut. | | `amount` | [`Decimal`](#decimal) | Yes | Deposit amount in units of `asset`. | | `credited_amount_usdx` | [`Decimal`](#decimal) | Yes | USDX credited to the account for this deposit. 1:1 with `amount` today. | | `from` | `string` | Yes | 0x-prefixed sender address the funds left. | | `to` | `string` | Yes | 0x-prefixed deposit address the funds arrived at. | | `tx_hash` | `string` | Yes | 0x-prefixed source-chain transaction hash. Always present: a deposit exists only once its transfer is observed. | | `log_index` | `integer` | Yes | Log index of the transfer within `tx_hash`. Pairs with it to form `id`. | | `status` | `string` — one of `detected` \| `confirming` \| `credited` \| `failed` \| `reverted` | Yes | Lifecycle: `detected` → `confirming` → `credited` \| `failed` \| `reverted`. `detected` is 0 confirmations, `confirming` is below the required depth, `credited` is final at the required depth. The two terminal failure states are distinct: `failed` means the deposit could not be credited; `reverted` means a reorg took it back. A client distinguishes them on this field, without parsing a reason. | | `confirmations` | `integer` | Yes | Confirmations observed so far. | | `required_confirmations` | `integer` | Yes | Confirmations required before crediting. | | `created_at` | [`TimestampMs`](#timestampms) | Yes | — | | `updated_at` | [`TimestampMs`](#timestampms) | Yes | — | | `credited_at` | [`TimestampMs`](#timestampms) | No | Unix ms when the deposit was credited; null until `status` is `credited`. | ## BridgeDepositAsset A depositable asset on a specific chain. | Field | Type | Required | Description | | --------------- | ---------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `symbol` | `string` — one of `USDC` \| `USDX` | Yes | Asset symbol. USDC and USDX only for this cut; USDT is out of scope. | | `decimals` | `integer` | Yes | On-chain token decimals for this asset on this chain. | | `min_amount` | [`Decimal`](#decimal) | Yes | Minimum accepted for a single deposit, measured on the **delivered** amount. Provisional: still being reconciled against the provider's quoted limits (ENG-8297), so treat it as a floor that may rise. | | `max_amount` | [`Decimal`](#decimal) | Yes | Maximum accepted for a single deposit. This is the vault's enforced per-transaction cap (`NexusVault.deposit` reverts above it), so a deposit over this amount fails on-chain rather than being clamped. | | `confirmations` | `integer` | Yes | Block confirmations required before a deposit is credited. | ## BridgeError Error envelope returned by all non-2xx /v1/bridge responses. | Field | Type | Required | Description | | ------- | -------- | -------- | ----------- | | `error` | `object` | Yes | — | ## BridgeWithdrawAsset A withdrawable asset on a specific chain. | Field | Type | Required | Description | | ------------ | ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `symbol` | `string` — one of `USDX` | Yes | Asset symbol. USDX only for this cut. | | `decimals` | `integer` | Yes | On-chain token decimals for this asset on this chain. | | `min_amount` | [`Decimal`](#decimal) | Yes | Minimum accepted for a single withdrawal. Provisional and not enforced on-chain (the release path has no floor); a UX floor only, separate from the deposit minimum and settled with the withdrawal path. | | `fee` | [`Decimal`](#decimal) | Yes | Flat fee charged in units of the asset (may be `"0"`). | ## BridgeWithdrawal A Halliday withdrawal (ENG-4625). Every payout pays a Halliday one-time wallet (OTW), quoted per withdrawal; Halliday then settles to the user asynchronously in the asset and destination the user chose. There is no user-supplied payout address and no route that skips Halliday. | Field | Type | Required | Description | | ---------------- | --------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | Yes | Opaque withdrawal id (`wdl_`), minted from a CSPRNG. Account-scoped: a guessed id from another account 404s. | | `account_id` | `string` | Yes | 0x-prefixed Nexus account being debited. | | `amount` | `string` | Yes | Withdrawal amount in USDX base units (integer, 6 decimals), as the request supplied it. | | `status` | `string` — one of `pending` \| `quoted` \| `broadcast` \| `confirmed` \| `failed` | Yes | Lifecycle: pending -> quoted -> broadcast -> confirmed \| failed. `quoted` once Halliday has returned an OTW, `broadcast` once the on-chain release is sent, `confirmed` once it is mined (Halliday then settles to the user). `failed` is terminal. On `failed` the Exchange debit is reversed only when the release is provably unpaid; an unknown-outcome release (broadcast, receipt unread) stays debited pending reconciliation, so `failed` does not by itself mean the balance was restored -- read `failure_reason`. | | `destination` | — | No | 0x-prefixed Halliday OTW this withdrawal pays; null until `quoted`. Never a user-supplied address. | | `tx_hash` | — | No | 0x-prefixed source-chain tx hash of the release; null until `confirmed`. An unknown-outcome `failed` release records its hash in `failure_reason` instead, since this field is written only on confirmation. | | `confirmations` | — | No | Confirmations observed for the release tx; null until `confirmed`. | | `failure_reason` | — | No | Operator-facing reason; present only when `status` is `failed`. | | `created_at` | [`TimestampMs`](#timestampms) | Yes | — | | `updated_at` | [`TimestampMs`](#timestampms) | Yes | — | ## BridgeWithdrawalRequest Trigger a withdrawal. The only field is the amount; there is deliberately no destination\_address -- the destination is the Halliday OTW quoted for this withdrawal (ENG-4625). | Field | Type | Required | Description | | -------- | -------- | -------- | -------------------------------------------------------------------------------------------------- | | `amount` | `string` | Yes | Withdrawal amount in USDX base units (a positive integer, 6 decimals). E.g. "10000000" is 10 USDX. | ## 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` — one of `Long` \| `Short` | — | The side the position was before it closed. | | `size` | [`Decimal`](#decimal) | — | Absolute size at close. | | `entry_price` | [`Decimal`](#decimal) | — | — | | `exit_price` | [`Decimal`](#decimal) | — | — | | `realized_pnl` | [`Decimal`](#decimal) | — | — | | `closed_at_ms` | [`TimestampMs`](#timestampms) | — | — | ## CreateKeyResponse A newly minted HMAC credential. `secret` is served exactly once, here: `GET /keys` serves `KeyInfo`, which has no secret field at all, and no other operation can recover it. A client that discards this response has lost the key. | Field | Type | Required | Description | | -------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `key_id` | `string` | Yes | Public key identifier: `nx_` followed by 16 lowercase hex characters. This is the value sent in the clear as the HMAC key id. | | `secret` | `string` | Yes | HMAC signing secret: 64 lowercase hex characters (32 random bytes). Never served again. The operation's example elides it; it is not a real length. | ## CreditRequest Claims synthetic USDX against the per-API-key daily allowance. Testnet only: mainnet collateral arrives through the bridge and there is no faucet or credit there. Omitting `amount` claims the whole remaining allowance for the day, so the field is a cap on the request rather than a required input. | Field | Type | Required | Description | | -------- | --------------------- | -------- | -------------------------------------------------------------------------------------------- | | `amount` | [`Decimal`](#decimal) | — | Synthetic USDX to credit (decimal string). Omit to claim the full remaining daily allowance. | ## CreditResponse What a credit claim granted, and what remains of the day's allowance. All three fields are required and all are decimal strings. `amount` is what this request credited, which can be less than what was asked for when the daily limit binds — compare `credited_today` against `daily_limit` to see the remaining headroom rather than assuming the request was granted in full. | 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). | ## CumulativeVolume Cumulative traded notional in quote, venue total and per market, with the coverage start that says what it is cumulative since. Aggregate only — it carries no account id, address, or per-account volume by construction. | Field | Type | Required | Description | | ------------------------- | ------------------------------------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cumulative_volume_quote` | [`Decimal`](#decimal) | Yes | Venue-wide cumulative traded notional in quote (USDX), as a decimal string — the sum of every entry in `markets`. | | `coverage_start_ms` | [`TimestampMs`](#timestampms) | No | Engine timestamp of the EARLIEST fill any market folded, so it bounds every fill the total counts. **Omitted when unknown** — nothing has traded since the indexer started, or the projection was restored from a checkpoint written before this field existed. Absence means unknown; never read it as zero or as the epoch. | | `markets` | array of [`MarketCumulativeVolume`](#marketcumulativevolume) | Yes | Per-market breakdown, ascending by `market_id` so two scrapes are directly comparable. | | `network` | `string` | Yes | The chain network THIS indexer serves, taken from its required `auth.network` configuration (ENG-6443) rather than asserted by the handler. Gate on this rather than on the hostname you happened to fetch: the route lives per environment, so a URL change that nobody remembers to reflect in a downstream config would otherwise relabel the figure silently. Known values: `mainnet` (real funds), `testnet` (play funds), `local`. Deliberately an open string rather than an enum, matching `NetworkTarget.network` and `Metadata.network`, so a network added later cannot break deserialization — but treat an identifier you do not recognize as **real funds** rather than assuming play funds. `local` and `testnet` are distinct values and both report `testnet: true` — synthetic funds either way — so this is the only field that tells a local instance apart from the public testnet. | | `testnet` | `boolean` | Yes | `true` on every network whose funds are not real — the boolean reading of `network`. Kept beside it so consumers written before ENG-12796 keep working; `network` is the more precise field and the one to prefer. It was a hardcoded `true` until ENG-12796. | | `note` | `string` | Yes | Disclaimer: not a 24h window, and restarts when the service does. It opens with a network-derived qualifier rather than a fixed one — `Illustrative testnet data.` on a synthetic-funds network (`testnet`, `local`), `Mainnet data.` on `mainnet`. | ## Decimal Arbitrary-precision decimal serialized as a string (lossless). Parse with a decimal type, never a float. *This schema declares no properties in the contract.* ## DepositRequest Credits collateral to the authenticated account directly, without the bridge. Only `amount` is required; `asset` defaults to USDX. This is the allowlisted operator path, not the route real funds take — a mainnet deposit arrives through the USDX bridge and is reported by the `/bridge/deposits` read model. | Field | Type | Required | Description | | -------- | --------------------- | -------- | ----------------------------------------- | | `amount` | [`Decimal`](#decimal) | Yes | Deposit amount (positive decimal string). | | `asset` | `string` | No | Asset symbol; defaults to USDX. | ## DepositResponse Engine deposit acknowledgement (forwarded). Includes the updated authoritative balance. Served by `POST /deposits` and by `POST /account/deposit`, which are the same engine handler behind two routes. | Field | Type | Required | Description | | --------- | --------------------- | -------- | ----------------------------------- | | `balance` | [`Decimal`](#decimal) | Yes | Authoritative post-deposit balance. | ## DepositTarget Funding instructions for the authenticated account, discriminated on `mode`. `onchain` is returned only by a deployment with a real deposit-contract address configured; every other deployment returns `testnet-faucet`. The mode is a property of the deployment, so a client must branch on it rather than pin one shape. *This schema declares no properties in the contract.* ## DepositTargetConfirm How to confirm the funds arrived. Identical in every mode, and the portable primitive: poll the named path until `poll_field` reflects the credit before trading. | Field | Type | Required | Description | | ------------ | -------- | -------- | ----------------------------------------------------------------- | | `method` | `string` | Yes | — | | `path` | `string` | Yes | Operation path to poll, relative to the base you are calling. | | `poll_field` | `string` | Yes | Field in that response whose change confirms the funds landed. | | `note` | `string` | No | Human-readable guidance. Diagnostic wording — do not match on it. | ## DepositTargetOnchain Funding instructions for a deployment with an on-chain deposit contract configured (mode `onchain`). Real value moves: the funds are bridged collateral, not synthetic. | Field | Type | Required | Description | | ------------ | ----------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mode` | `string` — one of `onchain` | Yes | — | | `account` | `string` | Yes | The authenticated account, as `0x` + 40 hex characters. This is whose balance the instructions fund; it is derived from the credential, not from any request parameter. | | `asset` | `string` | Yes | Collateral asset the instructions fund. USDX is the only collateral asset the venue accepts. | | `min_amount` | [`Decimal`](#decimal) | Yes | Smallest funding amount the venue advises, as a decimal string. **Advisory, not enforced** — `POST /account/credit` enforces only its per-key daily cap, and nothing rejects a smaller on-chain deposit. It is the floor that makes a first trade viable, and it is deployment configuration rather than a contract constant. | | `onchain` | `object` | Yes | The on-chain deposit target. | | `confirm` | [`DepositTargetConfirm`](#deposittargetconfirm) | Yes | — | ## DepositTargetTestnetFaucet Funding instructions for a deployment with no on-chain deposit contract configured (mode `testnet-faucet`). The credit is **synthetic test USDX with no real-world value**, applied off-chain — no on-chain transfer occurs. Do not build a funding flow that assumes this mode exists on every network: mainnet has no faucet. | Field | Type | Required | Description | | ------------ | ----------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mode` | `string` — one of `testnet-faucet` | Yes | — | | `account` | `string` | Yes | The authenticated account, as `0x` + 40 hex characters. This is whose balance the instructions fund; it is derived from the credential, not from any request parameter. | | `asset` | `string` | Yes | Collateral asset the instructions fund. USDX is the only collateral asset the venue accepts. | | `min_amount` | [`Decimal`](#decimal) | Yes | Smallest funding amount the venue advises, as a decimal string. **Advisory, not enforced** — `POST /account/credit` enforces only its per-key daily cap, and nothing rejects a smaller on-chain deposit. It is the floor that makes a first trade viable, and it is deployment configuration rather than a contract constant. | | `faucet` | `object` | Yes | The synthetic-credit endpoints to call. `primary` is preferred for autonomous clients — it is per-API-key and takes an amount; `alternate` is a fixed per-wallet grant. | | `confirm` | [`DepositTargetConfirm`](#deposittargetconfirm) | Yes | — | ## 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. | ## ExecutionFill A single match as the matching engine emits it, returned inside `OrderResponse.fills` and `OrderResultOk.fills`. Names both counterparties rather than one account, because at this layer a fill is a trade between two accounts and has not been projected onto either. **It is a different shape from `Fill`, not a variant of it.** `Fill` (`GET /fills`) is the indexer's per-account projection: it carries `order_id`, `size`, `fee` and `taker_or_maker`, and its `side` is the requesting account's own side, lowercase. This schema carries `quantity` rather than `size`, no `fee`, both order ids and both account ids, and its `side` is the TAKER's side in the engine's own `Buy`/`Sell` casing. A maker's side is the opposite of the value here — the engine performs exactly that flip in `flip_fill_for_maker` before applying the fill to the maker's position, and the indexer performs it again when building the per-account record. The two were one schema until ENG-10942, which is why a placement response documented a lowercase `side` the engine has never emitted. Every field below is always present. | Field | Type | Required | Description | | ---------------- | --------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | Yes | Trade ID for this match. | | `market_id` | `string` | Yes | Market (e.g. BTC-USDX-PERP) | | `price` | [`Decimal`](#decimal) | Yes | Executed price (decimal string) | | `quantity` | [`Decimal`](#decimal) | Yes | Executed quantity (decimal string). Named `quantity` here and `size` on `Fill`. | | `maker_order_id` | `string` | Yes | The resting order's ID. | | `taker_order_id` | `string` | Yes | The aggressing order's ID. This is the order you just placed when the fill arrives on a placement response. | | `maker_account` | `string` | Yes | The resting side's account, as `0x`-prefixed lowercase hex. | | `taker_account` | `string` | Yes | The aggressing side's account, as `0x`-prefixed lowercase hex. | | `side` | `string` — one of `Buy` \| `Sell` | Yes | The TAKER's side, in the same casing as `Order.side`. The maker's side is the opposite; do not read this as "my side" without first checking which of `maker_account` / `taker_account` is yours. | | `timestamp` | [`TimestampMs`](#timestampms) | Yes | Unix ms | | `is_liquidation` | `boolean` | Yes | Whether the aggressing order was a liquidation. | ## 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. No discount program exists today, so `discounts` is always empty and no properties are guaranteed yet. Additional properties may be added additively if a discount program is introduced. *This schema declares no properties in the contract.* ## Fill A single trade execution **projected onto the authenticated account**, as returned by `GET /fills`. The indexer builds it per account, so `side` is THIS account's side and `taker_or_maker` is the role this account played (indexer `AccountFillRecord`). This is not the shape an order placement returns — see `ExecutionFill` for that, and do not assume a fill from one surface parses as the other. Does not carry per-fill realized PnL — see `ActivityEntry.realized_pnl` on `GET /account/activity`, which states it. Adding it here is a separate, deferred decision (ENG-8657). | Field | Type | Required | Description | | ---------------- | ------------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | — | Fill ID | | `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 this fill cost the requesting account, in USDX (decimal string). Positive is a charge; negative is a maker rebate, i.e. a credit. On a self-match the account is both counterparties and settles both legs, so its single record reports the NET (taker fee minus maker rebate). **Optional — the key is OMITTED when the fill stated no fee, which is not a fee of zero.** `"0"` means the venue charged nothing (a liquidation fill is exempt on both legs); an absent key means it said nothing — a fill predating per-fill fee emission, or a leg the engine did not stamp. Before ENG-11832 both collapsed into `"0"`, and since the live `fills` WS frame already omitted the key, the two surfaces could describe the same fill differently. Treat absence as unknown, not as zero, and do not sum an absent fee into a total presented as complete. On a self-match the NET needs both legs stated, so the key is absent if either is. | | `taker_or_maker` | `string` — one of `taker` \| `maker` | — | — | | `timestamp` | [`TimestampMs`](#timestampms) | — | Unix ms | | `is_liquidation` | `boolean` | — | — | ## FundingPremiumSample One premium-index observation between settlements, as served by `/markets/{market_id}/funding-samples`. Carries the premium and its timestamp, and nothing else. The settled funding rate, mark price and oracle price are properties of a settled *window*, not of an intra-window sample, and the event these samples are folded from does not carry them. Read `/markets/{market_id}/funding` for those — it returns `FundingSample`. | Field | Type | Required | Description | | --------------- | ----------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `timestamp` | [`TimestampMs`](#timestampms) | Yes | — | | `premium_index` | [`Decimal`](#decimal) | Yes | `(trade_reference_price - oracle_price) / oracle_price` at the sample instant — the perpetual's own traded reference against the index, not the mark price. Reads `0` until the market has traded: with no trade reference available the value falls back to the oracle price, which makes the numerator exactly zero. A long run of `"0"` samples means the market has not traded, not that the perpetual is at parity with spot. | ## FundingSample A settled funding window, as served by `/markets/{market_id}/funding`: the realized rate for the window, plus the premium and prices of the last observation folded into it. This is not the shape of `/markets/{market_id}/funding-samples` — see `FundingPremiumSample`. | Field | Type | Required | Description | | --------------- | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `timestamp` | [`TimestampMs`](#timestampms) | — | — | | `fundingRate` | [`Decimal`](#decimal) | — | The realized funding rate for the settled window. Named `funding_rate` until ENG-13528 renamed it to CCXT's `fundingRate`, which is what `fetchFundingRateHistory` returns. | | `premium_index` | [`Decimal`](#decimal) | — | — | | `mark_price` | [`Decimal`](#decimal) | — | Named `mark_price` for wire compatibility only — this is not the blended mark price. It carries the perp reference: the volume-weighted median of the market's own recent trades at the settled window's last funding sample, which is the value the premium is measured against. The mark that margin and liquidations use is a blend of the oracle price and that trade reference, weighted heavily toward the oracle by default, so the two are not interchangeable — read the real mark from `GET /markets/{market_id}/mark-price`. This is that single last sample, not an average across the window; `funding_rate` beside it is the time-weighted result. Reads the oracle price until the market has traded, which makes `premium_index` exactly zero, and `"0"` when the window settled with no oracle sample at all. | | `oracle_price` | [`Decimal`](#decimal) | — | — | ## FundsEntry A deposit or withdrawal ledger entry. ENG-13528 moved four of its properties onto CCXT's `Transaction` vocabulary: `account` → `address`, `asset` → `currency`, `tx_hash` → `txid`, `status_updated_at` → `updated`. The remaining names are Nexus extensions CCXT has no counterpart for, and keep ours. | Field | Type | Required | Description | | ----------- | --------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | `integer` | Yes | — | | `kind` | `string` — one of `deposit` \| `withdrawal` \| `faucet` \| `credit` | Yes | — | | `address` | `string` | Yes | 0x-prefixed account address. Named `account` until ENG-13528 renamed it to CCXT's `address`. The rename is exact rather than approximate: this venue's account identifier IS the address the movement credits or debits. | | `amount` | [`Decimal`](#decimal) | Yes | — | | `currency` | `string` | Yes | Named `asset` until ENG-13528 renamed it to CCXT's `currency`. | | `timestamp` | [`TimestampMs`](#timestampms) | Yes | — | | `status` | `string` — one of `pending` \| `submitted` \| `confirmed` \| `failed` | Yes | — | | `txid` | `string` \| `null` | Yes | The on-chain transaction hash, null until the movement is submitted. Named `tx_hash` until ENG-13528 renamed it to CCXT's `txid`. | | `updated` | `integer` \| `null` | Yes | Unix ms of the last admin-driven status transition. Null until the first transition. Named `status_updated_at` until ENG-13528 renamed it to CCXT's `updated`; same nullability, same meaning. | ## KeyInfo An API key as `GET /keys` lists it. Carries no secret: the secret exists only in the `CreateKeyResponse` returned at creation. | Field | Type | Required | Description | | --------------- | ----------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `key_id` | `string` | Yes | Public key identifier, `nx_` + 16 lowercase hex characters. | | `tier` | [`Tier`](#tier) | Yes | — | | `label` | `string` \| `null` | Yes | Caller-supplied label from `POST /keys`, or `null` for a key created without one. **Nullable, not optional** — the field is always present, so read `null` rather than branching on a missing key. | | `created_at_ms` | [`TimestampMs`](#timestampms) | Yes | When the key was minted. The list is ordered by this value, oldest first. | ## LeverageResponse The stored per-market leverage setting, echoed back from the request. Declared by ENG-13528, which found this `200` carrying an example and no `schema` — so nothing verified the body and `oasdiff` had nothing to compare it against. This is **not** a CCXT structure. ccxt's `setLeverage` has no unified return at all (`Leverage` is what `fetchLeverage` returns, and nothing here is badged for that), so the shape gate records `setLeverage` as settled rather than as a gap, and declaring this body does not change that. The two are recorded apart on purpose. | Field | Type | Required | Description | | ----------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `market_id` | `string` | Yes | The market the setting applies to, echoed from the request. Deliberately not renamed to CCXT's `symbol`: this object is not a CCXT structure, so the vocabulary the rest of ENG-13528 moved does not reach it. | | `leverage` | `integer` | Yes | The whole-number leverage now stored for this account and market, echoed from the request. Always within `1..=max_leverage` for the market — a value outside it is refused rather than clamped. | ## LoginRequest Wallet-signature sign-in payload. The message is a fixed string rather than a nonce-bearing challenge, so a captured signature stays valid: treat it as a bearer credential and never log or forward it. Signed with EIP-191 `personal_sign`, which is a different scheme from the EIP-712 typed signature `POST /agents/register` requires — the two are not interchangeable. | 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 A session, and the address it was recovered from. **The token is a full-authority wallet credential, not a key-management one.** It is presented as `Authorization: Bearer`, and the same middleware that accepts an API key's HMAC or an agent key accepts it — agent, HMAC and Bearer all resolve to one `AuthContext`, so the token reaches the order surface, the funds routes and credential management alike. Minting an API key is what it is normally used for, but it is not what it is limited to: treat it as equivalent to the wallet, and prefer a scoped agent key for anything long-lived. `address` is recovered from the signature rather than supplied by the caller, so it is the venue's statement of who signed, not an echo. | 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) | ## MarkPriceResponse The current mark price for one market. `/markets/{market_id}/mark-price` and its `/api/v1` twin are the same handler behind two mounts, so the two responses cannot diverge. | Field | Type | Required | Description | | ------------ | --------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `market_id` | `string` | Yes | The market the price is for, echoed from the path. | | `mark_price` | [`Decimal`](#decimal) | Yes | Mark price as a decimal string at the market's own scale — trailing zeros are significant and preserved (`"50011.60"`, not `"50011.6"`). Never a zero or a null: an absent or stale mark is signalled by the response status, not by a sentinel in this field. | ## Market A market's static definition and risk parameters: the trading pair, its tick and lot granularity, order-size bounds, and the margin rates and caps the engine enforces against it. These are configuration rather than live state — nothing here moves with the book. For prices, volume and lifecycle status see `MarketSummary`; for the live book see `OrderBook`. `lot_size` is order granularity and is **not** a contract multiplier: `contractSize` is the separate field carrying the base-asset quantity one contract represents. ENG-13528 moved four properties onto CCXT's `Market` vocabulary: `market_id` → `id`, `base_asset` → `base`, `quote_asset` → `quote`, `contract_size` → `contractSize`. The rest are Nexus extensions CCXT has no counterpart for and keep our names. `MarketSummary` and `Position` still spell the multiplier `contract_size`; `Position` belongs to ENG-13312, so the surfaces differ deliberately. ENG-14839 added the four CCXT `Market` fields ENG-13528 measured as absent and left: `settle`, `type`, `marginModes` and `active`, plus the Nexus-extension `lifecycle` that `active` is a reading of. `active` and `lifecycle` are the only live state on this schema — everything else here is still configuration. | Field | Type | Required | Description | | ---------------------------- | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | — | Market identifier. Named `market_id` until ENG-13528 renamed it to CCXT's `id`. | | `base` | `string` | — | Base asset. Named `base_asset` until ENG-13528 renamed it to CCXT's `base`. | | `quote` | `string` | — | Quote asset. Named `quote_asset` until ENG-13528 renamed it to CCXT's `quote`. The asset the market is priced in. `settle` — the asset it is settled and margined in — is served separately and equals this on every market listed today, but is stated by the market rather than derived from this field (ENG-14839). | | `settle` | `string` | — | The asset this market settles and margins in — CCXT's `settle` (ENG-14839). `"USDX"` on every market listed today, and always equal to `quote`: the engine's margin, PnL, funding and fee math is single-collateral and carries no conversion term, so `validate_market_params` refuses a market whose settlement asset differs from its quote asset. **Stated, not derived.** Equality is an enforced invariant, not a definition. A quanto is quoted in one asset and settled in another, and CCXT's `linear` is `settle == quote` — so a client deriving this field from `quote` would compute a constant `true` for `linear` out of one value read twice, and could never report an inverse market it was looking at. | | `type` | `string` — one of `swap` | — | What kind of contract this market is, in CCXT's `Market.type` vocabulary (ENG-14839). `"swap"` — a perpetual — on every market listed today, and the only value the venue can currently produce. It is the field CCXT's eight instrument-type booleans (`swap`, `future`, `spot`, `option`, …) are all readings of, which is why the venue states it rather than leaving a client to assume it: an assumed constant misreports the first market that is not a perpetual, in the client, where the venue cannot correct it. The enum is deliberately not widened ahead of a listing. Listing a dated future or an option means teaching the engine its mechanics first, so a new value here is the edit that says those mechanics moved. | | `marginModes` | `object` | — | Which margin modes this market permits — CCXT's `marginModes` (ENG-14839). Both `true` on a `core`-class market, where the account's own default applies; `{cross: false, isolated: true}` on the exotic risk classes (RWA, equity, prelaunch, private), which force isolated margin so a blow-up is bounded by the margin posted against that position instead of reaching shared collateral, the insurance fund and venue-wide ADL. Derived from the market's risk class, which is Risk-owned policy (ENG-8289 / ENG-8701) — served rather than left to a client so the policy has one home. | | `active` | `boolean` \| `null` | — | Whether this market is currently tradable — CCXT's `active` (ENG-14839). Live state, unlike everything else on this schema: it moves with the market's lifecycle, and a client that cannot see it will route orders at a halted market. Exactly the negation of the engine's own admission gate: `false` for `listed`, `halted`, `settling` and `delisted`, `true` for `active`, `restricted` and `reduce_only`. `reduce_only` reads `true` because the market still admits position-reducing orders and liquidations. **Lossy on purpose — read `lifecycle` when the distinction matters.** `false` cannot tell an orderly wind-down from an incident halt from a terminal delisting. `null` only if the engine holds no lifecycle for a market it is otherwise serving, which its own bookkeeping makes unreachable. Nullable rather than defaulted because a fabricated `true` routes orders at a halted market. | | `lifecycle` | `string` \| `null` | — | The market's full lifecycle state (ENG-14839) — the same seven-value vocabulary as `MarketStatus.status`, and the state `active` above is a reading of. A Nexus extension; CCXT has no counterpart. Served alongside `active` rather than instead of it because the two have different consumers: a CCXT client wants the boolean, and a consumer that publishes market status needs the state. `null` for the same unreachable case as `active`. | | `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` | — | — | | `max_open_interest_notional` | [`Decimal`](#decimal) | — | Static one-sided open-interest cap in quote notional; `null` when the market sets none. Mutable on a running venue. This is the value an operator sets and changes; the bound an order is actually refused against is the minimum of this and the market's dynamic underlying terms, which can only tighten it. The two coincide on every market listed today. Distinct from `max_open_interest`, an independent cap denominated in base quantity that this endpoint also returns but this schema does not yet declare — they are two separate bounds, not two spellings of one. | | `price_band_bps` | `integer` | — | Order-vs-mark price collar, in basis points either side of the mark. A limit price further from the mark than this is refused at admission; liquidation orders are exempt. Mutable on a running venue. Always present and always in (0, 5000] - a market with no collar is not expressible. | | `contractSize` | [`Decimal`](#decimal) | — | Base-asset quantity one contract represents, as a decimal string. Named `contract_size` until ENG-13528 renamed it to CCXT's `contractSize`. `"1"` on every market listed today — every market is linear, and the engine's own notional math (`size × price`, with no multiplier term) is only consistent with `1`. Published rather than assumed so a client reading a position's contract count does not have to hardcode the venue's answer. **Not `lot_size`.** That is order granularity — the increment a size must be a multiple of. This is the multiplier. Conflating them misreports position size on any market where they differ. | ## MarketCumulativeVolume One market's cumulative traded notional. | Field | Type | Required | Description | | ------------------------- | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `market_id` | `string` | Yes | Market identifier, e.g. `BTC-USDX-PERP`. | | `cumulative_volume_quote` | [`Decimal`](#decimal) | Yes | Cumulative traded notional in quote (USDX) for this market, as a decimal string. | | `coverage_start_ms` | [`TimestampMs`](#timestampms) | No | Engine timestamp of the first fill folded into this market's total. **Omitted when unknown** — nothing has traded on this market since the indexer started. Absence means unknown; never read it as zero or as the epoch. | ## MarketOpenInterest One market's open interest. The two sides are reported separately and are never pre-summed; see the `gross_oi_two_sided_quote` field for the summed form and why it is named that way. | Field | Type | Required | Description | | -------------------------- | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `market_id` | `string` | Yes | Market identifier, e.g. `BTC-USDX-PERP`. Every listed market gets an entry, carrying `"0"` on both sides when nothing is open, so "no open interest" is distinguishable from "market unknown". Two deliberate exceptions: a delisted market appears only while it still carries an open position, and a market whose own base sum overflowed `Decimal` gets no row at all — the only value available for it is a truncated partial sum, and the base fields are mandatory, so it is named in the venue-level `quote_error` instead. | | `long_oi_base` | [`Decimal`](#decimal) | Yes | Sum of the positive position sizes in this market, in BASE units. Always present, `"0"` when nothing is open. Not summable across markets. | | `short_oi_base` | [`Decimal`](#decimal) | Yes | Sum of the ABSOLUTE values of the negative position sizes, in BASE units — positive, like `long_oi_base`. The side is named by the field, not carried in the sign. Equals `long_oi_base` on a matched book. | | `long_oi_quote` | [`Decimal`](#decimal) | No | `long_oi_base` priced at `mark_price`, in quote (USDX). **Omitted when the market could not be priced** — see `quote_error`. Absence is never zero. One exception, and it is what stops an empty market from withholding the venue figures: when `long_oi_base` and `short_oi_base` are both `"0"` the notional is exactly zero at any mark, so the row carries `"0"` here AND a `quote_error` naming the mark problem — the number is known, the price is not. | | `short_oi_quote` | [`Decimal`](#decimal) | No | `short_oi_base` priced at `mark_price`, in quote (USDX). Present and omitted under exactly the same conditions as `long_oi_quote` — both sides price off the one mark, so they are never partially available. | | `gross_oi_two_sided_quote` | [`Decimal`](#decimal) | No | `long_oi_quote + short_oi_quote`, in quote (USDX). Named `gross` and `two_sided` so it cannot be mistaken for the one-sided figure — caption `long_oi_quote` or `short_oi_quote`, not this. **Reconciling with the BFF, which is not this field:** the BFF's per-market `open_interest` on `GET /market-stats` relays `/admin/risk-summary`, which sums raw position sizes and never multiplies by a mark, so it is in BASE units. Its analogue here is `long_oi_base + short_oi_base`. This field is that same quantity priced into quote notional, which the BFF does not publish. | | `mark_price` | [`Decimal`](#decimal) | No | The mark the quote figures were computed FROM. Two rows carry no `mark_price`: a market with nothing open whose mark was absent or stale prices to zero without consulting one, and a market whose notional overflowed did consult a mark but has no figures to attach it to — that row names the mark inside `quote_error` instead. The rule, checkable from fields that are always present: quote figures are present when `mark_price` is present, OR when `long_oi_base` and `short_oi_base` are both `"0"`. | | `mark_price_as_of_ms` | [`TimestampMs`](#timestampms) | No | When that mark was last refreshed, on the INDEXER's clock — the same clock as `as_of_ms`, so the two are directly comparable. Present exactly when `mark_price` is. | | `quote_error` | — | No | Why this market could not be priced: no mark has been mirrored yet, the mark is stale (the message carries its measured age and the limit), or the notional overflowed. Omitted when pricing succeeded. **It does not mean the quote figures are missing** — a market with nothing open carries this AND quote figures of `"0"`. Branch on the quote fields to decide whether a row has numbers; read this to learn what is wrong with the market's mark. One field rather than one per side, because both sides price off the same mark. | ## 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 lifecycle status: the state, and the halt detail that belongs to it. The full seven-state vocabulary was declared in v0.9.0 (ENG-10445) and is fully produced since ENG-13954. | Field | Type | Required | Description | | ----------------- | --------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `market_id` | `string` | — | — | | `status` | `string` — one of `listed` \| `active` \| `halted` \| `restricted` \| `reduce_only` \| `settling` \| `delisted` | — | The market's lifecycle state. All seven are produced (ENG-13954): the indexer derives this from the market's own lifecycle record, which every transition writes — including the halt. It no longer derives it from the halt bit, which could only answer 'active' or 'halted' and so reported an orderly settling market, with its book cancelled and its positions force-settling at a pre-committed TWAP, as 'active'. Read `halt_reason` alongside 'halted'. | | `halt_reason` | `string` \| `null` | — | Why the market is halted; `null` unless `status` is 'halted'. A free-form identifier rather than an enum, on purpose: the reason set is closed engine-side and widening it is a coordinated engine+indexer deploy, so pinning a copy of it here would be a second list to keep in step (ENG-13473). Branch on the values you know and treat an unrecognised one as 'halted, reason unfamiliar'. It distinguishes a deliberate operator halt from a fail-closed one — an exhausted ADL pool, an uncovered system loss, a tripped max-move breaker, a state divergence — which before ENG-12787 shared one value and could not be told apart. | | `halted_at` | `integer` \| `null` | — | — | | `adl_event_count` | `integer` | — | — | ## MarketSummary A market's live trading state: last trade price, traded volume, trade count, and lifecycle status with its halt detail. Two fields are easy to misread and say so themselves. `last_trade_price` is what the market last traded at, **not** the mark the engine derives for margin and liquidations. And `volume_24h` is not a 24-hour window despite the name — read that field's own description before charting it. | 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` | — | Traded notional in quote (USDX). **This is not a 24h window.** `MarketSummary.volume_24h` and `Ticker.quoteVolume` are the SAME accumulator under a misleading name: nothing decays either of them. Read `GET /stats/volume` when you want the cumulative figure stated honestly, with the coverage start that says what it is cumulative since. This field is a JSON number produced by a lossy `f64` conversion; `/stats/volume` carries the same quantity as an exact decimal string. | | `trade_count` | `integer` | — | — | | `status` | `string` — one of `listed` \| `active` \| `halted` \| `restricted` \| `reduce_only` \| `settling` \| `delisted` | — | The market's lifecycle state. All seven are produced (ENG-13954): the indexer derives this from the market's own lifecycle record, which every transition writes — including the halt. It no longer derives it from the halt bit, which could only answer 'active' or 'halted' and so reported an orderly settling market, with its book cancelled and its positions force-settling at a pre-committed TWAP, as 'active'. Read `halt_reason` alongside 'halted'. | | `halt_reason` | `string` \| `null` | — | Why the market is halted; `null` unless `status` is 'halted'. A free-form identifier rather than an enum, on purpose: the reason set is closed engine-side and widening it is a coordinated engine+indexer deploy, so pinning a copy of it here would be a second list to keep in step (ENG-13473). Branch on the values you know and treat an unrecognised one as 'halted, reason unfamiliar'. It distinguishes a deliberate operator halt from a fail-closed one — an exhausted ADL pool, an uncovered system loss, a tripped max-move breaker, a state divergence — which before ENG-12787 shared one value and could not be told apart. | | `halted_at` | `integer` \| `null` | — | Unix ms timestamp when market was halted | | `adl_event_count` | `integer` | — | Cumulative ADL settlement events for this market | ## OpenInterest Open interest, venue total and per market, with the long and short sides reported separately. Aggregate only — it carries no account id, address, or per-account position by construction. Venue figures are quote-only because base units do not add across markets. | Field | Type | Required | Description | | -------------------------- | ---------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `as_of_ms` | [`TimestampMs`](#timestampms) | No | The last event this indexer ingested, on its OWN clock — the freshness of the fold as a whole, and what tells a fresh snapshot from a stalled one. **Omitted before the first event.** It is NOT the last time open interest changed: a venue where nothing traded for an hour still advances this, deliberately, because a per-position timestamp would report a quiet market as stale. | | `long_oi_quote` | [`Decimal`](#decimal) | No | Venue-wide long open interest in quote (USDX) — the sum of every market's `long_oi_quote`. **This is the field to caption.** Omitted when a market carries open interest this venue could not total, and also when the venue fold itself overflows `Decimal`; `quote_error` says which. Whenever it IS present every row carries its own `long_oi_quote`, so summing the breakdown reproduces this number exactly and the total can be audited in one pass. | | `short_oi_quote` | [`Decimal`](#decimal) | No | Venue-wide short open interest in quote (USDX). Equal to `long_oi_quote` by construction on a matched book; a persistent difference means the projection is desynced from the engine. | | `gross_oi_two_sided_quote` | [`Decimal`](#decimal) | No | Venue-wide `long + short` in quote (USDX) — twice the one-sided figure, named so it cannot be mistaken for the one-sided total. **There is deliberately no analogue of the BFF's `total_open_interest`:** that figure sums per-market BASE totals across markets, and base units do not add across markets, so this contract refuses to publish the quantity rather than publish a number with no unit. | | `quote_error` | — | No | Why the venue totals are absent — which markets carrying open interest could not be priced, or an overflow. Omitted when the totals are present. A partial venue total is never presented as complete: one market holding open interest at an unknown price withholds all three venue figures. A market with NOTHING open never appears here even when its own mark is missing — it cannot make a total partial, and its `quote_error` stays on its own row. | | `markets` | array of [`MarketOpenInterest`](#marketopeninterest) | Yes | Per-market breakdown, ascending by `market_id` so two scrapes are directly comparable. | | `mark_price_source` | `string` | Yes | What the quote notional was priced at, in prose. Part of the contract because a notional figure without its price source is not auditable. | | `network` | `string` | Yes | The chain network THIS indexer serves, taken from its required `auth.network` configuration (ENG-6443) rather than asserted by the handler. Gate on this rather than on the hostname you happened to fetch: the route lives per environment, so a URL change that nobody remembers to reflect in a downstream config would otherwise relabel the figure silently. Known values: `mainnet` (real funds), `testnet` (play funds), `local`. Deliberately an open string rather than an enum, matching `NetworkTarget.network` and `Metadata.network`, so a network added later cannot break deserialization — but treat an identifier you do not recognize as **real funds** rather than assuming play funds. `local` and `testnet` are distinct values and both report `testnet: true` — synthetic funds either way — so this is the only field that tells a local instance apart from the public testnet. | | `testnet` | `boolean` | Yes | `true` on every network whose funds are not real — the boolean reading of `network`. Kept beside it so consumers written before ENG-12796 keep working; `network` is the more precise field and the one to prefer. It was a hardcoded `true` until ENG-12796. | | `note` | `string` | Yes | Human-readable disclaimer, and the one-sided-versus-gross warning restated in prose. | ## Order An order and its lifecycle, as the read endpoints return it. Every placement option is echoed back, so this schema is also the record of how an order was placed: `postOnly`, `reduceOnly`, `stp`, `max_slippage_bps`, `triggerPrice`, the trailing anchor and offset, and the `clientOrderId` the caller supplied. Field names follow CCXT's unified vocabulary wherever CCXT defines one and stay `snake_case` for the Nexus extensions it does not — the same rule `Trade` follows (ENG-13314). Money remains a decimal string rather than becoming a JSON number (EDR-012), so unlike `Trade` this schema pairs camelCase keys with decimal-string values. `POST /orders` still accepts the request vocabulary (`market_id`, `quantity`, `client_id`) and returns this one — the asymmetry is deliberate and is ENG-13524's to settle. Quantities are three figures: `amount` is the total the order was placed for, `filled` what has executed, and `remaining` their difference — served by the venue rather than left to the caller, because these are decimal strings and the subtraction is where a client loses precision (ENG-13272). All three survive an amend, which replaces the order rather than mutating it. The four fill aggregates — `average`, `cost`, `fee` and `lastTradeTimestamp` — are `null` together when the venue cannot compute them, with `fill_totals_error` carrying the reason. They are not per-fill detail: the individual executions are on `/fills`, and on `OrderResponse` at placement time. | Field | Type | Required | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | — | — | | `symbol` | `string` | — | — | | `account_id` | `string` | — | — | | `side` | `string` — one of `Buy` \| `Sell` | — | — | | `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. | | `stp` | `string` \| `null` | — | The self-trade prevention mode the order was placed with, echoed back (see the `OrderRequest.stp` placement field for what each mode does). `null` for an order placed without one, which is the default and means self-matching was allowed. One of `CancelNewest`, `CancelOldest` or `DecrementAndCancel`. Deliberately not a closed enum here, for the same reason as `cancellation_reason`: the mode set has changed before (D-026 supersedes D-014) and a mode added later must not break a client pinned to an older spec tag. `OrderRequest.stp` does enumerate the modes, because there the value is one you supply and the server validates it. | | `max_slippage_bps` | `integer` \| `null` | — | Slippage cap in basis points, echoed for orders placed with one (see the `OrderRequest.max_slippage_bps` placement field); null for orders placed without a cap. | | `price` | [`Decimal`](#decimal) | — | The order's limit price, or null for an order type that has none. CCXT defines `price` as the limit price, so ENG-13314 renamed `limit_price` to it. This is NOT the `price` that ENG-6776 removed from this schema. That one was a phantom — documented, and emitted by neither producer, so a client branching on it got `undefined`. This property is the value the response has carried all along, now under CCXT's name for it. | | `stopPrice` | [`Decimal`](#decimal) | — | Stop price for a stop order, null otherwise. | | `triggerPrice` | [`Decimal`](#decimal) | — | The price that armed a triggered order, null for order types that are not triggered. | | `stopLossPrice` | [`Decimal`](#decimal) | — | The trigger price of a stop-loss order — CCXT's `stopLossPrice`. Set only on the stop family (`StopLimit`, `StopMarket`), where it restates the order's own `triggerPrice` under CCXT's name; null on every other order type. Nexus models a bracket's stop loss as its own reduce-only child order, and records no parent→child link, so this is an order stating its OWN threshold — which is also CCXT's definition of the field. A parent order does not report its bracket's price here. Trailing types are deliberately null: their threshold is `trailing_anchor` offset by `trailing_offset_bps`, not a fixed price, so a value here would state a number the engine does not use. DOES NOT SURVIVE THE FIRE. This field is keyed on `type`, and the venue rewrites `type` when the trigger fires (`StopMarket` becomes `Market`, `StopLimit` becomes `Limit`) while retaining `triggerPrice`. The same order therefore reports a price here while it is resting and `null` once it has fired, with `triggerPrice` unchanged throughout. Reconcile a stop across its whole life on `triggerPrice`, not on this field. | | `takeProfitPrice` | [`Decimal`](#decimal) | — | The trigger price of a take-profit order — CCXT's `takeProfitPrice`. Set only on the take-profit family (`TakeProfitLimit`, `TakeProfitMarket`), where it restates the order's own `triggerPrice` under CCXT's name; null on every other order type. The mirror of `stopLossPrice`, and null under the same conditions — see that field for why a bracket parent does not report its child's price, why trailing types state nothing, and why a FIRED take profit reports null here while keeping its `triggerPrice`. | | `trailing_anchor` | [`Decimal`](#decimal) | — | The extreme price a trailing order is measured from, null for non-trailing orders. | | `trailing_offset_bps` | `integer` \| `null` | — | Trailing distance in basis points for a trailing order; null otherwise. Echoed from placement, like `max_slippage_bps`. | | `reduceOnly` | `boolean` | — | Whether the order may only reduce an existing position, echoed from placement (`OrderRequest.reduce_only`). Read this rather than inferring it. The field was in every `GET /orders` response before ENG-6776 documented it — the indexer serializes the shared `Order` type verbatim — but absent from this schema, so a client needing it was guessing from order type and position side instead of reading the flag the venue recorded. | | `postOnly` | `boolean` | — | Whether the order was placed post-only: cancelled rather than executed if it would have taken liquidity. | | `is_liquidation` | `boolean` | — | Whether the liquidation engine created this order rather than the account. Liquidation fills are fee-exempt on both legs (ADR-0004), which is why a `Fill.fee` of "0" against such an order is a real zero and not an unstated fee. | | `clientOrderId` | `string` \| `null` | — | The client-supplied identifier for the order, echoed back; null when placement supplied none. | | `amount` | [`Decimal`](#decimal) | — | Total quantity the order was placed for, fills included. What is still executable is `remaining`, which the venue serves rather than making the caller subtract. An amend preserves it unless the amend supplies a new `size`. | | `filled` | [`Decimal`](#decimal) | — | Quantity executed so far, out of `amount`. Carried across an amend, so on a replacement it still counts every fill of the order it descends from. | | `remaining` | [`Decimal`](#decimal) | — | Quantity not yet executed — `amount - filled` — stated by the venue rather than re-derived by the caller. CCXT's unified `remaining`. Derivable, and served natively anyway (ENG-13272). Quantities here are decimal strings (EDR-012), so a caller subtracting them in JavaScript converts through a float first and can land a value that is wrong in the last places — which is what consumers do today. The engine already holds this figure exactly, so the venue reports it and the subtraction happens once, in decimal, rather than once per client. It is the arithmetic difference at all times, NOT an assertion that the quantity is still working. A cancelled, expired or rejected order reports the quantity that never executed, not a quantity still on the book; `status` is what distinguishes those, and a client sizing a replacement order should read both. `0` on a fully filled order. Carried across an amend on the same terms as its two operands: `PATCH /orders/{order_id}` preserves `amount` unless the amend supplies a new `size`, and carries `filled` across, so the difference stays consistent with the pair on the same response. Unlike the four fill aggregates it is never `null` and has no `fill_totals_error` case — it needs no fill history to compute, only the order's own two quantities. | | `status` | `string` — one of `Open` \| `PartiallyFilled` \| `Filled` \| `Cancelled` \| `Expired` \| `Rejected` \| `Triggered` | — | Lifecycle state. `Triggered` is a transient engine state stamped on a stop/take-profit/trailing order at the moment it fires, before the resulting order is submitted; no client-facing response is expected to carry it, because every submit outcome overwrites it (`Open`/`PartiallyFilled` when the converted order rests, `Filled`, `Cancelled`, or `Rejected`). It is listed because the wire type can hold it, so a consumer that rejects unknown values would fail on it rather than degrade. Treat this set as growable and prefer tolerating an unrecognised status to hard-failing. | | `cancellation_reason` | — | — | Why the order reached a terminal `Cancelled` or `Rejected` status. `null` for every other status, and for a terminal order the engine recorded no cause for. The key is always present. **Two wire shapes.** The engine's reason type is an externally tagged enum, so every cause except self-trade prevention is a bare string, while self-trade prevention is a single-key object naming the mode that fired: `{"Stp": "CancelNewest"}`. Branch on the JSON type before reading the value. The string form is one of `User` (an explicit cancel or cancel-all), `SlippageCap` (a market order's running fill VWAP left the `max_slippage_bps` band — see that field), `Liquidation` (cancelled ahead of a liquidation, or the unfilled remainder of one), `Expired` (an IOC, FOK or market remainder that cannot rest on the book), `MarketHalt`, `AmendReplace` (carried on the *original* order of an atomic cancel-replace via `PATCH /orders/{order_id}`), `InsufficientLiquidity` (a stop, stop-limit or trailing stop fired into an empty opposite side), `BracketClosed` or `BracketFlipped` (a bracket child whose parent position closed to zero or flipped sign), or `PriceBandExceeded` (the order-vs-mark price-band collar rejected it). The object form's only key today is `Stp`, whose value is `CancelNewest`, `CancelOldest` or `DecrementAndCancel`. **Treat the value as open.** Causes are added as the engine gains them, and this is not a closed enum: match the ones you handle and surface anything else verbatim rather than failing to parse. A client pinned to an older spec tag will meet causes it does not know. `GET /orders/history` reports the same causes in a **different encoding** — `OrderHistoryEntry.cancellation_reason` is always a string and renders the self-trade case as `Stp(CancelNewest)`, not as an object. Do not compare values across the two surfaces. | | `timeInForce` | `string` | — | — | | `timestamp` | [`TimestampMs`](#timestampms) | — | When the order was created, in epoch milliseconds. Named `created_at` until ENG-13314 renamed it to CCXT's `timestamp`. `datetime` beside it renders the same instant as a string. | | `datetime` | `string` | — | `timestamp` as an ISO 8601 string in UTC, to millisecond precision. Derived from that same value rather than recorded separately, so the two cannot describe different instants. CCXT declares both; read whichever suits the client. | | `lastUpdateTimestamp` | [`TimestampMs`](#timestampms) | — | When the order was last modified, in epoch milliseconds. Named `updated_at` until ENG-13314 renamed it to CCXT's `lastUpdateTimestamp`. | | `average` | [`Decimal`](#decimal) | — | Volume-weighted average price of this order's fills, as a decimal string. `null` when the order has not filled (`fill_totals_error` is then also `null` — nothing executed is an answer), or when the totals cannot be stated — see `fill_totals_error`. | | `cost` | [`Decimal`](#decimal) | — | Total quote value executed on this order (Σ price × size), as a decimal string. Same availability rule as `average`. | | `fee` | [`Decimal`](#decimal) | — | Total fee for this order as a signed decimal string: positive is a charge, negative a net maker rebate. `null` when the totals are unavailable, **and also when they are available but a contributing fill stated no fee** — a total is a claim about every fill, so one unstated leg makes the total unknown rather than smaller. Absent is never zero. `POST /orders` returns `null` here even alongside a populated `average`: that response is built from the match result, which carries no fee attribution. | | `lastTradeTimestamp` | [`TimestampMs`](#timestampms) | — | Timestamp of this order's most recent fill, in epoch milliseconds. Same availability rule as `average`. | | `fill_totals_error` | `string` \| `null` | — | Machine-readable reason `average` / `cost` / `fee` / `lastTradeTimestamp` are `null`, or `null` when they are populated **or** when the order simply has not filled. One channel for all four because they are one aggregate with one cause. `fills_retention_exceeded` — a fill of this order has aged out of the retained history, so any total would be a partial sum. A partial average is a real-looking price with nothing marking it wrong, so it is withheld. `fill_history_predates_amend` — the retained fills fall short of this order's `filled`, on a response for an order id the venue minted answering this same request. `PATCH /orders/{order_id}` is an atomic cancel-replace: it mints a new order id and carries `filled` across, while fills stay attributed to the id that executed them, so the replacement counts executions it has no history of and the totals would describe only the post-amend portion. Served only where the amend is the sole possible cause — a read route reports `fill_history_short_of_filled_qty` for the same shortfall. `fill_history_short_of_filled_qty` — the retained fills for this order id are complete as far as the retention window can tell, and still sum to less than its `filled`. Two causes produce this and they cannot be told apart here: the order descends from an amend (see `fill_history_predates_amend`), or its per-order aggregate was evicted from a bounded map and rebuilt from later fills alone, which is a retention drop the window test cannot see. The reason states the shortfall rather than naming a cause it would be guessing at, because the two have different remedies. As with every value here no partial total is served: the four fields stay `null`. `fill_history_not_retained` — the producer answering this request keeps no per-order fill history, so the totals are not derivable here even though the order has executed. Distinct from `fills_retention_exceeded`, which means a retained history dropped a fill. Reaches a client on the responses relayed from the matching engine without a fill-history join: `DELETE /orders/{order_id}`, `DELETE /orders`, and the duplicate-`client_id` replay branches of `POST /orders` and `POST /orders/batch`, which return an order the request did not create. `PATCH /orders/{order_id}` is enriched before it leaves the venue and reports `fill_history_predates_amend` instead. `filled_qty_lags_fill_history` — the retained fills for this order id sum to MORE than its `filled`, so the totals would answer for more executions than the order itself admits to. Neither a shortfall nor a retention problem: the venue folds a match's fill and the taker order's own `filled` from two separate events, so a read landing between them sees a fill history ahead of the order's projection. It closes itself within one event — retry the read. The four fields stay `null` until then, and a `filled` of `0` carrying this cause means the same thing rather than an order that has not executed: fills are known for the id, the order has simply not caught up yet. | ## OrderBook CCXT-compatible order book. Bids/asks are \[price, amount] arrays. | Field | Type | Required | Description | | ----------- | ----------------------------- | -------- | ----------- | | `symbol` | `string` | — | — | | `bids` | array of array of — | — | — | | `asks` | array of array of — | — | — | | `timestamp` | [`TimestampMs`](#timestampms) | — | — | | `datetime` | `string` | — | — | | `nonce` | `integer` | — | — | ## OrderHistoryEntry A terminal-status order (filled / cancelled / rejected / expired). Badged `x-ccxt-method: fetchOrders`, so it answers CCXT's unified `Order` vocabulary. It did not until ENG-14207: this is a separate indexer projection that the ENG-13314 rename never reached, so it went on serving `market_id` / `order_type` / `filled_qty` / `size` / `created_at_ms` / `completed_at_ms` while every other `Order`-returning method served the unified names. The fields CCXT has no counterpart for keep ours — `cancellation_reason` is a Nexus extension, and its encoding on this route differs from `Order`'s by design (see below). As of ENG-14207 it serves the same unified vocabulary `Order` does, field for field, with two deliberate differences. `cancellation_reason` is a Nexus extension whose encoding on this route is a string (see below), not the object `Order` uses. And `timeInForce`, `postOnly`, `reduceOnly` are nullable here where `Order` states them unconditionally, because an entry recorded before ENG-14207 did not store them and `null` is the honest answer for one. | Field | Type | Required | Description | | --------------------- | -------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | — | — | | `symbol` | `string` | — | The market this order was placed on. Named `market_id` until ENG-14207 renamed it to CCXT's unified name, which `Order.symbol` has carried since ENG-13314. | | `side` | `string` — one of `Buy` \| `Sell` | — | Served as `buy` / `sell` until ENG-14207. The casing now agrees with `Order.side`: the two order surfaces used to disagree with each other, so a client reading both had to branch on which one answered. The enum is closed and the venue holds to it. The projection stores this field as text in its own lowercase vocabulary (`buy` / `sell`) and the venue translates on the way out; a stored value it cannot translate is reported as a server error rather than served, because clients compare this field literally. `type` on this same schema declares no enum for the opposite reason — an unrecognised value there crosses verbatim. | | `type` | `string` | — | `Limit` \| `Market` \| `StopLimit` \| `StopMarket` \| `TakeProfitLimit` \| `TakeProfitMarket` \| `TrailingStop` \| `TrailingLimit` — the same spelling `Order.type` serves. Named `order_type` until ENG-14207, and its VALUES moved in that same change. They were the engine enum's derived `Debug` output lowercased, so `StopLimit` reached the wire as `stoplimit`: that matched neither the `stop_*` this description used to claim nor any consumer, and the six multi-word variants resolved to nothing. | | `price` | [`Decimal`](#decimal) | — | Limit price; null for market orders. | | `amount` | [`Decimal`](#decimal) | — | Total quantity the order was placed for, fills included. Named `size` until ENG-14207 renamed it to CCXT's unified name, which `Order.amount` has carried since ENG-13314. | | `filled` | [`Decimal`](#decimal) | — | Quantity executed, out of `amount`. Named `filled_qty` until ENG-14207 renamed it to CCXT's unified name, which `Order.filled` has carried since ENG-13314. | | `remaining` | [`Decimal`](#decimal) | — | Quantity never executed — `amount - filled` — CCXT's unified `remaining`, the same field `Order.remaining` carries (ENG-13272). Served here as well because `fetchOrders` reads this projection rather than `Order`, so a CCXT client would otherwise see the field on seven methods and not on the eighth. Every order in this projection is terminal, so this is the quantity that never executed rather than one still working: `0` on a `Filled` order, and the unexecuted remainder on a `Cancelled`, `Expired` or `Rejected` one. **Nullable here, and not on `Order`.** This projection stores `amount` and `filled` unvalidated, so either may be a value the venue cannot read back as a number; `Order` holds both as typed quantities and can always subtract them. `null` means exactly that — an operand could not be parsed, so no difference can be stated. It is deliberately not `0`: zero is a real answer meaning the order filled completely, and serving it for an unreadable record would describe that record as a completed order. Read `null` as "unknown", never as "nothing left". | | `status` | `string` — one of `Filled` \| `Cancelled` \| `Rejected` \| `Expired` | — | — | | `cancellation_reason` | `string` \| `null` | — | Why the order was cancelled or rejected; `null` for any other status. Always a **string** on this route, including for self-trade prevention, which renders as `Stp(CancelNewest)` — this surface stringifies the engine's reason type, so the encoding differs from `Order.cancellation_reason`, where that same cause is the object `{"Stp": "CancelNewest"}`. The cause set is otherwise identical, and equally open — see `Order.cancellation_reason` for the full list. | | `timestamp` | [`TimestampMs`](#timestampms) | — | When the order was created, in epoch milliseconds. Named `created_at_ms` until ENG-14207 renamed it to CCXT's unified name, which `Order.timestamp` has carried since ENG-13314. | | `datetime` | `string` | — | `timestamp` as an ISO 8601 string in UTC, to millisecond precision. Derived from that same value rather than recorded separately, exactly as `Order.datetime` is. Added by ENG-14207. | | `lastUpdateTimestamp` | [`TimestampMs`](#timestampms) | — | When the order reached its terminal status, in epoch milliseconds. Named `completed_at_ms` until ENG-14207 renamed it to CCXT's unified name, which `Order.lastUpdateTimestamp` has carried since ENG-13314. | | `clientOrderId` | `string` \| `null` | — | The client-supplied identifier for the order, echoed back; null when placement supplied none. Added to this schema by ENG-14207, and `null` on an entry recorded before that change — the projection did not store the value, which is a different fact from placement not supplying one. | | `timeInForce` | `string` \| `null` | — | `GTC` \| `IOC` \| `FOK` \| `PostOnly` — the same spelling `Order.timeInForce` serves. Added by ENG-14207. Nullable here where `Order.timeInForce` is not: an entry recorded before that change did not store one, and `null` says so rather than asserting the `GTC` a consumer used to assume. | | `postOnly` | `boolean` \| `null` | — | Whether the order was placed post-only: cancelled rather than executed if it would have taken liquidity. Added by ENG-14207. Nullable here where `Order.postOnly` is not, for the reason `timeInForce` gives: `false` on an entry that never recorded the flag would be a fabricated answer indistinguishable from a real one. | | `reduceOnly` | `boolean` \| `null` | — | Whether the order may only reduce an existing position, echoed from placement (`OrderRequest.reduce_only`). Added by ENG-14207. Nullable here where `Order.reduceOnly` is not — same reason as `postOnly`. | | `stopPrice` | [`Decimal`](#decimal) | — | Stop price for a stop order, null otherwise. Added to this schema by ENG-14207; `null` on an entry recorded before that change. | | `triggerPrice` | [`Decimal`](#decimal) | — | The price that armed a triggered order, null for order types that are not triggered. Added to this schema by ENG-14207; `null` on an entry recorded before that change. | | `stopLossPrice` | [`Decimal`](#decimal) | — | The trigger price of a stop-loss order — CCXT's `stopLossPrice`. Set only on the stop family (`StopLimit`, `StopMarket`), where it restates the order's own `triggerPrice` under CCXT's name; null on every other order type. Nexus models a bracket's stop loss as its own reduce-only child order, and records no parent→child link, so this is an order stating its OWN threshold — which is also CCXT's definition of the field. A parent order does not report its bracket's price here. Trailing types are deliberately null: their threshold is `trailing_anchor` offset by `trailing_offset_bps`, not a fixed price, so a value here would state a number the engine does not use. DOES NOT SURVIVE THE FIRE. This field is keyed on `type`, and the venue rewrites `type` when the trigger fires (`StopMarket` becomes `Market`, `StopLimit` becomes `Limit`) while retaining `triggerPrice`. The same order therefore reports a price here while it is resting and `null` once it has fired, with `triggerPrice` unchanged throughout. Reconcile a stop across its whole life on `triggerPrice`, not on this field. | | `takeProfitPrice` | [`Decimal`](#decimal) | — | The trigger price of a take-profit order — CCXT's `takeProfitPrice`. Set only on the take-profit family (`TakeProfitLimit`, `TakeProfitMarket`), where it restates the order's own `triggerPrice` under CCXT's name; null on every other order type. The mirror of `stopLossPrice`, and null under the same conditions — see that field for why a bracket parent does not report its child's price, why trailing types state nothing, and why a FIRED take profit reports null here while keeping its `triggerPrice`. | | `average` | [`Decimal`](#decimal) | — | Volume-weighted average price of this order's fills, as a decimal string. `null` when the order has not filled (`fill_totals_error` is then also `null` — nothing executed is an answer), or when the totals cannot be stated — see `fill_totals_error`. | | `cost` | [`Decimal`](#decimal) | — | Total quote value executed on this order (Σ price × size), as a decimal string. Same availability rule as `average`. | | `fee` | [`Decimal`](#decimal) | — | Total fee for this order as a signed decimal string: positive is a charge, negative a net maker rebate. `null` when the totals are unavailable, **and also when they are available but a contributing fill stated no fee** — a total is a claim about every fill, so one unstated leg makes the total unknown rather than smaller. Absent is never zero. `POST /orders` returns `null` here even alongside a populated `average`: that response is built from the match result, which carries no fee attribution. | | `lastTradeTimestamp` | [`TimestampMs`](#timestampms) | — | Timestamp of this order's most recent fill, in epoch milliseconds. Same availability rule as `average`. | | `fill_totals_error` | `string` \| `null` | — | Machine-readable reason `average` / `cost` / `fee` / `lastTradeTimestamp` are `null`, or `null` when they are populated **or** when the order simply has not filled. One channel for all four because they are one aggregate with one cause. `fills_retention_exceeded` — a fill of this order has aged out of the retained history, so any total would be a partial sum. A partial average is a real-looking price with nothing marking it wrong, so it is withheld. `fill_history_predates_amend` — the retained fills fall short of this order's `filled`, on a response for an order id the venue minted answering this same request. `PATCH /orders/{order_id}` is an atomic cancel-replace: it mints a new order id and carries `filled` across, while fills stay attributed to the id that executed them, so the replacement counts executions it has no history of and the totals would describe only the post-amend portion. Served only where the amend is the sole possible cause — a read route reports `fill_history_short_of_filled_qty` for the same shortfall. `fill_history_short_of_filled_qty` — the retained fills for this order id are complete as far as the retention window can tell, and still sum to less than its `filled`. Two causes produce this and they cannot be told apart here: the order descends from an amend (see `fill_history_predates_amend`), or its per-order aggregate was evicted from a bounded map and rebuilt from later fills alone, which is a retention drop the window test cannot see. The reason states the shortfall rather than naming a cause it would be guessing at, because the two have different remedies. As with every value here no partial total is served: the four fields stay `null`. `fill_history_not_retained` — the producer answering this request keeps no per-order fill history, so the totals are not derivable here even though the order has executed. Distinct from `fills_retention_exceeded`, which means a retained history dropped a fill. Reaches a client on the responses relayed from the matching engine without a fill-history join: `DELETE /orders/{order_id}`, `DELETE /orders`, and the duplicate-`client_id` replay branches of `POST /orders` and `POST /orders/batch`, which return an order the request did not create. `PATCH /orders/{order_id}` is enriched before it leaves the venue and reports `fill_history_predates_amend` instead. `filled_qty_lags_fill_history` — the retained fills for this order id sum to MORE than its `filled`, so the totals would answer for more executions than the order itself admits to. Neither a shortfall nor a retention problem: the venue folds a match's fill and the taker order's own `filled` from two separate events, so a read landing between them sees a fill history ahead of the order's projection. It closes itself within one event — retry the read. The four fields stay `null` until then, and a `filled` of `0` carrying this cause means the same thing rather than an order that has not executed: fills are known for the id, the order has simply not caught up yet. `filled_qty_unparseable` — this order's own `filled` could not be read as a decimal, so no comparison against the retained fills is possible and no total can be stated. Unique to this schema: `Order` carries `filled` as a value the venue has already parsed, while the order-history projection round-trips it through a checkpoint as text. A record reaching this cause is corrupt on the venue's side, not a retention or timing effect — retrying will not clear it. It is reported rather than folded into "did not execute", which is what four `null`s and a `null` error would otherwise have claimed about it. | ## 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` — one of `Buy` \| `Sell` | Yes | — | | `order_type` | `string` — one of `Limit` \| `Market` \| `StopLimit` \| `StopMarket` \| `TakeProfitLimit` \| `TakeProfitMarket` \| `TrailingStop` \| `TrailingLimit` | 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. | | `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` — one of `GTC` \| `IOC` \| `FOK` \| `PostOnly` | 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. | | `reduce_only` | `boolean` | No | — | | `stop_price` | [`Decimal`](#decimal) | 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. | | `trigger_price` | [`Decimal`](#decimal) | 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). | | `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. | | `stp` | `string` \| `null` | No | Opt-in self-trade prevention. Omit the field, or send `null`, to allow self-matching — that is the default and the industry-standard behaviour, and the engine will fill your order against your own resting order. Set a mode to have the engine intervene when a taker meets a maker on the same account instead. `CancelNewest` cancels the incoming taker and leaves the maker resting; the taker stops walking the book entirely, so remaining taker size beyond that maker is cancelled too. `CancelOldest` cancels the resting maker and lets the taker carry on against other accounts' makers. `DecrementAndCancel` reduces both sides by `min(taker_remaining, maker_size)` and cancels the smaller side, leaving the larger to continue at the reduced quantity. The check is applied **per encountered same-account maker**, not once at order entry, so a taker crossing several of your own makers is evaluated at each one. It sits in the shared matching path, so it applies to every order type rather than a subset. When a mode cancels an order, that order comes back with `cancellation_reason` set to the object `{"Stp": ""}` — see `Order.cancellation_reason`. | | `client_id` | `string` \| `null` | No | Client-supplied idempotency key for this order, opaque to the venue and scoped to your account: two accounts may use the same value independently. **Retrying a submit with a `client_id` you have already used does not place a second order.** A client cannot tell "the venue never received my order" from "it received it, accepted it, and the response was lost" — both look like a timeout — so a retry is the only safe response to one, and this is what makes retrying safe. The repeat is answered `200` with the order the first request created, rather than `201` with a new one. Submit the retry byte-identically; the venue answers with the order it already holds and does not compare the rest of the body against it. **Retention is bounded.** The venue remembers a limited number of recent keys per account, sized to cover a retry window rather than a session. A key reused long after that window is treated as new, so it is not a durable uniqueness constraint and must not be used as one — do not rely on it to prevent a duplicate hours later. An amend (`PATCH /orders/{order_id}`) carries the key to the replacement order, so a retry after an amend is answered with the replacement. Omit the field, or send `null`, to opt out; an empty string is treated as omitted. `POST /orders/batch` honours the key per entry, so a retried batch can mix replays of orders you already hold with genuinely new ones: a replayed entry comes back as a normal success row carrying the original order, subject to the same resting-only limit as above. Two entries in one batch sharing a key accept the first and refuse the second. | | `max_slippage_bps` | `integer` \| `null` | No | Server-enforced slippage cap in basis points (1 bp = 0.01%). Omit the field for no cap. When set, the engine captures the book mid-price `(best_bid + best_ask) / 2` once at submission and requires the order's running fill VWAP to stay inside `mid ± mid × bps / 10000` as it walks the book. Fills made before the cap binds stand; the fill that would push the VWAP outside the band is not made and the unfilled remainder is cancelled — the order comes back on the normal `201` with `status` `Cancelled` and `cancellation_reason` `SlippageCap`, not as an error. Because the reference is the mid captured server-side at submission and the bound is on the running VWAP rather than on the worst individual fill, this is a stricter guarantee than a marketable limit price derived client-side from a previously sampled reference price. Applies to the market family: `Market`, plus `StopMarket`, `TakeProfitMarket`, and `TrailingStop`, which carry the field through their conversion and have the cap applied when they fire as market orders. Accepted but ignored on `Limit`, `StopLimit`, `TakeProfitLimit`, and `TrailingLimit` — a limit order already fills at its limit price or better. Two edges worth knowing. A mid-price requires **both** sides of the book to be non-empty, so a capped order submitted while either side is empty is rejected with `InsufficientLiquidity` (a `400` on `POST /orders`, an `err` item on `POST /orders/batch`) — including when the empty side is the order's own and the order could otherwise have filled. And `0` does not mean "no cap": it collapses the band onto the mid exactly, so against any book with a non-zero spread the order cancels with zero fills. `POST /orders/preview` accepts the field but does not apply it — `expected_fill_vwap` always walks the full book. | ## OrderResponse What `POST /orders` returns: the accepted order and the executions that placement produced immediately. **`fills` is only populated here.** Fetching the same order afterwards returns a bare `Order`, which carries the aggregates but not the individual executions — so a client that discards this response cannot recover the fill detail from the order endpoints and must read `/fills` instead. Persist it at placement if you need it. | Field | Type | Required | Description | | ------- | ------------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `order` | [`Order`](#order) | — | — | | `fills` | array of [`ExecutionFill`](#executionfill) | — | The executions this placement produced, straight off the matching engine. These are `ExecutionFill`, NOT the account-projected `Fill` that `GET /fills` returns — different fields, and a `side` that means something different. See `ExecutionFill`. | ## 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. *This schema declares no properties in the contract.* ## OrderResultErr A rejected order in a batch result (outcome `err`). Mirrors the global error envelope. | Field | Type | Required | Description | | --------- | ----------------------- | -------- | ----------------------------- | | `outcome` | `string` — one of `err` | Yes | — | | `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` — one of `ok` | Yes | — | | `order` | [`Order`](#order) | Yes | — | | `fills` | array of [`ExecutionFill`](#executionfill) | No | Same engine-side executions as `OrderResponse.fills`. | ## OrdinaryTransferEnrollment | Field | Type | Required | Description | | --------- | -------- | -------- | ----------- | | `account` | `string` | Yes | — | | `domain` | `string` | Yes | — | ## OrdinaryTransferEnrollmentResponse | Field | Type | Required | Description | | ---------- | ------------------------- | -------- | ----------- | | `account` | `string` | Yes | — | | `domain` | `string` | Yes | — | | `enrolled` | `boolean` — one of `True` | Yes | — | ## OrdinaryTransferError | Field | Type | Required | Description | | --------- | -------- | -------- | ----------- | | `code` | `string` | Yes | — | | `message` | `string` | Yes | — | ## OrdinaryTransferHistory | Field | Type | Required | Description | | ------------- | -------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `transfers` | array of [`OrdinaryTransferReceipt`](#ordinarytransferreceipt) | Yes | — | | `next_cursor` | `string` \| `null` | Yes | Last returned transfer id, or null for an empty page. Pass as after; a final follow-up page may be empty. | | `balance` | `string` | Yes | Current collateral of the signed reader account, observed after the history lookup. This is an account-scoped read, not the counterparty balance or a historical receipt balance. | ## OrdinaryTransferReceipt | Field | Type | Required | Description | | -------------------- | ----------------------------- | -------- | ----------- | | `transfer_id` | `string` | Yes | — | | `status` | `string` — one of `committed` | Yes | — | | `asset` | `string` — one of `USDX` | Yes | — | | `source` | `string` | Yes | — | | `destination` | `string` | Yes | — | | `amount` | `string` | Yes | — | | `client_transfer_id` | `string` | Yes | — | | `domain` | `string` | Yes | — | | `committed_at_ms` | `integer` | Yes | — | ## OrdinaryTransferRequest | Field | Type | Required | Description | | -------------------- | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------- | | `source` | `string` | Yes | — | | `destination` | `string` | Yes | — | | `asset` | `string` — one of `USDX` | Yes | — | | `amount` | `string` | Yes | Positive USDX, at most six fractional digits and 18446744073709.551615. No rounding, signs, exponent or whitespace. | | `client_transfer_id` | `string` | Yes | Economic id scoped to the source. Never replace this id after an ambiguous response. | | `domain` | `string` | Yes | Deployment domain configured by the operator, for example prd-testnet. Signed inside the body. | ## 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. *This schema declares no properties in the contract.* ## 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 names follow CCXT's unified vocabulary wherever CCXT defines one and stay `snake_case` for the Nexus extensions it does not — the same rule `Order` and `Trade` follow (ENG-15117, which renamed thirteen fields and carried eight `_error` twins with them to `_error`). `size`, `roe`, `max_leverage` and `funding_paid` keep the venue's spelling: CCXT defines no counterpart for a position's base-asset quantity (its `contracts` is `size / contractSize`, a different number), for a bare return ratio (its `percentage` is per hundred), for a market's leverage ceiling, or for a paid-positive cumulative funding figure. **`GET /account` does not answer this schema.** That route relays the matching engine's own position response — a narrower object, under the engine's names, carrying `funding_accrued`, `fee_pnl` and `entry_pnl` which are absent here. A client reading both surfaces reads two vocabularies. `PositionPnl` (`GET /positions/pnl`) and `ClosedPosition` (`GET /positions/closed`) are likewise separate schemas that this rename did not reach. | Field | Type | Required | Description | | ------------------------ | ----------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `symbol` | `string` | — | — | | `side` | `string` — one of `Long` \| `Short` | — | — | | `size` | [`Decimal`](#decimal) | — | — | | `entryPrice` | [`Decimal`](#decimal) | — | — | | `markPrice` | [`Decimal`](#decimal) | — | The mark price this position's `unrealizedPnl`, `notional` and `initialMargin` were computed against. This is the real blended mark that margin and liquidations use — not the trade reference that `FundingSample.mark_price` carries under the same name. Mirrored from the engine's `GET /markets/{market_id}/mark-price` by the indexer's per-cycle poll, and treated as unavailable when it is absent OR staler than the freshness bound, so a frozen last-good mark is never served as live (ENG-5909). `null` when the mark is unavailable — see `markPrice_error`. It used to be served as the string `"0"` in that case, a sentinel a client could not tell apart from a genuine zero; the other mark-dependent fields on this object (`notional`, `initialMargin`, `roe`) already reported that absence as `null` + `*_error: "mark_price_unavailable"`, and this field now follows the same rule (ENG-13921). | | `markPrice_error` | `string` \| `null` | — | Machine-readable reason `markPrice` is `null` (`mark_price_unavailable`), or `null` when populated. | | `unrealizedPnl` | [`Decimal`](#decimal) | — | — | | `realizedPnl` | [`Decimal`](#decimal) | — | — | | `liquidationPrice` | [`Decimal`](#decimal) | — | Price at which the position is liquidated, as a decimal string. `null` when the venue has not computed one — see `liquidationPrice_error`. A zero is a real price and never a stand-in for absence: this field used to carry the string `"0"` to mean "not computed", which made a position that liquidates only at zero — i.e. effectively cannot be liquidated — indistinguishable from one whose liquidation price is simply unknown. | | `liquidationPrice_error` | `string` \| `null` | — | Machine-readable reason `liquidationPrice` is `null`. Absent, or `null`, when `liquidationPrice` is populated — the indexer omits the sibling rather than nulling it, and `/account` (relayed from the engine) does not carry it at all. On the indexer-served reads it is always `margin_state_not_mirrored`: liquidation price needs margin-module state the indexer does not mirror. | | `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 `initialMargin` — 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` | [`Decimal`](#decimal) | — | Position notional value (\|size\| × mark price), as a decimal string. `null` when the mark price is unavailable — see `notional_error`. | | `notional_error` | `string` \| `null` | — | Machine-readable reason `notional` is `null` (e.g. `mark_price_unavailable`), or `null` when populated. | | `roe` | [`Decimal`](#decimal) | — | Return on equity: `unrealizedPnl / initialMargin` (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. | | `initialMargin` | [`Decimal`](#decimal) | — | Initial-margin requirement held against this position (`notional × 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 `initialMargin_error`. | | `initialMargin_error` | `string` \| `null` | — | Machine-readable reason `initialMargin` 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. **The sign is not uniform across the API, and this field is the exception rather than the rule.** `paid-positive` is chosen here for parity with Hyperliquid's `cumFunding`. The sibling decomposition served at `GET /positions/pnl` reports the same cash flow as `funding_pnl` with the OPPOSITE sign — received-positive, so that it sums with the other P\&L components — and the service negates between the two. A client that reads both and assumes one convention will render one of them backwards, and because both are plausible numbers nothing will look wrong. Negate when moving a value between the two fields. | | `contractSize` | [`Decimal`](#decimal) | — | Base-asset quantity one contract represents, mirrored from the market's parameters — the same value `GET /markets` publishes. `"1"` on every market listed today. `null` while market parameters have not yet loaded — see `contractSize_error`. | | `contractSize_error` | `string` \| `null` | — | Machine-readable reason `contractSize` is `null` (`market_params_unavailable`), or `null` when populated. | | `lastPrice` | [`Decimal`](#decimal) | — | The market's last traded price, as a decimal string. `null` before the market's first fill — see `lastPrice_error`. **Distinct from `markPrice`,** which is oracle-derived and is what margin and liquidation are computed against. This is the last execution. They differ, and substituting one for the other is wrong in a way that is hard to notice. | | `lastPrice_error` | `string` \| `null` | — | Machine-readable reason `lastPrice` is `null` (`no_trades_yet`), or `null` when populated. | | `timestamp` | [`TimestampMs`](#timestampms) | — | When this position was opened, in epoch milliseconds. `null` when no engine position snapshot has been folded for it yet — see `timestamp_error`. **Distinct from `lastUpdateTimestamp`:** one is when the position began, the other when it was last written to. A position that has traded since opening has two different values here, and the open instant is the one that orders a position list by age. | | `timestamp_error` | `string` \| `null` | — | Machine-readable reason `timestamp` is `null` (`position_snapshot_not_seen`), or `null` when populated. | | `lastUpdateTimestamp` | [`TimestampMs`](#timestampms) | — | When this position was last written to, in epoch milliseconds. Always present — every path that creates or refreshes a position entry stamps it, so there is no absence to report and no companion `_error` field. | | `marginMode` | `string` \| `null` | — | Margin mode for this position. **Per-position, not per-account:** a market whose risk class forces isolated margin holds that mode while the same account's other positions may be cross. `null` when no engine position snapshot has been folded for it yet — see `marginMode_error`. | | `marginMode_error` | `string` \| `null` | — | Machine-readable reason `marginMode` is `null` (`position_snapshot_not_seen`), or `null` when populated. | | `collateral` | [`Decimal`](#decimal) | — | Margin allocated to this position specifically, as a decimal string. Meaningful only for an isolated position. `null` — with a reason in `collateral_error` — in three cases that are deliberately kept apart: a **cross** position has no per-position allocation at all because the account backs it (`cross_margin_no_allocation`); an **isolated** position may have none posted yet (`isolated_margin_not_allocated`); and a position with no folded snapshot has one we cannot state (`position_snapshot_not_seen`). The first is an answer, not a gap. | | `collateral_error` | `string` \| `null` | — | Machine-readable reason `collateral` is `null` (`cross_margin_no_allocation`, `isolated_margin_not_allocated`, or `position_snapshot_not_seen`), or `null` when populated. | ## PositionPnl One open position's P\&L, decomposed into the three components that sum to it. Served from indexer-local projections with no engine round-trip, which is why it is a separate operation rather than more fields on `Position` — `/positions` is polled hot and this is not on that path. **Signs are P\&L-relative throughout, and `funding_pnl` is therefore the NEGATION of `Position.funding_paid`.** Here, positive means the account gained: a funding settlement received is positive, a fee paid is negative. `Position.funding_paid` on `/positions` is paid-positive instead, for parity with Hyperliquid's `cumFunding`. A client that reads both and assumes one convention will render one backwards, and both renderings are plausible numbers, so nothing will look wrong. Negate when moving a value between them. | Field | Type | Required | Description | | -------------------- | ----------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `market_id` | `string` | Yes | The market this position is in. | | `side` | `string` — one of `Long` \| `Short` | Yes | Position direction. | | `size` | [`Decimal`](#decimal) | Yes | Position size in base units. | | `entry_pnl` | [`Decimal`](#decimal) | Yes | Price P\&L: `unrealized_pnl + realized_pnl`. The mark-vs-entry component plus the engine-mirrored cumulative realized figure. | | `unrealized_pnl` | [`Decimal`](#decimal) | Yes | The live mark-vs-average-entry component of `entry_pnl`. **`0` does not necessarily mean the position has no price P\&L.** It is computed from `(mark, avg_entry)` and falls back to `0` whenever either is absent — the mark withheld as stale (ENG-5909), or a position carrying no `avg_entry`. Both render as a flat `0` that is indistinguishable from a position trading exactly at entry. Check `mark` and `entry` on the same payload to tell the cases apart; `total_pnl_complete` will not, because it is set unconditionally. | | `realized_pnl` | [`Decimal`](#decimal) | Yes | Engine-mirrored cumulative realized P\&L for this position. | | `funding_pnl` | [`Decimal`](#decimal) | Yes | Sum of funding settlements for this `(account, market)`. **Received-positive** — the opposite sign to `Position.funding_paid`. Bounded by the funding ring buffer, so it spans retained history rather than all time. | | `fee_pnl` | [`Decimal`](#decimal) | Yes | Sum of fees for this `(account, market)`, expressed as P\&L: a fee paid **reduces** P\&L, so this is normally negative. Built from the engine's stamped per-fill `taker_fee` / `maker_rebate`, not re-derived from bps. Bounded by the fill ring buffer. | | `total_pnl` | [`Decimal`](#decimal) | Yes | `entry_pnl + funding_pnl + fee_pnl`. | | `total_pnl_complete` | `boolean` | Yes | True when all components were derivable, so `total_pnl` is a complete sum. **Always `true` in today's responses** — but because `pnl_decomposition_json` sets it unconditionally, NOT because completeness is checked. Do not read it as a guarantee. The gap is real and reachable: `unrealized_pnl` falls back to `0` when the mirrored mark is withheld as stale (ENG-5909 — `fresh_engine_mark_price` returns nothing past `MAX_MARK_AGE_MS`) or when the position has no `avg_entry`. In that state `total_pnl` is missing its price component while this flag still reports `true`. Prefer `mark` and `entry` on the same payload: if either is absent, treat `unrealized_pnl` and `total_pnl` as incomplete regardless of what this says. Retained as a boolean because a component could become conditionally unavailable again, and a client that already branches on it would then be correct rather than surprised. It is **not** a claim that each component spans all time: `funding_pnl` and `fee_pnl` are ring-bounded, and that retention caveat is a durable-history question rather than an availability one. | ## 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) | — | — | | `projected_post_trade_leverage` | [`Decimal`](#decimal) | — | — | | `expected_fill_vwap` | [`Decimal`](#decimal) | — | — | | `projected_fees` | [`Decimal`](#decimal) | — | — | ## RateLimitBucketStatus One rate-limit budget's state — the same three numbers, under the same names, as `RateLimitStatus`'s flat fields, so a bucket entry needs no second set of semantics. Not nullable: an entry exists only for a budget that meters the caller, so there is no unlimited case to represent — an `unlimited`-tier caller gets an empty `buckets` map instead. | Field | Type | Required | Description | | ------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `limit` | `integer` | Yes | Budget of **weight** per second for this bucket — not a count of requests, and also its burst capacity, so `remaining` never exceeds it. | | `remaining` | `integer` | Yes | Tokens currently in this bucket, in **unit-cost requests**: 10 means ten weight-1 requests, or two weighing 5. Divide by an operation's weight for how many of *that* call remain. `0` is what a `429` naming this bucket reports. | | `reset_at_ms` | `integer` | Yes | Unix timestamp in milliseconds when this bucket is whole again; `0` when it is already full. It refills continuously, so tokens are available before this time. | ## RateLimitStatus Rate-limit state per budget. The flat `tier`, `limit`, `remaining` and `reset_at_ms` describe the **request** class only — the binding minimum of the per-key and per-owner buckets — and are unchanged. `buckets` reports each budget separately, including the trading-action and cancellation budgets order writes are charged to, so order-placement headroom is readable rather than something a client had to guess at. WebSocket ceilings are still not reported here. See “Rate limits” in the API description. | Field | Type | Required | Description | | ------------- | ------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tier` | `string` | Yes | Rate limit tier name (e.g. `pro`, `marketmaker`, `unlimited`). Tiers are multipliers on one model, not different models. | | `limit` | `integer` \| `null` | Yes | Budget of request **weight** per second — not a count of requests. Most requests cost one unit, heavy aggregate reads cost more, and a batch order submit scales with its size (see `x-nexus-rate-limit-weight` and “Rate limits”). Also the burst capacity — the token bucket holds one second's worth of tokens — so `remaining` never exceeds it. Null for the unlimited tier, which is bucketed per client IP instead. | | `remaining` | `integer` \| `null` | Yes | Tokens currently in the bucket, expressed as **unit-cost requests**: a value of 10 means ten weight-1 requests, or two requests weighing 5. Divide by an operation's weight to get how many of *that* call you can still make. 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. The bucket refills continuously rather than in discrete windows, so tokens are available before this time — it is when the budget is whole again, not when the next request is permitted. Null for the unlimited tier. | | `buckets` | `object` | No | Every budget that meters this account, reported separately and keyed by the SAME label a `429` carries in its `bucket` field and the `X-RateLimit-Bucket` header — so `buckets[error.bucket]` resolves, and a refusal can be correlated with the state that produced it. `key` is present only when a per-key bucket actually gates the caller. `ip` never appears: it meters a connection rather than an account, and the only callers it applies to are `unlimited`-tier ones, whose whole response is null. Empty object for the `unlimited` tier, which no account-scoped bucket meters. **Additive** — the four flat fields above are unchanged and still report the binding request budget, so a client that ignores this field behaves exactly as before. | ## ReferralStats Venue-wide referral programme aggregate. Aggregate only — it carries no account id, address, referral code, or per-account figure by construction. | Field | Type | Required | Description | | ----------------------------- | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `codes_minted` | `integer` | Yes | Referral codes in existence. One per account that has registered since the programme shipped — NOT the account total, which also includes the codeless cohort reported by `accounts_without_code`. | | `edges_bound` | `integer` | Yes | Referral edges bound. An edge is immutable once written and one account can hold at most one, so this is also the number of distinct referred accounts. | | `active_referred` | `integer` | Yes | The subset of `edges_bound` whose referred account has since traded. Always less than or equal to `edges_bound`. | | `conversion_ratio` | [`Decimal`](#decimal) | Yes | `active_referred / edges_bound` as a decimal string, four decimal places. **`null` when `edges_bound` is zero** — there is nothing to divide, and `"0.0000"` would assert that edges exist and none converted. | | `accounts_without_code` | — | Yes | Accounts that have never registered an agent, which includes every account predating the programme. Registering an agent is the only path that mints a code, while an account row is also created on first login and on first credential — so this is NOT a frozen legacy cohort, and it grows whenever a wallet arrives and never registers. Published so the gap between this figure and `codes_minted` is visible rather than inferred. `null` when it could not be computed, in which case `accounts_without_code_error` says so and the rest of the aggregate is still accurate. | | `accounts_without_code_error` | — | No | Machine-readable reason `accounts_without_code` is `null`. Omitted when the cohort count succeeded — the same shape `OpenInterest.quote_error` carries, so a consumer that branches on presence and one that branches on a null value are both right. | | `latest_edge_at` | — | Yes | When the most recent edge was bound. `null` on a venue with no edges — never a zero timestamp. | | `as_of` | `string` | Yes | When this aggregate was observed, read from the accounts database clock rather than the serving replica's, so it describes the data rather than the process. | | `network` | `string` | Yes | The chain network THIS indexer serves, taken from its required `auth.network` configuration rather than asserted by the handler. Known values: `mainnet` (real funds), `testnet` (play funds), `local`. An open string rather than an enum, so a network added later cannot break deserialization — but treat an identifier you do not recognize as real funds. | | `testnet` | `boolean` | Yes | `true` on every network whose funds are not real — the boolean reading of `network`. `local` and `testnet` both report `true`, so `network` is the field that tells them apart. | | `note` | `string` | Yes | The caveats above, in prose, for a consumer that publishes the figure. | ## 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` — one of `ok` \| `degraded` \| `down` \| `starting` | — | Worst-of across all components. | | `updated` | [`TimestampMs`](#timestampms) | — | When this reading was taken, in epoch milliseconds. Named `timestamp_ms` until ENG-13528 renamed it to CCXT's `updated`, which is what `fetchStatus` returns. The reading is stamped on every request, so it is the age of the answer rather than the age of the last status change. | | `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` | — | — | | `connected` | `boolean` | — | — | | `last_event_ms` | [`TimestampMs`](#timestampms) | — | — | | `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` | — | — | | `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` | — | Traded notional in quote (USDX). **This is not a 24h window.** `MarketSummary.volume_24h` and `Ticker.quoteVolume` are the SAME accumulator under a misleading name: nothing decays either of them. Read `GET /stats/volume` when you want the cumulative figure stated honestly, with the coverage start that says what it is cumulative since. Same accumulator, and the same lossy `f64` conversion, as `MarketSummary.volume_24h`. | | `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` | — | — | ## Tier Rate-limit tier of an API key or account override. Exactly three values, PascalCase on the wire. `Pro` is what any owner with no override resolves to. `MarketMaker` carries the market-making allowance. `Unlimited` is for gateway/proxy keys that multiplex many users and is exempt from per-key rate limiting — it is a value a client can really receive, so a two-value union over `Pro` and `MarketMaker` is wrong. `PUT /admin/tiers` ACCEPTS a laxer input vocabulary than this (`pro`, `market_maker`, `marketmaker` and `unlimited` all parse), but every response normalizes to the three values above. *This schema declares no properties in the contract.* ## TierEntry One account-level tier override. | Field | Type | Required | Description | | --------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `address` | `string` | Yes | Account the override applies to. `GET /admin/tiers` always serves it canonically, as `0x` + 40 lowercase hex characters. `PUT /admin/tiers` echoes the request string back VERBATIM instead, so a caller that sent it unprefixed or mixed-case reads that form back — compare addresses case-insensitively and with `0x` stripped, never byte-for-byte. | | `tier` | [`Tier`](#tier) | Yes | — | ## TimestampMs Unix epoch timestamp in milliseconds. *This schema declares no properties in the contract.* ## Trade CCXT-compatible trade record | Field | Type | Required | Description | | ---------------- | --------------------------------- | -------- | ----------- | | `id` | `string` | — | — | | `symbol` | `string` | — | — | | `price` | `number` | — | — | | `amount` | `number` | — | — | | `cost` | `number` | — | — | | `side` | `string` — one of `buy` \| `sell` | — | — | | `timestamp` | [`TimestampMs`](#timestampms) | — | — | | `datetime` | `string` | — | — | | `takerOrMaker` | `string` \| `null` | — | — | | `is_liquidation` | `boolean` | — | — | | `info` | `object` | — | — | ## WithdrawalError Machine-readable withdrawal rejection. The classification is in `code` for every rejection the exchange raises itself; the exchange-freeze refusal carries it in `error` instead, and a forwarded engine rejection carries the same value under both. Branch on whichever is present — one always is — and treat `message` as human-readable detail only. | Field | Type | Required | Description | | ----------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- | | `code` | `string` | — | Stable error classification. See the per-status descriptions for the documented values. | | `error` | `string` | — | Error classification for the freeze refusal (`withdrawals_frozen`), and a duplicate of `code` on forwarded engine rejections. | | `message` | `string` | — | Human-readable detail. Do not branch on it. | | `claimed` | `string` | — | On `SIGNER_MISMATCH`: the `wallet` the request claimed. | | `recovered` | `string` | — | On `SIGNER_MISMATCH`: the address actually recovered from `signature`. | ## WithdrawalRequest A signed `WithdrawIntent`. The server recovers the signer from `signature` and credits that wallet; nothing here selects a destination. | Field | Type | Required | Description | | ------------- | --------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `wallet` | `string` | Yes | Withdrawing wallet address (0x-prefixed, 20 bytes). Must equal the address recovered from `signature`. | | `amount` | [`Decimal`](#decimal) | Yes | Amount to withdraw, as a positive whole number of the asset's smallest unit. `WithdrawIntent` carries a `uint256`, so a fractional value cannot be represented and is refused with `400 fractional_amount`. Encode the same integer you signed. | | `asset` | `string` | No | Asset symbol; defaults to USDX. Recorded on the withdrawal record and not forwarded to the engine. The venue is single-collateral, so the signed `asset` address is always the USDX sentinel. | | `nonce` | `integer` | Yes | Single-use per-wallet nonce, included in the signed typed data. The current Unix timestamp in milliseconds is a safe value. Reusing an accepted nonce returns `401 NONCE_REPLAY` and creates no second withdrawal. | | `signature` | `string` | Yes | EIP-712 signature over `WithdrawIntent{amount, asset, nonce}` from the wallet private key (0x-prefixed, 65 bytes, canonical low-S). | | `destination` | `string` | No | Optional, and locked to `wallet`. The signed intent carries no destination, so any other value is refused with `400 destination_locked`. Omit it unless you are asserting the destination explicitly. | ## WithdrawalResponse Withdrawal acceptance. Carries the authoritative post-withdrawal collateral balance from the engine, plus the identity of the ledger entry the acceptance created. The withdrawal is recorded with status `pending` and is also readable through `GET /withdrawals`; this response is not proof of on-chain settlement. ENG-13528 added `id`, `amount`, `status` and `timestamp`. Before that this object was `balance` alone, so a caller could not follow its own withdrawal — it had to re-read `GET /withdrawals` and guess which row was its own. `txid` is deliberately absent: no on-chain transaction exists yet at acceptance, and it appears on the `GET /withdrawals` entry once the transfer is submitted. | Field | Type | Required | Description | | ----------- | --------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `balance` | [`Decimal`](#decimal) | Yes | Authoritative post-withdrawal collateral balance, as the engine reported it. `null` when the engine accepted the withdrawal but its body could not be read — the acceptance still stands, and the identity fields below are still served, so an unreadable balance is never reported as a fabricated number. Nullable in the schema and not only in this sentence: a generated client typed on a bare string would reject a legal response. | | `id` | `integer` | Yes | Identifier of the `FundsEntry` this acceptance recorded. The same `id` the entry carries on `GET /withdrawals`. | | `amount` | [`Decimal`](#decimal) | Yes | The accepted withdrawal amount, echoed from the signed intent. | | `status` | `string` — one of `pending` \| `submitted` \| `confirmed` \| `failed` | Yes | Status the entry was recorded with. Always `pending` at acceptance; the other values appear only on `GET /withdrawals` after an operator transition. | | `timestamp` | [`TimestampMs`](#timestampms) | Yes | When the entry was recorded, in epoch milliseconds. The same instant the entry carries on `GET /withdrawals`. | ## WsTokenLegacyResponse A minted WebSocket token from the legacy `POST /ws-tokens`. Deliberately narrower than `WsTokenResponse`: this endpoint discards the expiry the token store computes, so there is none to serve and the 60 s TTL has to be assumed. One more reason to prefer `POST /ws/token`. | Field | Type | Required | Description | | ------- | -------- | -------- | ---------------------------------------------------------------- | | `token` | `string` | Yes | Single-use token: 48 lowercase hex characters (24 random bytes). | ## WsTokenResponse A minted WebSocket token and its expiry, from `POST /ws/token`. | Field | Type | Required | Description | | ------------ | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `token` | `string` | Yes | Single-use token: 48 lowercase hex characters (24 random bytes). Pass it as `?token=TOKEN` when upgrading to `GET /ws`. | | `expires_at` | [`TimestampMs`](#timestampms) | Yes | When the token stops being accepted — mint time plus the 60 s TTL. Read it rather than re-deriving the deadline from your own clock. | --- # 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.