How Ava is built

What Ava is

Ava is the execution layer for agents that do DeFi. A coding agent can describe what it wants done with money, but it holds no key, no signer and no RPC. Ava holds those, and it holds them behind rules the agent cannot change: a mandate the user agreed to, a policy envelope, a registry of what is actually executable, and a receipt that separates what was claimed from what a chain confirmed.

The whole system is one spine, and every live spend walks it in order:

1. 01

   Intent. An agent names an action through MCP or REST: supply 5 USDC to Morpho on Base, under mandate mdt_…

2. 02

   Authority. The caller's bearer token must carry the spend audience, and the mandate must belong to that caller.

3. 03

   Executability. The capability registry decides whether that kind, chain and venue may run on this deployment.

4. 04

   Preview. Ava reads real chain state and builds the exact action. Its hash is what a human approves.

5. 05

   Gates. Mandate gate, policy gate, a single-flight execution claim and a durable budget reservation.

6. 06

   Signature. Only now is a signer built. Turnkey signs with the user's own key, in the user's own sub-organization.

7. 07

   Settlement. Ava broadcasts, waits for the chain, and compares what settled with what was authorised.

8. 08

   Receipt. A hash-chained receipt is written. Only a chain-confirmed settlement may be reported as a fill.

System context

Every caller reaches the API through the getava.xyz origin. Agents speak MCP as JSON-RPC over HTTP; browsers and the CLI also use REST. The site forwards /v1, /mcp and /health to the API on Fly.io, which is the only component that talks to Postgres, Turnkey and the chains.

flowchart LR
  subgraph callers["Callers"]
    direction TB
    agent["Coding agent<br/>Claude Code · Cursor · Codex"]
    claw["OpenClaw skill"]
    cli["npx @getava-xyz/connect"]
    human["Human in a browser"]
    verifier["Third-party verifier"]
  end

  subgraph edge["getava.xyz · Vercel"]
    direction TB
    site["Next.js site<br/>docs · install · dashboard"]
    console["Operator console<br/>Vite SPA at /console"]
  end

  subgraph core["Ava API · Fly.io"]
    direction TB
    api["api-worker<br/>Hono · REST + MCP"]
    sched["Scheduler<br/>same process"]
  end

  pg[("Postgres<br/>ledger · tenancy · claims")]
  turnkey["Turnkey<br/>per-user sub-org keys"]
  chains["EVM + Sui RPC<br/>Base · Monad · Avalanche · BNB · Arbitrum"]
  venues["Venue + data APIs<br/>Kyber · 0x · LI.FI · CoW · Jupiter<br/>CoinGecko · DefiLlama"]
  llm["OpenRouter<br/>optional, copilot only"]

  agent -- "MCP over HTTP" --> site
  claw -- "MCP over HTTP" --> site
  cli -- "MCP + REST" --> site
  human --> site
  human --> console
  verifier -- "GET /v1/receipts/:hash/verify" --> site
  site -- "rewrite /v1 /mcp /health" --> api
  console -- "/v1 via site origin" --> api
  api --> pg
  sched --> pg
  api -- "sign" --> turnkey
  api -- "read · broadcast · confirm" --> chains
  sched -- "receipt anchors" --> chains
  api -- "quotes · prices · yields" --> venues
  api -.-> llm

The proxy exists for a concrete reason recorded in apps/site/next.config.ts: two of the domain’s four nameservers answered NXDOMAIN for api.getava.xyz, so roughly half of visitors could not resolve the API host. Serving the API from the site’s own origin removed that dependency and the CORS preflight with it.

Deployables

The monorepo builds eight things that ship. Only one of them holds state or keys. Two that look like services by name, agent-service and execution-worker, are libraries the API imports and runs in its own process.

Stack

API worker layers

Inside the API there are two transports and one implementation. REST routes live in apps/api-worker/src/routes; the MCP server in lib/mcp.ts dispatches each tool to the same functions those routes call. This is deliberate: a second implementation behind MCP is how the mandate gate was once enforced over HTTP and skipped over MCP.

