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.

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.

Example

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