AX ExchangeCopy Anchor Link

AX Exchange is a centralized and regulated derivatives exchange for traditional underlying asset classes. Architect Bermuda Ltd. operates AX under a license from the Bermuda Monetary Authority (BMA). AX lists perpetual and dated futures contracts in both its production and sandbox catalogs.

This integration supports live market data ingest and order execution with AX Exchange.

OverviewCopy Anchor Link

This adapter is implemented in Rust and exposed to Python through PyO3 bindings. It does not require external AX client libraries.

This guide assumes a trader is setting up for both live market data feeds, and trade execution. The AX Exchange adapter includes multiple components, which can be used together or separately depending on the use case.

• AxHttpClient: Low-level HTTP API connectivity.
• AxMdWebSocketClient and AxOrdersWebSocketClient: Low-level WebSocket connectivity for Rust callers.
• AxDataClient: A market data feed manager.
• AxExecutionClient: An account management and trade execution gateway.
• AxDataClientFactory: Factory for AX data clients.
• AxExecutionClientFactory: Factory for AX execution clients.

ExamplesCopy Anchor Link

• Python examples
• Rust examples

AX Exchange documentationCopy Anchor Link

AX Exchange provides documentation for users at the Architect documentation site. Refer to the AX Exchange documentation in conjunction with this NautilusTrader integration guide.

ProductsCopy Anchor Link

The production catalog lists perpetual and dated futures contracts in these venue categories:

The sandbox catalog differs. It also lists energy_etfs contracts such as USO-PERP and UNG-PERP, which map to the Equity asset class, and compute perpetuals such as OCPI-H100-PERP.

The adapter maps a crypto venue category to the CRYPTOCURRENCY asset class, and any category it does not recognize to ALTERNATIVE.

Perpetual contractsCopy Anchor Link

A perpetual contract (perpetual swap) is a derivative that tracks the price of an underlying asset without expiring. Unlike standard futures, there is no settlement date, which eliminates rollover costs and simplifies position management. A funding rate mechanism keeps the contract price aligned with the underlying index price through periodic payments between long and short holders. See the Architect documentation for details on funding rate mechanics and contract specifications.

Characteristics of AX perpetual contracts:

• Cash-settled in USD: No physical delivery. All profit and loss is settled in USD.
• Funding rates: Periodic payments keep the contract price aligned with the underlying.
• Multiplier of 1: Each contract represents one unit of exposure to the underlying.
• Whole contracts only: Fractional quantities are not supported.
• Margin: A position requires initial margin to open and maintenance margin to stay open.

The adapter represents an AX instrument without an expiration as PerpetualContract and an instrument with an expiration as FuturesContract. The venue category determines the Nautilus asset class. The adapter uses MARGIN account type and NETTING order management.

SymbologyCopy Anchor Link

The adapter preserves each AX symbol and appends the Nautilus venue identifier .AX. Perpetual symbols use the -PERP suffix. Dated symbols include their year and contract month.

The venue identifier is AX. To construct a Nautilus InstrumentId:

from nautilus_trader.model import InstrumentId

instrument_id = InstrumentId.from_str("EURUSD-PERP.AX")

EnvironmentsCopy Anchor Link

AX Exchange provides two trading environments. Configure the appropriate environment using the environment parameter in your client configuration.

SandboxCopy Anchor Link

The default environment for development and testing with simulated funds. All sandbox endpoints are resolved automatically when environment=AxEnvironment.SANDBOX.

export AX_API_KEY="your-sandbox-api-key"
export AX_API_SECRET="your-sandbox-api-secret"

ProductionCopy Anchor Link

For live trading with real funds. Requires a verified AX Exchange account.

config = AxExecutionClientConfig(
    environment=AxEnvironment.PRODUCTION,
)

Market dataCopy Anchor Link

The adapter provides real-time market data via WebSocket subscriptions, with HTTP endpoints for historical data backfill.

Data typesCopy Anchor Link

AX instrument states map to MarketStatusAction as follows:

WebSocket subscription behaviorCopy Anchor Link

AX market data WebSocket subscriptions use one active stream per symbol. The adapter selects the smallest stream that covers the active Nautilus subscriptions:

• A trades-only subscription uses AX level: "TRADES", which delivers trade prints only.

• Book-only and quote-only subscriptions set AX trades: false and ticker: false to suppress unrequested trade and ticker events.

• Mark price and instrument status subscriptions require AX ticker events. Thus, the adapter enables ticker delivery on the active book stream. If no book subscription exists, it opens an L1 stream.

• Book deltas subscribe at the AX level matching the Nautilus book type. L1_MBP has no delta-capable AX equivalent, so the adapter logs a warning and subscribes at L2 instead.

• If multiple Nautilus data types are active for a symbol, the adapter resubscribes only for these changes:

  • The required AX level or delivery flags change.
  • An order book needs a fresh snapshot (see Order book recovery).

• Subscription changes reach AX in the order the data engine issues them, so an unsubscribe followed by a resubscribe leaves the stream subscribed.

AX documents estimated funding rates on ticker events and an estimated-funding request on the orders WebSocket. Ticker models retain estimated-funding metadata. Nautilus exposes settled funding-rate updates through HTTP polling. The adapter does not emit a separate estimated-funding data type or request standalone estimates.

Order book recoveryCopy Anchor Link

The data client tracks each order book delta subscription with the shared book recovery machinery. AX L2 and L3 messages carry a full snapshot and no sequence number. AX sends one immediately after each subscribe acknowledgement, including for an empty or unchanged book. The client accepts every message as a snapshot. It suppresses book output while a subscription write is in flight and drops frames for a book that is no longer subscribed.

Recovery replaces the symbol's subscription with an unsubscribe and a subscribe on the same connection. The replacement retains its current level and trade and ticker flags. AX carries all market data for a symbol on one stream, so trades, quotes, mark prices, and instrument status for that symbol pause while the replacement runs. Recovery starts when:

• An initial subscription write fails.
• No snapshot arrives within book_snapshot_timeout_secs (default 10 seconds) after the initial subscription write completes or the connection is re-established. A data client connect after disconnect counts too: the client keeps its books, and the WebSocket client replays their subscriptions.
• An L2 or L3 frame cannot be converted, such as an incremental (st: false) frame. The book stops emitting until a replacement snapshot arrives, and a running recovery's current attempt fails without waiting for its snapshot deadline.

A subscription AX rejects delivers no snapshot, so its snapshot deadline starts recovery. A subscription the client cannot queue because the WebSocket handler has stopped starts no recovery, and its book emits nothing. Subscribing to deltas for a book whose stream is already open replaces the stream, so the book starts from a fresh snapshot.

Each recovery makes up to eight attempts within 180 seconds, with exponential backoff. It then retries until it accepts a snapshot. The retry interval doubles from one minute to fifteen minutes. A running recovery continues across reconnects with its remaining budget, and unsubscribe or shutdown cancels it. A recovery waiting between attempts after its budget retries at once on the new connection. Recovery never ends in a failed state.

Subscription writes run in order while the handler continues processing commands and frames. Cancellation skips unsent book subscription and recovery writes and keeps their snapshot gates closed. A write already admitted to the network can still complete before later subscription changes.

The client does not correlate subscription acknowledgements with recovery attempts. A snapshot queued before a replacement can complete recovery once the replacement write finishes. AX sends no frames while a book is unchanged, so the client does not treat a silent book as stale.

Setting book_snapshot_timeout_secs to 0 disables snapshot deadlines. Recovery then starts only from a failed initial write or an invalid frame. Within the retry budget, a replacement that delivers no snapshot waits until one of these events:

• The client accepts a snapshot.
• An invalid frame fails the attempt.
• Recovery is cancelled.
• The 180-second initial budget ends.

Live recovery validationCopy Anchor Link

The ax-book-stress harness is a development tool for changes to book synchronization and recovery. It uses AX sandbox market data and submits no orders. It checks five perpetual books against the book stream contract and each relayed raw L2 frame.

The AX market data stream requires authentication, so the harness reads sandbox API credentials from AX_API_KEY and AX_API_SECRET and runs without scripts/strip-adapter-env.bash. From the repository root, run:

CARGO_BUILD_JOBS=16 cargo test -p nautilus-architect-ax --features examples --test ax-book-stress -- --timeout 10 --rounds 14

