Everything Ava serves, and nothing it does not

The loop

A wallet answers whether a transaction is safe to sign. Ava answers a different question: is the agent doing the job it was given. That needs the job written down first.

1. 01

   Session. One request creates a user id. One human owns many agents under it.

2. 02

   Mandate. Objective, capital, constraints, and the conditions that end the position, all agreed before the agent acts.

3. 03

   Evaluation. Ava reads the market itself and tests the conditions, recording what it observed.

4. 04

   Record. Every mandate, refusal and receipt lands on the agent's record, with proven counted apart from claimed.

Base URL and transport

From a terminal or a server the API is https://ava-v4-api.fly.dev. Everything is JSON over HTTPS. There is no websocket and no SSE.

From a browser, use relative paths. This site proxies /v1, /health and /mcp to the API from its own origin, so a page never makes a cross-origin request, never pays for a preflight, and never depends on a second hostname resolving. The API keeps a CORS allowlist for anyone who calls it directly, and a browser on an origin outside that list is blocked before the request leaves it.

Authentication

POST /v1/users/session is open: no CAPTCHA, no email, no wallet popup. It returns a userId that names you and a token that proves you are that user. Send the token as Authorization: Bearer on every other call. It is shown once; Ava stores only its SHA-256 digest and cannot show it again. Agents may also send x-ava-agent-id to scope work to one instance.

A userId in a header, a query string, a request body, or an MCP tool argument is a claim, never identity. Ava compares it with the token and refuses a disagreement with USER_ID_ASSERTION_MISMATCH rather than quietly correcting it, so a client confused about whose capital it is moving finds out before the money does.

Headless callers use an API key bound to one user id server-side (AVA_API_KEYS in userId:key form). There is no key that can act as an arbitrary tenant.

Ownership failures answer 404 rather than 403 throughout. Asking for a mandate or a record that belongs to someone else must not confirm that the id exists.

curl -sS -X POST https://ava-v4-api.fly.dev/v1/users/session \
  -H 'content-type: application/json' \
  -d '{}'

captured 2026-07-29

{
  "ok": true,
  "user": {
    "userId": "usr_96a9bb92c52be687",
    "createdAt": "2026-07-29T12:26:17.051Z"
  },
  "wallets": [],
  "agents": [],
  "token": "ava_st_<32 random bytes, base64url, shown once>",
  "tokenId": "stk_6f0a1c2d3e4b5a69",
  "sessionKind": "created",
  "requestId": "c8728537-7bca-40b3-8be5-289a6f07ff8a"
}

REST surface

These are the endpoints this site uses. The API serves more, and they are documented where they are stable.

Create a mandate

objective is an enum, not free text, and constraints.maxNotionalUsd is a number. Both are the two mistakes the schema rejects most often.

curl -sS -X POST https://ava-v4-api.fly.dev/v1/mandates \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer ava_st_YOUR_TOKEN' \
  -d '{
    "objective": "earn",
    "capital": { "asset": "USDC", "amount": "1000", "chain": "base" },
    "constraints": { "maxNotionalUsd": 500 }
  }'

{
  "ok": true,
  "mandate": {
    "mandateId": "mdt_df43bc9cee6c41aa",
    "userId": "usr_fa1149c27487e34e",
    "portal": "base",
    "name": "earn 1000 USDC (775d1e)",
    "status": "active",
    "objective": "earn",
    "capital": { "asset": "USDC", "amount": "1000", "chain": "base" },
    "constraints": { "maxNotionalUsd": 500 },
    "conditions": [],
    "action": { "type": "paper_plan_lend", "payload": {} },
    "createdAt": "2026-07-29T12:27:59.338Z",
    "updatedAt": "2026-07-29T12:27:59.338Z"
  },
  "nextStep": "Mandate is active. Evaluate with POST /v1/mandates/:id/evaluate (live price when snapshot omitted). MCP: ava_create_mandate / ava_eval_mandate.",
  "requestId": "777c3ad6-9b32-4ca4-a355-3fc4347863e2"
}

Evaluate a mandate

With an exit condition attached, evaluation fetches a live price and records what it saw. Trimmed here to the fields this page discusses; the full response also returns the updated mandate and the matched condition indexes.

curl -sS -X POST https://ava-v4-api.fly.dev/v1/mandates/mdt_b8a740bcf7e1490d/evaluate \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer ava_st_YOUR_TOKEN' \
  -d '{}'

{
  "matched": true,
  "evaluation": {
    "matched": true,
    "reason": "conditions_matched:price_condition_met",
    "observed": {
      "price": 1905.05,
      "priceChangePct": 1.4799914918104407,
      "matchedIndexes": [0]
    },
    "actionDispatched": false
  },
  "snapshot": {
    "price": 1905.05,
    "priceChangePct": 1.4799914918104407,
    "priceChangePct1h": 1.4799914918104407,
    "source": "coingecko",
    "asset": "ETH",
    "observedAt": "2026-07-29T12:28:15.178Z"
  }
}

Read a track record

