AX Exchange

AX Exchange is a centralized and regulated derivatives exchange for traditional underlying asset classes. Operated by Architect Bermuda Ltd. and licensed by the Bermuda Monetary Authority (BMA), AX lists perpetual contracts in production and also exposes dated futures in its sandbox catalog.

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

Overview

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.

Examples

• Python examples
• Rust examples

AX Exchange documentation

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

Products

The production catalog contains perpetual contracts across these venue categories:

The sandbox also lists dated gold contracts such as XAU-2026-SEP and XAU-2026-DEC.

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

Perpetual contracts

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: Initial margin is required to open a position; maintenance margin to keep it 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.

Symbology

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")

Environments

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

Sandbox

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"

Production

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

config = AxExecutionClientConfig(
    environment=AxEnvironment.PRODUCTION,
)

Market data

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

Data types

AX instrument states map to MarketStatusAction as follows:

WebSocket subscription behavior

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, so the adapter enables ticker delivery on the active book stream, opening an L1 stream when no book subscription exists.
• 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 when the required AX level or delivery flags change, or when 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 recovery

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, and AX sends one right 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, echoing 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, then continues at an interval that doubles from one minute to fifteen minutes until a snapshot is accepted. 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.

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 leaves its attempt waiting until a snapshot is accepted, an invalid frame fails it, recovery is cancelled, or the 180-second initial budget ends.

Live recovery validation

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

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 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, and 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 behavior

• 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. Startup mass-status reconciliation traverses its cursor chain, accepts partial pages, and rejects repeated cursors or duplicate order IDs.
• 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 intervals

Orders capability

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.

The official REST place-order and orders WebSocket request schemas contain no order_type or trigger_price field, and 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 types

Execution instructions

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.

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, an order whose reduce-only instruction was dropped from the wire payload was accepted and filled as an ordinary order, which 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 force

The venue deprecates DAY and recommends GTC instead.

Advanced order features

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, so a CancelAllOrders command with order_side set cancels only open orders on that side for the instrument through individual cancel requests. A side-filtered request selects from open orders only, so an inflight (SUBMITTED) order not yet acknowledged by AX survives one.

Position management

Order querying

Account state

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, and 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.

Authentication

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.

Configuration

Environments and endpoints

Data client configuration options

Execution client configuration options

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 credentials

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 notes

• 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 and records the new venue order ID it returns. A modification is rejected locally when it carries a trigger price, which AX has no field for, or when the order has no venue order ID yet.
• Funding rate polling: The data client polls GET /funding-rates per subscribed instrument on funding_rate_poll_interval_mins, requesting a seven-day lookback so a rate is still found across weekends and holidays, and 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.
• Instrument fee rates: Instruments do not carry maker or taker fee rates. An authenticated client still resolves account rates from GET /whoami and fails to connect if that lookup fails. Those rates are not copied onto instruments.
• Fill commissions: Real-time fill events from the WebSocket do not include fee data. A tracked streaming fill leaves commission unset. An untracked fill falls back to a fill report with zero commission. Reconciliation does not replace the commission on a fill that was already applied. The REST /fills endpoint supplies the fee for a fill that was not already applied from the stream. The adapter converts that fee with Money::from_decimal into USD, whose precision is 2, so a sub-cent fee such as 0.012188 is stored as 0.01. A fee that cannot be represented fails the fill-report request 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. Reconciliation requests the most recent seven days of fills; fills older than that are not reconciled.
• 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. 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.

Contributing