--scenario selects the run:

• churn (default): rotates through these conditions:

  • Invalid frames that each book recovers without a reconnect.
  • Snapshots held past their deadlines after a reconnect.
  • Late snapshots after a reconnect.
  • A rejected replacement.
  • Reconnects cut before their snapshots.
  • A restart during recovery.
  • A 40-second traffic freeze that closes no socket.

• initial: drops each book's first snapshot and silences its stream, in a fresh session per round. With --timeout 0, the books stay dark until a reconnect replays their subscriptions.

• turnover: unsubscribes and resubscribes a recovering book just after recovery starts, after its replacement reaches the venue, or after a rejected replacement's deadline. The new subscription must keep streaming once the venue settles, with no further replacement.

• boundaries: rejects every attempt in the retry budget, then checks the retry ceiling, a reconnect that ends the ceiling wait, unsubscribe during recovery, and shutdown during a reconnect. It requires a nonzero --timeout, since snapshot deadlines end each rejected attempt, and at least three --symbols.

--timeout sets the snapshot timeout in seconds, where 0 disables snapshot deadlines, and --rounds sets the number of rounds (14 by default). --symbols takes a comma-separated list of symbols to check. The sandbox market maker quotes only some instruments, and a book that stops streaming fails the run, so choose books that stream.

The harness requires the sandbox market data WebSocket and REST API. See Stress harnesses for the shared flags and output format.

HTTP API behaviorCopy Anchor Link

• GET /tickers returns limit/offset page metadata and supports limit, offset, and sort query parameters.
• GET /ticker returns the ticker under a top-level ticker response field.
• GET /open-orders uses limit/offset pagination. Open-order reconciliation traverses all pages and validates totals, offsets, duplicates, and completeness so detected response drift fails the request.
• GET /fills and GET /funding-rates use cursor pagination. The adapter traverses each cursor chain as a best-effort historical read. AX corrections during traversal are not an atomic snapshot.
• GET /orders exposes cursor metadata and supports order_id, order_ids, account_id, and optional timestamp filters. Order-report history traversals follow the cursor chain, accept partial pages, and validate declared limits and totals. Empty continuation pages, repeated cursors, duplicate order IDs, and incomplete declared totals fail the request.
• Open-order, historical-order, fill, and position report requests resolve an uncached symbol through GET /instrument and cache the result. An instrument request or parse failure fails that entire report request instead of dropping venue state.
• GET /transactions requires start_timestamp_ns and end_timestamp_ns with a range no wider than 7 days. The low-level client exposes its cursor and account selectors.
• GET /order-status can include reject_reason and reject_message for rejected orders.
• When an account selector is omitted, AX uses the primary account. The high-level execution client owns one primary account. Low-level request models expose documented account selectors.

Bar intervalsCopy Anchor Link

Orders capabilityCopy Anchor Link

The AX order-entry API has no order-type selector. Its single native order shape requires a price, which the adapter maps to a Nautilus LIMIT order. The adapter simulates a Nautilus MARKET order by previewing an aggressive price and submitting that priced shape with IOC. Tracked fills retain the submitted Nautilus order type and side, including simulated market orders.

The official REST place-order and orders WebSocket request schemas contain no order_type or trigger_price field. Sandbox stop-limit submissions with unbreached triggers executed immediately at the active limit price. With conditional execution unconfirmed, the adapter rejects venue-native stop-limit orders before sending them.

Nautilus can still emulate a stop-limit order locally. The common order emulator waits for the configured trigger, then sends a plain limit order to this adapter.

Order typesCopy Anchor Link

Execution instructionsCopy Anchor Link

The adapter omits rb on place and replace requests, using AX's default rej behavior for post-only orders. Selecting bo (back off one tick from the opposite side) or tbl (best price on the same side) is not supported. See the AX changelog.

Sandbox crossing-order validation confirms that omitted rb and explicit rej reject with post-only order would cross the book. External orders that opt into bo or tbl report the adjusted limit in p; reconciliation uses that price. Post-only orders can fill after resting.