{
  "ok": true,
  "record": {
    "recordVersion": "ava.agent-record.v1",
    "agentInstanceId": "5f24f968-32a6-4622-87ff-dd5e39259ea7",
    "visibility": "owner",
    "stats": {
      "mandatesHeld": 0,
      "mandatesActive": 0,
      "executionsAttempted": 0,
      "receiptsTotal": 0,
      "receiptsNoProof": 0,
      "receiptsUnconfirmed": 0,
      "receiptsProven": 0,
      "refusalsTotal": 0,
      "refusalsByCode": []
    },
    "verification": {
      "receiptDigest": "sha256(canonicalJson(unsignedReceipt))",
      "mandateHash": "sha256(canonicalJson(extractMandateTerms(mandate)))",
      "provenRule": "receiptsProven counts only receipts whose proofStanding is chain-confirmed"
    },
    "generatedAt": "2026-07-29T12:28:58.164Z"
  }
}

Zero is zero. A new agent has an empty record and Ava does not fill it with sample history.

The mandate object

MCP tools

Ava speaks MCP as JSON-RPC over HTTP at /mcp and /v1/mcp. GET returns the tool list, POST takes tools/list and tools/call. There is no stdio binary to install.

{
  "mcpServers": {
    "ava": {
      "type": "http",
      "url": "https://www.getava.xyz/mcp",
      "headers": {
        "Authorization": "Bearer ava_st_PASTE_YOUR_SESSION_TOKEN"
      }
    }
  }
}

The install guide writes your real session id into this block.

What is actually live

Every chain and venue Ava lists is one row in a capability registry, read live below rather than reproduced from a roadmap. The list is long and most of it will not run today. That is the honest state of the product, so the rows are split by whether you can execute them right now and each one that you cannot says why in plain words.

A row is executable only when three separate things are true at once: implemented means the adapter code exists, apiReachable means a public route on the authenticated API reaches it, and operatorEnabled means the operator has turned it on. Two of three is not a capability. They are kept apart because they are fixed by three different pieces of work, and collapsing them into one word is what made this list unreadable.

The same registry is served as JSON at /capabilities.json, already split into executable and not, with the rule above stated in the payload. Prefer it over parsing the table below: this layout is written for a person reading the page and is not a contract. If you would rather watch the loop run than read about it, the unedited terminal recording is a session, a wallet, a mandate and two real refusals against the live API, with nothing cut.

A mainnet proof is a historical fact about one transaction. It is never permission to execute now. A row that once settled on chain and is switched off today is not a route you can call, and this page will not let the first fact stand in for the second.

The proof that exists is worth naming exactly. A 0.1 USDC supply to the gtUSDCp vault on Base settled in block 49315911, and its receipt was the first to carry proof.standing: chain-confirmed. It is verifiable without a credential. chain-confirmed is not shorthand for a transaction hash existing: Ava decoded the transaction and compared five fields, status, token, amount, sender and recipient, against what the receipt claims. A hash that exists but disagrees returns chain-contradicted, which is treated as worse than no proof at all.

Executable over the authenticated API now

These accept a live execution request today. Everything else on this page does not, whatever its venue is called.

Not executable

Each row names the first thing standing between it and a live call. A dry-run row is not a broken row: it builds a real quote and real calldata against a real venue and then stops, deliberately, before anything is signed.

Refusal codes

Every failure returns { ok: false, error: { code, message, details? }, requestId }. The code is stable and worth branching on. The message is for humans and may change.

Limits

Wallet provisioning is live: every agent wallet is created in its own Turnkey sub-organisation, so one user's growth cannot exhaust another's allowance, and provisioning returns a real address rather than a placeholder.

{
  "ok": true,
  "wallet": {
    "walletId": "763e4194-55bc-43e5-9bdd-160de0763e0c",
    "userId": "usr_c12fb8706494753a",
    "family": "evm",
    "address": "0xAF1e62e11329896cf75540D31ab86CE0490f6387",
    "provider": "turnkey",
    "status": "active",
    "turnkeyWalletId": "63cdf133-2461-5a67-8c2a-df6c7fa918d7",
    "turnkeyOrganizationId": "a198bc63-329d-45ac-b663-a36333b6d6a8",
    "createdAt": "2026-07-29T13:57:49.906Z"
  },
  "nextStep": "Wallet is active and ready for policy-gated signing.",
  "requestId": "77400897-3b68-458e-bcdb-8adaf8c33132"
}

• The CoW broker runs in quote-only mode, so a swap returns a draft to inspect rather than a fill.
• Morpho lend on Base has signed and settled once on mainnet, and that single receipt is the whole of Ava's execution history. Every other route above stops at unsigned calldata.
• agentId on POST /v1/users/me/agents must exist in the catalog. An arbitrary id is refused with UNKNOWN_AGENT, so byo-external is the slot for an agent Ava does not host.
• Agent records are owner-only until the owner changes visibility, and a stranger's read is answered identically to a record that does not exist.

Ready to run it? The install guide makes every call on this page from your browser.