Schema Reference
Shared response and request types for the Nexus Exchange API (OpenAPI v0.9.36). Every one of the 75 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). 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). Fields named
*_ms,*_at_ms, ortimestampfollow this convention. A few CCXT-shaped schemas also carry adatetimefield, which is an ISO 8601 date-time string alongside the numeric timestamp.ThroughputSample.timestampis 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, andoneOf/anyOfwith anullbranch where the non-null branch is a$ref(most often Decimal or TimestampMs). A single-elementallOfaround a$refis 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 pairs it with a companion
<field>_errorstring holding a machine-readable reason (e.g.mark_price_unavailable). When the value is populated, the companion isnull.Two naming families, and casing does not imply value type. Native Nexus schemas use
snake_casekeys and decimal strings. The CCXT-compatible schemas (Ticker, OrderBook, Trade, Order) use CCXT'scamelCasekeys for the fields CCXT defines and keepsnake_casefor the Nexus extensions it does not, so one schema carries both. Their value types are not uniform:Ticker,OrderBookandTradeserialize numbers as JSON numbers for drop-in compatibility with existing CCXT tooling, whileOrderkeeps 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
Requiredcolumn reflects the schema'srequiredarray. Where a schema declares norequiredarray 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
The authenticated account's effective fee schedule, mirroring Hyperliquid userFees. Reports what the venue charges today: there are no per-account fee tiers or discounts yet (fee model still a draft), so tier is base and discounts is empty. The rate is the forward-looking schedule rate scoped by schedule, not a realized per-fill average.
maker_fee_bps
integer
Yes
Effective maker fee in basis points. Negative means the maker is paid a rebate — e.g. -2 is a 0.02% rebate.
taker_fee_bps
integer
Yes
Effective taker fee in basis points — e.g. 5 is a 0.05% fee.
tier
string
Yes
Fee tier for the account. Currently always base: there are no per-account fee tiers yet (distinct from rate-limit tiers). New values may appear when the fee model lands, so treat this as an open string.
schedule
string
Yes
Scope of the reported rate. Currently always standard. The venue charges a per-market schedule (standard crypto, mid-cap crypto, FX, commodities/indices all differ, and the split varies by deploy config), but this endpoint takes no market parameter, so it reports the standard crypto-group schedule and marks it here. Treat the rate as scoped by this value, not a venue-wide guarantee; per-market effective rates are a planned follow-up. Treat as an open string — new scopes may appear.
volume_30d
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
Yes
Active fee discounts applied to the account. Currently always empty — no discount program exists yet.
AccountFunding
A funding payment for the account.
market_id
string
—
—
direction
string — one of paid | received
—
—
AccountPortfolioSummary
Portfolio summary for the authenticated account (aggregate equity, PnL, volume, open counts).
total_realized_pnl_24h
—
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
—
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
—
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. Same contract as volume_30d_estimated on GET /account/fees, and the same caveat: false means no eviction was detected, not that the window is certified complete.
open_positions_count
integer
—
—
open_orders_count
integer
—
—
withdrawable
—
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.
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.
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 <field>_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.
AdlClosureRecord
One counterparty's forced closure within an ADL settlement.
AdlEventRecord
Single ADL settlement (insurance fund depleted → counterparty closures). v0.21.
market_id
string
—
—
target_account
string
—
0x-prefixed bankrupt account
sequence
integer
—
Engine event sequence number
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.
address
string
—
Agent address (0x-prefixed)
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.
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
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.
BalanceBucket
One balance band and the number of accounts in it.
BalanceDistribution
Aggregate balance distribution. Carries no per-account values by construction.
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.
BridgeChainAssets
Bridgeable assets for one chain.
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
Yes
Assets that can be deposited from this chain (USDC, 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.
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.
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.
BridgeDepositAsset
A depositable asset on a specific chain.
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
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
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.
error
object
Yes
—
BridgeWithdrawAsset
A withdrawable asset on a specific chain.
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
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.
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.
id
string
Yes
Opaque withdrawal id (wdl_<hex>), 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.
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).
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.
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.
market_id
string
—
—
side
string — one of Long | Short
—
The side the position was before it closed.
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.
amount
—
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.