Order-history, open-order, and WebSocket order responses retain rb as optional typed adapter metadata on AxOrderDetail, AxOpenOrder, and AxWsOrder. It describes the latest place or replace request and takes effect only when that request has po: true. Missing or null values remain absent. Unrecognized strings map to Unknown, not Reject. OrderStatusReport does not expose this metadata, so reconciliation reports cannot distinguish these repricing policies for externally placed or replaced orders.

The reduce-only boundary matters because AX has no reduce-only field. In sandbox, the venue accepted and filled an order as ordinary after its reduce-only instruction was dropped from the wire payload. Such an order can open or increase exposure instead of closing it. Production behavior was not verified. The adapter therefore denies reduce-only orders before submission rather than sending an instruction the venue cannot honor.

The adapter also rejects quote-quantity and display-quantity instructions because its AX wire path cannot encode those semantics. This is an adapter boundary, not a claim that AX Exchange rejects equivalent venue-native features.

Time in forceCopy Anchor Link

The venue deprecates DAY and recommends GTC instead.

Advanced order featuresCopy Anchor Link

The adapter restores cached local open and in-flight orders before processing the orders stream. An uncertain send or request failure retains local tracking until a terminal event or a terminal reconciliation report identifies the active venue order. After replacement, queries, modifications, and cancels use the active venue order ID. Stale parent updates and malformed tracked updates wait for reconciliation without being routed as external orders.

A cancel that already has a venue order ID is forwarded, including a second cancel of a terminal order. A strategy does not send that second cancel after the local order is already closed or pending cancel. The adapter emits OrderCancelRejected only when AX sends CancelRejected. Sandbox answers a resend of an already canceled order with WebSocket error 404 (order not found). The adapter logs that error and does not turn it into OrderCancelRejected.

Side filter: AX cancel-all has no side parameter. Thus, a CancelAllOrders command with order_side set sends individual cancel requests. It cancels only open orders on that side for the instrument. A side-filtered request selects from open orders only, so an inflight (SUBMITTED) order not yet acknowledged by AX survives one.

Position managementCopy Anchor Link

Order queryingCopy Anchor Link

Account stateCopy Anchor Link

The /balances endpoint carries no margin data, so account state also requests /risk-snapshot. Its USD initial_margin_required_total populates the USD balance's locked funds, capped at the USD balance. A USD MarginBalance entry pairs initial with maintenance margin. When /risk-snapshot fails, account state falls back to balances-only with zero locked margin and a warning.

AuthenticationCopy Anchor Link

AX Exchange uses bearer token authentication:

1. API key and secret obtain a session token via /authenticate.
2. The session token is used as a bearer token for subsequent REST and WebSocket requests.
3. The adapter requests one-hour session tokens and refreshes them every 30 minutes.
4. A refresh updates REST authentication and the token used by the next WebSocket reconnect without interrupting the active connection.

ConfigurationCopy Anchor Link

Environments and endpointsCopy Anchor Link

Data client configuration optionsCopy Anchor Link

Execution client configuration optionsCopy Anchor Link

When transport_backend=None, the compiled Rust default selects Sockudo when the transport-sockudo Cargo feature is enabled and Tungstenite otherwise.

Use AxDataClientConfig with AxDataClientFactory and AxExecutionClientConfig with AxExecutionClientFactory. The Python examples show the complete LiveNode.builder(...) configuration for data and execution clients.

API credentialsCopy Anchor Link

There are two options for supplying your credentials to the AX Exchange clients. Either pass the corresponding api_key and api_secret values to the configuration objects, or set the following environment variables:

• AX_API_KEY
• AX_API_SECRET

When starting the trading node, you'll receive immediate confirmation of whether your credentials are valid and have trading permissions.

Implementation notesCopy Anchor Link

• Whole contracts only: AX uses integer contract quantities. The adapter models a one-contract size increment and lot size, while enforcing each instrument's separate minimum_order_size. Fractional quantities generate OrderDenied locally.

• Dated futures activation: AX publishes expiration but not activation timestamps. The adapter uses zero for the unknown activation time and preserves that limitation in instrument metadata.

• Rate limiting: The adapter applies a conservative rate limit of 10 requests/second with automatic exponential backoff on rate limit responses.