flowchart TB
  subgraph transport["Transport"]
    direction LR
    rest["REST routes<br/>routes/*.ts"]
    mcp["MCP JSON-RPC<br/>lib/mcp.ts · 29 tools"]
    rest ~~~ mcp
  end

  mw["Middleware chain<br/>CORS · request id · logging · auth · spend audience · idempotency"]

  subgraph domain["Domain"]
    direction LR
    tenancy["Sessions · agents · wallets<br/>@ava/tenancy"]
    mandates["Mandates · standing envelopes<br/>@ava/mandates"]
    planner["Intent + workflow planner<br/>@ava/intent"]
    copilot["Copilot<br/>lib/copilot.ts"]
    tenancy ~~~ mandates ~~~ planner ~~~ copilot
  end

  subgraph gates["Gates, in the order a spend meets them"]
    direction LR
    registry["Capability registry<br/>implemented · apiReachable · operatorEnabled"]
    mgate["Mandate gate"]
    policy["Policy gate<br/>@ava/policy"]
    claim["Execution claim<br/>single flight"]
    budget["Policy reservation<br/>daily + exposure"]
    registry --> mgate --> policy --> claim --> budget
  end

  subgraph exec["Execution"]
    direction LR
    lend["Lend executors<br/>Morpho · Aave · Compound · Suilend"]
    swap["Swap venues<br/>Kyber · 0x · Uniswap v3 · LI.FI"]
    bridge["Across bridge"]
    lend ~~~ swap ~~~ bridge
  end

  subgraph ports["Ports"]
    direction LR
    signer["Turnkey signer"]
    rpc["RPC transport"]
    ledger["Receipt ledger<br/>chain + sign at write"]
    signer ~~~ rpc ~~~ ledger
  end

  transport --> mw --> domain
  domain --> gates --> exec --> ports

What each layer owns

• Transport. Parses and validates input with zod, resolves the portal, and returns the shared envelope { ok, …, requestId }. MCP narrows what tools/list advertises to an 18-tool default (opt in to more with ?toolsets=) because Cursor caps a user at 40 tools across all servers; tools/call still accepts every tool by name.
• Domain. Tenancy maps a user to agent instances and wallet families (evm, solana, sui). Mandates hold objective, capital, constraints and exit conditions, and are hashed over their terms only, so status changes never break a receipt’s binding.
• Gates. Each gate answers a different question: may this kind run here, does the mandate allow it, does policy allow it, has it already been claimed, and is there budget left today. They are ordered so a refused request never consumes a reservation.
• Execution. One executor per venue family, each with its own settlement check. Aave re-reads the Pool’s own Supply event; Compound reads Comet.balanceOf in the settling block; Morpho reads the ERC-4626 position pinned to the confirmed block.
• Ports. The ledger wrapper chains and optionally signs every receipt at the storage boundary, so no writing path can forget to.

Request pipeline

Every request crosses the same middleware chain, registered in apps/api-worker/src/app.ts. Authentication is deny-by-default: a short allowlist of public routes answers anonymously and everything else needs a credential.

flowchart TB
  req(["HTTP request"]) --> pre["CORS allowlist · inject stores<br/>request id · structured log"]
  pre --> auth{"Credential presented?"}
  auth -- "invalid" --> e401a["401 UNAUTHORIZED"]
  auth -- "none, private path" --> e401b["401 AUTH_REQUIRED"]
  auth -- "valid API key or session token" --> principal["Principal set<br/>userId · kind · audience"]
  auth -- "none, public path" --> spend
  principal --> spend{"Live-spend path?"}
  spend -- "audience is not spend" --> e403["403 SPEND_CREDENTIAL_REQUIRED"]
  spend -- "allowed" --> idem{"Mutation that needs<br/>an Idempotency-Key?"}
  idem -- "key missing" --> e422["422 IDEMPOTENCY_KEY_REQUIRED"]
  idem -- "key seen before" --> replay["Replay the cached 2xx"]
  idem -- "proceed" --> route["Route handler"]
  route --> envelope["Any thrown ApiError becomes<br/>ok false · error · requestId"]

Public routes

GET /health, GET /v1/capabilities, GET /v1/portal, GET /v1/portal/catalog, POST /v1/users/session, POST /v1/users/session/device, /mcp and /v1/mcp (each tool authenticates itself), GET /v1/agents/:id/record (handler still hides owner-only records) and GET /v1/receipts/:ref/verify.

Live-spend routes

POST /v1/lend/execute, /v1/workflows/execute, /v1/copilot/approve, /v1/execute/:id and /v1/bridge/execute refuse any principal that cannot spend. Over MCP, the same rule is applied per tool to ava_lend_execute and ava_approve_execute. The credential model is on Data and trust.

