How a request flows

For AI agents: the documentation index is at llms.txt (full corpus: llms-full.txt). A markdown source for this page is /sandboxes/how-it-works.md.

An agent never builds, signs or sends a transaction itself. It names an action and its arguments; Arete does the rest, and refuses anything your rules don’t allow before a signature exists.

Agent (MCP tools / a4 CLI)
  │  its own API key mints a short-lived sandbox token
  │  (only while you grant it access; one scope per granted action)
  ▼
Arete sandbox API
  1. Grant check     is this action granted to this agent?
  2. Build           encode the named instructions from each program's IDL,
                     fill fixed, wallet and derived accounts
  3. Guard           every instruction and inner call against your rules:
                     programs, instructions, spend limits, destinations,
                     authority changes
  4. Trial run       simulate; a transaction that would fail is refused
  5. Sign and send   only now does the wallet's key sign
  6. Record          the action, its outcome, decoded events and balance changes
  ▼
Solana

Authentication

The agent uses its own account’s secret API key (ARETE_API_KEY, or its a4 login). With it, the MCP server lists the sandboxes the agent has been granted and picks the one a call is for: the call’s sandbox argument, else the one chosen with sandbox_select, else the only active sandbox granted. It then exchanges the key for a short-lived token for that one sandbox. The exchange succeeds only while you grant that agent access, and the token carries one scope per action you granted. When the token expires it is minted again; when you revoke the grant, the next mint fails and the agent stops.

Neither the API key nor the token is ever returned to the agent in a tool result.

Preview and invoke run the same checks

sandbox_preview runs steps 1 to 4 and stops: nothing is signed, sent or recorded. It returns pass with what the wallet would lose (outflowLamports, the network fee included) and the transaction it built, or the refusal. sandbox_invoke runs every step.

Because both run the same checks, an agent can find out whether an action passes, and what it costs, before committing to it.

Exactly once

Every sandbox_invoke carries an idempotency key, the agent’s own or a generated one. A key never runs twice. If a call times out, the agent sends the same request with the same key, which returns the original result (replayed: true), or looks the action up with sandbox_action. A slow network never turns into a double trade.

Refusals

A refused action names the code, the rule that refused (such as program-allowlist, instruction-allowlist, outflow-cap or session-grant), what triggered it, whether the same request can succeed later (retryable) and what to do (hint). Refusals are recorded in the history too. See Errors and refusals.

What the agent can see

Reads go through the same token: the wallet’s status, the rules, holdings and history. Program reads and live views are the sandbox’s wider read surface, scoped to the programs in its rules. See Read scope.