Intent

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.
order_type	string	no	limit (default) or market.
limit_price	decimal string	for limit
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. 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.

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; nothing downstream may change it. A venue that does not support a value refuses the order rather than downgrading it (A2M_TIME_IN_FORCE).

Example

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