Package graph

The 49 workspace packages fall into six groups. Dependencies point downward toward a small set of shared contracts, which is what lets an adapter be tested in isolation and replaced without touching the API.

flowchart TB
  api["apps/api-worker"]
  libs["apps/agent-service · apps/execution-worker<br/>in-process libraries"]

  gov["Authority and policy<br/>mandates · policy · wallet-policy<br/>capability-registry · condition-engine · automations"]
  ident["Identity<br/>tenancy · portal · agent-record"]
  venues["Venue adapters<br/>adapter-morpho · aave · compound · suilend<br/>adapter-kyber · 0x · uniswap · lifi · jupiter<br/>adapter-bridge · broker-router · broker-cow"]
  infra["Infrastructure<br/>ledger · ledger-postgres · wallet-turnkey"]

  contracts["Shared contracts<br/>intent · execution-contract · verifiability"]

  api --> libs
  api --> gov
  api --> ident
  api --> venues
  api --> infra
  libs --> gov
  libs --> venues
  libs --> infra
  gov --> contracts
  venues --> contracts
  infra --> contracts
  ident --> contracts

Boot and runtime

apps/api-worker/src/runtime.ts builds the app from the environment. Postgres mode applies every schema before serving and hydrates the mandate cache, so the API never answers from a view that is missing mandates the database holds. Asking for Postgres without a DATABASE_URL is a boot error, not a fallback to memory.

flowchart TB
  start(["index.ts → createRuntimeAppFromEnv"]) --> mode{"AVA_LEDGER_MODE"}
  mode -- "in_memory" --> mem["In-memory stores<br/>developer machine"]
  mode -- "postgres" --> url{"DATABASE_URL?"}
  url -- "missing" --> fail["Boot error, no fallback"]
  url -- "set" --> schema["Apply every schema idempotently<br/>then hydrate the mandate cache"]
  schema --> wire
  mem --> wire["createApp with Turnkey provisioner, CoW transport,<br/>API keys, auth mode, operator token, CORS"]
  wire --> serve["Serve on PORT, then start the scheduler<br/>only if AVA_SCHEDULER_ENABLED=true"]

The scheduler

lib/scheduler.ts runs inside the API process when AVA_SCHEDULER_ENABLED=true, which is why the Fly machine is never auto-stopped. Every 60 seconds it evaluates active automations and mandates against a live CoinGecko price and evaluates due standing envelopes. A separate, slower timer publishes receipt chain heads to Base when an anchor key is configured.

Infrastructure

Production is one always-on Fly.io machine in Singapore beside its managed Postgres, plus two Vercel projects. The /health check reports the ledger mode and dependency modes, and is what Fly polls every 30 seconds.

flowchart TB
  dns(["www.getava.xyz"])

  subgraph vercel["Vercel"]
    direction LR
    siteapp["apps/site<br/>Next.js 16"]
    webapp["apps/web<br/>Vite console"]
  end

  subgraph fly["Fly.io · ava-v4-api · region sin"]
    direction LR
    machine["api-worker container<br/>shared-cpu-1x · 1 GB · min 1, never auto-stopped"]
    flypg[("Managed Postgres<br/>same region")]
  end

  subgraph ext["External"]
    direction LR
    tk["Turnkey API"]
    rpcs["Chain RPC endpoints"]
    apis["Venue and price APIs"]
  end

  dns --> siteapp
  siteapp -- "/console · /workspace · /assets" --> webapp
  siteapp -- "/v1 · /mcp · /health" --> machine
  machine --> flypg
  machine --> tk
  machine --> rpcs
  machine --> apis

The repository also carries a root vercel.json that serves the same Hono app as a Vercel function through api/, and a railway.toml for the Dockerfile. Both boot the same createRuntimeAppFromEnv. The README and the site’s proxy default name Fly.io as production; whether the other two are deployed anywhere today cannot be determined from the repository.

External integrations

Configuration

Every setting is read from the environment at boot. The defaults are the safe ones: auth is required unless a developer opts out, operator controls are disabled without a token, and receipts are recorded as unsigned rather than signed with an absent key.

Where to go next

• Core workflows walks onboarding, a live lend, a multi-leg plan, standing authorization and verification as sequence diagrams.
• Data and trust covers credentials, what is stored where, the receipt model, and the known gaps.
• API and MCP reference lists the endpoints, the live MCP tool list, and which registry rows execute today.