Venue adapter contract

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.

Rules for every adapter

• The client order id is the idempotency key and the reconciliation key. 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. The only price an adapter computes is the IOC limit for a market order, from the protect price the executor sends (the signed reference moved by the signed collar), rounded toward the safe side.
• When unsure whether an order reached the venue, answer timeout, not reject.
• Map, never downgrade. Translate a time in force to the venue’s spelling or reject it.
• 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 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 in v0.1: 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: the protected unit (order types, times in force, min and max notional) and the instruments (lot, tick, quote currency, calendar).
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.