Nexus cross-margin requirements for testnet trading
Nexus requires sufficient free margin in its shared testnet account before the matching engine accepts an order that opens or enlarges a position. Synthetic USDX supplies the collateral. Existing positions and order reservations affect capacity, while each market has its own margin rates and leverage ceiling. Account funding alone does not guarantee order acceptance.
updated
Account funding versus isolated-position adjustments
A cross-margined position uses shared account collateral, while an isolated-margin adjustment moves collateral allocated to one open position. The appropriate control depends on the position’s margin mode. Successful authentication establishes permission to make requests; it does not establish that an isolated-margin operation applies to a cross-margined position.
Funding the cross-margin account
The testnet faucet supplies synthetic USDX with no real-world value. The credit operation has a per-API-key daily allowance, and its response reports the amount credited and the allowance. That credit belongs to the account balance. A position-level margin adjustment serves a different purpose and cannot replace testnet account funding.
Moving isolated collateral
The isolated-margin adjustment operation requires an open position in isolated mode. It rejects a cross-margined position with
MarginModeNotIsolated. Removing isolated collateral also faces the position’s free-margin and withdrawal-floor constraints. These conditions concern that position’s allocation, so they do not describe how to replenish the shared
cross-margin
account.
Free margin after positions and order reservations
Free margin reflects the account’s remaining capacity after existing commitments, which makes it different from the collateral balance. Account equity includes collateral and unrealized profit or loss. The free-margin calculation deducts position initial-margin requirements and pre-trade order reservations from equity, so a funded account can still lack room for another order.
Resting exposure matters before an order becomes a completed trade. Reservations can commit capacity alongside open positions. Looking only at the position list therefore leaves out part of the account’s margin commitments; the portfolio summary also reports open-order counts and aggregate margin usage.
Trading fees and funding settlements can change the balance that supports shared exposure. Their effects belong in the account assessment alongside unrealized profit or loss. A gain or loss on one cross-margined position affects shared equity, so evaluating another position in isolation does not describe the whole account’s capacity.
The reported
withdrawable
amount floors authoritative free margin at zero. It describes the amount that can leave the account after commitments. A positive collateral balance and a positive withdrawable balance consequently answer different questions.
Market-specific margin rates and leverage ceilings
The selected contract determines the published risk inputs, including initial margin, maintenance margin, and maximum leverage. These are market parameters, so a remembered setting from another contract does not establish the requirements for this order.
Initial margin against marked notional
The position read model calculates cross-margin usage as marked notional multiplied by the market’s initial-margin rate. Marked notional uses absolute position size multiplied by mark price. Reported margin usage is the initial-margin requirement held against the position.
Maintenance requirements and permitted leverage
Maintenance margin governs the ongoing collateral requirement for open exposure. The market’s maximum leverage describes a permitted ceiling; it does not establish available account capacity. Market data exposes these inputs separately. Margin rates and permitted leverage can change with market configuration. An order estimate needs the values applicable to that contract.
Quantity and price requirements alongside margin
Sufficient margin does not make an order valid if its price or quantity violates the contract’s trading rules. Tick size defines the permitted price increment, and lot size defines the quantity increment. The contract also supplies minimum and maximum order sizes. Price and quantity must satisfy their respective grids and applicable bounds. Rounding a quantity changes the size used in a margin estimate. Rust SDK normalization helpers round price and size, then validate the resulting values; rounding alone cannot resolve every violation. A quantity can remain below the minimum after normalization. Limit, stop-limit, and take-profit-limit orders require a supplied limit price. Trailing-limit orders use trailing and limit offsets instead, while market-family orders omit the limit-price field.
The market-status read separately reports whether a contract is active or halted. That operating state differs from its price and quantity rules. Meeting a collateral requirement does not establish market availability for an intended request. These engine rules apply to requests from both the terminal and software clients.
Pre-trade projections without reserved capacity
An order preview estimates the proposed request’s margin impact without placing the order or reserving collateral. Its fields include required initial margin, projected post-trade equity, projected fees, and expected execution price.
A successful preview response can contain
accepted: false
and a rejection reason. Optional projections can also be absent; an unreported margin requirement does not mean zero. Expected fill price can be absent when no execution is projected, including a limit order that would rest. The matching engine checks the actual submission against the state that exists when it arrives.
Account snapshots and unavailable risk calculations
The consolidated account-state read returns the portfolio summary and open positions from one coherent server-side read. This avoids combining an aggregate from one moment with positions from another. The summary and positions still contain fields that the server may leave unreported, so consistency between the two does not make every risk figure available.
Derived position fields can carry a companion error explaining why a value is missing. Account summary and state reads return HTTP 502 with
authoritative_margin_unavailable
when the authoritative margin view cannot supply the calculation. That response leaves capacity unknown. It does not establish a zero balance, an empty position list, or freedom to add exposure.
Adding exposure and reducing a position
Additional exposure and a position reduction face the same live account context, but their purposes differ. An exposure-increasing order needs capacity for the added requirement. A reduce-only order constrains execution to decreasing an existing position. Both still involve the selected contract’s valid order fields and the account’s current state.
- Confirm testnet funding and cross-margin mode for the affected position.
- Use shared equity, existing position requirements, and order reservations to assess capacity.
- Read the contract’s margin rates, leverage ceiling, quantity bounds, and price increments.
- For added exposure, inspect required initial margin and projected equity in the preview.
- For a reduction, use reduce-only handling and distinguish accepted order size from executed quantity.
An accepted reduction changes exposure only when execution actually reduces the position. Mark prices or another fill can change the account assessment before either request reaches the engine.
Maintenance pressure and portfolio liquidation messages
Liquidation monitoring compares shared account equity with the portfolio’s maintenance-margin requirement. A portfolio-level alert can have no market identifier because its scope covers the shared account. That absence does not turn the alert into an error.
A
PortfolioLiquidation
notification reports that the account’s cross-margin positions have already closed.
Its per-market closure records describe the completed liquidation. Collateral coverage can deteriorate without a new order when mark prices move against existing exposure.
Questions and answers about Nexus
Can a Nexus order batch consume the margin needed by later orders?
Yes, batch orders are processed sequentially, so an earlier order can consume margin that a later order needs. The batch is not atomic: one rejection does not cancel the other entries. Each result corresponds to its request position and reports acceptance or rejection independently. An overall successful response therefore does not establish that every requested order passed its margin check.
Why can leverage remain null when a position reports margin usage?
The position read model can report margin usage while lacking the margin state needed to derive actual leverage. A companion error such as margin_state_not_mirrored explains the missing value. Dividing notional by the reported initial-margin usage produces the reciprocal of the market’s initial-margin rate. That calculation does not recover the position’s actual leverage setting or its share of account equity.
Does the account fee response apply to every contract’s margin estimate?
The account fee response reports rates within the scope named by its schedule field. It is a forward-looking fee schedule, not an average of fees already paid. The documented standard schedule concerns the standard crypto group; other market groups can use different schedules. Applying one returned rate to every contract can therefore misstate projected trading costs and the balance remaining after execution.
Can a testnet API key authorize margin-related actions on another network?
A testnet API key is valid only on the network that issued it. Session tokens, agent registrations, and signing domains are also network-scoped. Changing a client’s target does not move its credentials or collateral. A funding or trading request must use credentials for its selected network; a testnet balance does not establish collateral available elsewhere.
Why does a funded testnet account receive a jurisdiction error?
A jurisdiction control can reject a state-changing request even when the account has sufficient margin. The response includes a machine-readable reason such as US_RESTRICTED, GEO_UNRESOLVED, or RESTRICTED_JURISDICTION. These are access decisions, and SDKs treat them as permanent for that request origin. Adding collateral or repeatedly submitting the same request does not remove that access condition.
Will the liquidation stream replay my account’s warning state after reconnecting?
The liquidation channel does not send a current warning snapshot when a client subscribes or reconnects. Alerts arrive when severity worsens, without repeated messages while severity holds or a message on recovery. There is also no REST read of the current alert state. Silence after reconnection therefore gives no assurance that the account has recovered its collateral coverage.
Is a timed-out order request proof that no margin was committed?
A timeout leaves the order’s acceptance status unknown because the server may have processed the request before its response was lost. The TypeScript SDK sends state-changing requests once and avoids automatically retrying them. Account and order records provide the relevant state afterward. Sending another exposure-increasing order without resolving that uncertainty can create an additional commitment.