Venue adapter contract

Note

You are reading specification v0.3, a superseded draft. Current: v0.4. Earlier drafts: v0.2, v0.1. See the changelog.

An executor talks to venues through adapters. In the reference implementation this is a gRPC service, Venue; every request names a venue, and one adapter process may serve several. The adapter decides nothing.

Operations

Operation	Contract
Health	Is the venue usable now (credentials loaded, venue reachable)? Checked before a send.
Capabilities	Order types with the times in force allowed for each; per-instrument lot_size, tick_size, max_price_decimals, max_price_sig_figs, min_qty, min_notional, quote_currency; reduce_only support; network (for example testnet).
Quote	Read-only price for an instrument.
Submit	Send one order. Outcomes: ack (with status and any fills), reject (definitive, nothing placed), timeout (ambiguous: the venue may have it; the order moves to unknown), not_configured (definitive local failure).
Cancel	Cancel by client order id. The executor confirms against a snapshot.
Snapshot	Status and fills for watched client order ids, ids the venue does not know (missing_ids), external fills, and complete. An incomplete snapshot never counts as missing.
Balances	Cash for the account, or supported=false.
ListInstruments	Every instrument the venue lists, normalized: symbol, display name, asset_class, product_class, quote_currency, lot_size, tick_size, max_price_decimals, shortable, fractionable, status (active, halted, delisted); or supported=false. Read-only. The authorizer syncs its instrument list from it and marks a symbol the venue stops listing as delisted.

Rules for every adapter

• The client order id is the idempotency key and the reconciliation key. It is minted by the authorizer (co_ plus 32 hex characters) and never reused. If the venue needs a different format, derive it deterministically.
• Never round or change a signed price or quantity. If the venue cannot accept it, reject. A protective limit for a market order is computed only on venues that have no native market order and need one (for example Hyperliquid, which sends an IOC limit at the protect price). The protect price is the signed reference moved by the signed collar, rounded toward the safe side. A venue with native market orders (for example Alpaca) receives a plain market order; the guard there is the authorizer’s pre-send checks on the signed reference price (staleness, collar, and the notional and buying power reserved at reference plus collar).
• When unsure whether an order reached the venue, answer timeout, not reject.
• Map, never downgrade. Translate a time in force or order type to the venue’s spelling, or reject it. Never coerce an unsupported combination into a supported one, and never declare a combination the venue would itself coerce.
• Money is a decimal string on the wire.
• Test hooks belong in a separate service, not in the venue contract.

Example: Hyperliquid

The first venue with a working adapter is Hyperliquid perpetuals, used on testnet. The Hyperliquid market page covers how to connect, the order path, field mapping, supported types and how failures are handled.

• The executor’s adapter signs with a Hyperliquid API wallet that the user’s main account approved. An API wallet can trade but cannot withdraw. The agent never sees it.
• client_order_id maps to Hyperliquid’s cloid as 0x followed by the first 16 bytes of sha256(client_order_id).
• Time in force: gtc to Gtc, ioc to Ioc, post_only to Alo. fok and day are refused. Market orders must be ioc and are sent as an IOC limit at the protect price.
• Precision: size is a multiple of 10^-szDecimals; prices have at most 5 significant figures (integers always allowed) and at most 6 - szDecimals decimals for perpetuals. Minimum order value is 10 USDC.
• Risk treatment: these perpetuals are handled like spot (long only, full notional reserved, no funding or liquidation model). The adapter sets 1x leverage before the first order on each coin and rejects the order if it cannot.

Adding a venue

1. Implement the operations above, with unit tests against a fake client and no network.
2. Keep it off by default behind configuration; secrets go only to the adapter’s environment.
3. Seed reference data for the protected unit (order types, times in force, min and max notional) and the calendar. Instruments (lot, tick, quote currency, status) come from ListInstruments.
4. If the product class is new, add its risk treatment first. Until then the authorizer fails closed (A2M_UNSUPPORTED_PRODUCT).
5. Check quotes and metadata against the venue’s test network before any order.