Intent

What an agent asks for.

An intent is what an agent asks for. One wire form is shared by every binding: the REST endpoints POST /v1/check and POST /v1/authorize, and the MCP tools a2m_check and a2m_place_order all take the same object.

Fields

Field	Type	Required	Notes
`intent_id`	string	yes	The caller’s idempotency key. Repeating it with the same body returns the same result; repeating it with a different body is `A2M_IDEMPOTENCY` (409).
`venue`	string	yes	Venue name, for example `hyperliquid` or `sim`.
`instrument`	string	yes	The venue’s own symbol, for example `ETH` on Hyperliquid perpetuals or `BTC/USDT`.
`side`	string	yes	`buy` or `sell`.
`qty`	decimal string	yes	Must be positive. At most 6 decimal places; more is a 400 (`APEX_4011`), never rounded.
`order_type`	string	no	`limit` (default) or `market`.
`limit_price`	decimal string	for `limit`	At most 6 decimal places; more is a 400 (`APEX_4011`), never rounded.
`time_in_force`	string	no	`gtc` (default), `ioc`, `fok`, `post_only`, `day`. See below.
`reference_price`	decimal string	see notes	The agent’s view of the price. At most 6 decimal places. Ignored when the authorizer prices intents itself from a quote source.
`reference_price_ts`	RFC 3339 string	see notes	Time of the reference price. A missing, unparseable, stale or future reference fails closed (`A2M_STALE_PRICE`). The reference implementation’s default maximum age is 10 seconds.
`reduce_only`	boolean	no	Only shrink an existing position.
`extended_hours`	boolean	no	Default `false`. When `true`, the order may also trade in the market’s pre- and post-market sessions. Only a `limit` order with `day` or `gtc` is accepted; any other combination is a 400 (`APEX_4011`). See Sessions and calendars.

The agent does not send a client_order_id. The authorizer mints one when it issues an executable decision. See Orders and execution reports.

Time in force

The protocol values are lower case. Common aliases are accepted and normalised (alo, add_liquidity_only and postonly become post_only; good_till_cancel becomes gtc; immediate_or_cancel becomes ioc; fill_or_kill becomes fok). Any other value is a 400 error, never a silent default.

Value	Meaning
`gtc`	Good till cancelled
`ioc`	Immediate or cancel: fill what crosses now, cancel the rest
`fok`	Fill or kill
`post_only`	Add liquidity only; rejected if it would cross
`day`	Expires at the end of the venue’s trading day

The decision fixes the time in force and the order type; nothing downstream may change them. A venue that does not support a combination MUST refuse the order before sending it (A2M_TIME_IN_FORCE or A2M_ORDER_TYPE). It MUST NOT downgrade, coerce or substitute a supported value.

The default time_in_force is gtc. A market order that omits it is therefore gtc, and is refused on any venue that does not accept market plus gtc. The agent SHOULD set a time in force the venue accepts for that order type. For a market order, Hyperliquid accepts ioc and Alpaca accepts day.

Sessions and calendars

The authorizer judges session against the instrument’s calendar, in that calendar’s time zone.

Regular sessions are the market’s ordinary trading hours. An intent with extended_hours false is accepted only inside a regular session on a trading day (A2M_MARKET_CLOSED otherwise).
Extended sessions are the pre- and post-market periods, when the market has them. US equities in the reference data use 04:00–09:30 and 16:00–20:00 Eastern Time (17:00 on early-close days).
Holidays are closed for every session.
Early closes cut a trading day short: regular sessions end at the early close, and extended sessions end at the early extended close. The gap between the early regular close and the usual post-market start stays closed; the authorizer fails closed rather than guess.
A market with no extended sessions (for example a 24-hour crypto venue) refuses extended_hours true (A2M_EXTENDED_HOURS). If both regular and extended sessions are closed, the refusal is A2M_MARKET_CLOSED.
A missing or unreadable calendar fails closed (A2M_MARKET_CLOSED).

Until a venue adapter can pass the extended_hours flag through, the executor refuses an extended-hours decision before sending (A2M_EXTENDED_HOURS, 422). It MUST NOT silently send the order as a regular-hours order.

Example

{
  "intent_id": "demo-0001",
  "venue": "hyperliquid",
  "instrument": "ETH",
  "side": "buy",
  "qty": "0.01",
  "order_type": "limit",
  "limit_price": "2000",
  "time_in_force": "gtc"
}