• Market orders: AX does not support native market orders. The adapter uses a preview endpoint to determine the take-through price and submits an aggressive IOC limit order. Because the book can move between the preview and the submission, a simulated market order may fill partially.

• Stop-limit orders: The adapter rejects venue-native stop-limit submissions because sandbox testing did not confirm conditional semantics. Use local order emulation when a strategy requires a stop-limit order.

• Order modification: AX supports atomic order replacement via POST /replace-order. The execution client maps modify_order to this endpoint. The HTTP response contains a proposed venue order ID; the orders stream confirms whether replacement succeeds. Queries and cancels retain the working order ID until the stream, a child fill, or a query confirms the replacement. A query of a replaced parent checks proposed IDs and returns the confirmed replacement's status, including fills or cancellation. It leaves the result unresolved when no replacement is confirmed. A cancel before confirmation targets the parent and can be rejected; recovery then needs a late stream confirmation, a child fill, or an explicit query. A crossing post-only replacement emits OrderModifyRejected with the venue reason and leaves the original order working. The adapter rejects a modification locally if it carries a trigger price, because AX has no field for one, or if the order has no venue order ID yet.

• Funding rate polling: The data client polls GET /funding-rates for each subscribed instrument at funding_rate_poll_interval_mins. It requests a seven-day lookback to find a rate across weekends and holidays. It emits the latest rate only when it differs from the last one emitted.

• Cancel on disconnect: Set cancel_on_disconnect=True in the execution client config to have the exchange cancel all open orders if the orders WebSocket disconnects.

• Account fee rates: Instruments do not carry maker or taker fee rates. An authenticated client resolves account rates from GET /whoami and fails to connect if that lookup fails. The execution client caches rates per AX account, apart from instruments, and refreshes them each time it connects. Automatic WebSocket reconnects keep the cached rates.

• Fill commissions: Real-time fill events from the WebSocket do not include fee data. The adapter estimates commission for both tracked fill events and untracked fill reports using the fill quantity, absolute fill price, contract multiplier, and account's maker or taker rate. It uses the trade's account ID, then the order's account ID if absent, or the first /whoami account if neither ID is present. It keeps the calculation in decimal arithmetic and rounds only the final fee into USD Money, whose precision is 2.

  A fill whose instrument or complete account fee schedule is not cached, or whose commission cannot be represented, is logged and skipped. Tracked order metadata remains available for reconciliation. Recovery depends on configured reconciliation checks or an explicit order query. Skipped fills do not trigger an immediate REST request.

  Reconciliation does not replace an applied commission, so a streamed estimate remains even when the venue-reported /fills fee differs. That endpoint supplies the fee for a fill that was not already applied from the stream. The adapter converts it with Money::from_decimal into USD, so a sub-cent fee such as 0.012188 is stored as 0.01. An unrepresentable REST fee fails fill-report requests, historical order-status requests that need fills, and mass status. During startup, that error prevents the node from starting.

• Fill reconciliation window: The /fills endpoint requires a bounded time range and caps the span at seven days. Fill requests cover seven days by default, or the shorter configured lookback. Order history uses the configured lookback and has no start bound by default.

  Older order reports can still produce inferred fills with commission=None. Order history does not supply fees, and the adapter does not estimate historical fees from current account rates. Position accounting excludes unavailable fees, so reconstructed PnL for that history is incomplete. A reported zero fee remains a zero commission.

• Fill order identity: AX can omit order_id for block trades and final settlement fills. The adapter derives a deterministic reconciliation order ID from trade_id for those classified records and includes a matching FILLED market order report in startup mass status. Classification fields are optional for regular fills with a valid order_id. The adapter rejects rows with neither an order ID nor explicit special-fill classification, and rejects inconsistent classification.

• Unfilled IOC/FOK: AX reports an unfilled immediate order as an expiry. The adapter maps it to OrderCanceled to match NautilusTrader semantics.

• One-tick quotes: Example testers place post-only limits one tick from top of book. Those quotes can still fill. Flatten leftovers with cargo run --bin ax-flatten -p nautilus-architect-ax (AX_IS_SANDBOX defaults to true). That binary cancels all open orders on the account, then closes every position.

ContributingCopy Anchor Link