Agent API

Base URL: https://hartiilabs.com/api/agent. Every response is Cache-Control: no-store. Builders never sign and never hold a key — they return calldata for AgentVault.execute(...), which the caller signs itself (see MCP setup for the reference implementation).

#Reads

• GET /manifest — tool list, contract addresses, caps, revert reasons, the Fish/Fly randomness recipe and eligibility rules.
• GET /vault/:addr — owner, agent, caps, spent/remaining today, paused, QUAI balance, holdings + P&L (BigInt, wei), recent AgentAction activity.
• GET /quote?token=&side=buy|sell&amountWei= — a bonding-curve quote. ?pool=1&tokenIn=&tokenOut=&amountWei=&router= quotes a HartiiSwap pool instead.

#Builders

POST /build/{buy,sell,launch,swap,addLiquidity,removeLiquidity,launchNft} with { vault, ...action fields }. Every response has the shape:

{
  "to": "0x… (the vault)",
  "data": "0x… (steps[0]'s calldata)",
  "value": "0",
  "steps": [ { "to": "0x…", "data": "0x…", "value": "0", "kind": "approve|buy|sell|…", "summary": "…" } ],
  "summary": "…",
  "warnings": ["…"]
}

steps holds every on-chain call in order for actions that need an approval first (sell, addLiquidity, removeLiquidity, an ERC-20-leg swap) — each entry is independently a complete, signable execute(...) calldata. to/data/value at the top level always mirror steps[0]. Every execute(...) calldata a builder returns carries value: "0": agent calls never send QUAI straight to an arbitrary address — an approve step is always zero-value, and a buy's QUAI travels with AgentVault.execute's own value argument, not through calldata.

#Games

• POST /fish/cast { vault } — draws one token from the eligible pond and returns a small buy.
• POST /fly/route { vault, stops? } — draws an ordered route (2-6 stops, default 3) and returns a buy for the first stop.
• POST /fly/next { vault, routeId } — sells the current stop and buys the next one (or just sells, on the last stop).

See Games for the randomness recipe and eligibility rules.

#Rate limits

Every route here is rate-limited per IP (60s sliding window). A 429 includes Retry-After-style guidance in its error string — back off and retry.