Ava
Connect your agent

installation guide

Put your agent under a mandate

Every step on this page is a request. The buttons send it from your browser to the production API and print exactly what comes back, including the refusals. Nothing is illustrated.

api
ava-v4-api.fly.dev
auth
bearer token
mcp
/mcp, http json-rpc

Reading rather than installing? The reference lists every endpoint and MCP tool, and start covers the other two ways in.

step 01not run

Get a session

A session is a user id plus a bearer token, and there is still no signup, no email, and no wallet popup. The id names you; the token proves you are that user, and every later call in this guide sends it as Authorization: Bearer. The token is shown once and stored only in this browser. One human can own many agents under the same id.
terminal
curl -sS -X POST https://ava-v4-api.fly.dev/v1/users/session \
  -H 'content-type: application/json' \
  -d '{}'
Runs the request above from this browser.
step 02not run

Connect your AI agent

Ava speaks MCP over HTTP at https://www.getava.xyz/mcp. The caller is whoever the bearer token resolves to, server-side, and a userId in tool arguments naming anyone else is refused rather than honoured. Register the agent first so its work lands under its own instance id.
Finish step 1 first: this call needs a session.

One command writes HTTP MCP config for Claude Code, Cursor, and Codex. It does not print the session token. The model never signs and never sets policy.

terminal
npx @getava-xyz/connect

Equivalent manual add:

terminal
claude mcp add --transport http ava https://www.getava.xyz/mcp \
  --header "Authorization: Bearer ava_st_PASTE_YOUR_SESSION_TOKEN"

Prefer a file you can commit with the repo? Write this to .mcp.json at the project root.

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

The header above still holds a placeholder. Run step 1 and it fills with your real session id.

step 03optionalnot run

Provision an agent wallet

A mandate can be written and evaluated without a wallet. A wallet is what lets the agent hold and move real capital later. Ava provisions it in a Turnkey enclave and the key never reaches this page, your agent, or disk. If the session already has one, it is shown above rather than provisioned again.
step 04not run

Set a mandate

A mandate is the agreement the agent is held to: what the capital is for, how much of it may move, and the condition that ends the position. It is written before the agent acts, so afterwards there is something to check the agent against.
portal (derived)

base

Without one, step 5 has nothing to test and answers no_conditions. With one, the evaluation pulls a live price for the asset you name.

terminal
curl -sS -X POST https://ava-v4-api.fly.dev/v1/mandates \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer ava_st_PASTE_YOUR_SESSION_TOKEN' \
  -d '{"portal":"base","objective":"protect","capital":{"asset":"USDC","amount":"500","chain":"base"},"constraints":{"maxNotionalUsd":500},"conditions":[{"asset":"ETH","metric":"price","comparator":"lt","threshold":2000}]}'
Finish step 1 first: this call needs a session.
step 05not run

Verify

Evaluation is the part that makes the mandate more than a note. Ava reads the market itself, tests the condition, records the outcome on the mandate, and returns what it saw. Nothing is executed here.
terminal
curl -sS -X POST https://ava-v4-api.fly.dev/v1/mandates/mdt_PASTE_YOUR_MANDATE_ID/evaluate \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer ava_st_PASTE_YOUR_SESSION_TOKEN' \
  -d '{}'
Create a mandate in step 4 and this button targets it.