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 coding 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.

Write this to ~/.cursor/mcp.json for every project, or .cursor/mcp.json for one.

mcp.json

{
  "mcpServers": {
    "ava": {
      "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.

family

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.

objectivecapital.assetcapital.amountcapital.chainconstraints.maxNotionalUsd

portal (derived)

base

Attach an exit condition

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.

condition assetcomparatorthreshold (usd)

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.