---
title: "History, holdings and audit"
description: "Read every action a sandbox ran, refusals included, and what it holds now, from the agent's tools or the a4 CLI."
editUrl: true
head: []
template: "doc"
sidebar: {"hidden":false,"attrs":{}}
pagefind: true
draft: false
---

> For the complete documentation index optimized for AI agents, see [llms.txt](https://docs.arete.run/llms.txt) or [llms-full.txt](https://docs.arete.run/llms-full.txt). A markdown version of this page is available at [/sandboxes/history.md](https://docs.arete.run/sandboxes/history.md) or by sending `Accept: text/markdown`.
Every action an agent asks for is recorded, whether it landed, failed or was
refused. The agent can read that record, and so can you through the CLI.
Both reads are read-only.

## From the CLI

```bash
a4 sandbox list                            # granted sandboxes; * marks the one in use
a4 sandbox use <id or name>                # choose one for this folder
a4 sandbox history                         # newest first, 20 per page
a4 sandbox history --status landed --since 24h
a4 sandbox history --program Pump.fun --all --json
a4 sandbox holdings
a4 sandbox rules show
```

```text
Sandbox 6f1c2c43-6d3c-4a51-9b8e-0e3c1e2a7b10  history, newest first

  2026-11-12 10:00:00  landed    Pump.fun.buy  -0.105005 SOL, +1234.5 7xKX…gAsU  5Kt3…6uHq
      events: TradeEvent ×2
  2026-11-12 09:58:30  rejected  Pump.fun.sell
      sandbox-guard-trial-failed

More: a4 sandbox history --cursor eyJpZCI6ImEyIn0
```

| Flag                   | Meaning                                                                                                           |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `--sandbox <id\|name>` | Another sandbox, for this command only (default: the one chosen with `a4 sandbox use`, else the only one granted) |
| `--limit <n>`          | Actions per page, 1 to 100                                                                                        |
| `--cursor <c>`         | Carry on from a previous page                                                                                     |
| `--status <s>`         | `landed`, `failed`, `rejected`, `sent`, …                                                                         |
| `--program <p>`        | Only actions that called this program, by id or name                                                              |
| `--mint <m>`           | Only actions that moved this token mint                                                                           |
| `--since <t>`          | RFC 3339, or an age such as `30m`, `24h`, `7d`                                                                    |
| `--all`                | Read every page                                                                                                   |
| `--raw`                | Keep each action's raw parsed transaction in `--json` output                                                      |

On records that carry them, a row also shows the network fee
(`networkFeeLamports`, already part of the SOL change) and the guard
pipeline:
`-0.105005 SOL, network fee 0.000005 SOL, +1234.5 7xKX…gAsU  5Kt3…6uHq  guard execute-v1`.
The fee is left out while it is null (the landing not read yet) and on older
records.

The filters are applied by the client to the pages it reads. A filtered read
keeps reading pages until enough actions match (up to 10 pages per call),
then prints the cursor to carry on from.

## From the agent

`sandbox_history` takes the same filters (`cursor`, `limit`, `status`,
`program`, `mint`, `since`, `includeRaw`), and `sandbox_holdings` takes
`includeRaw`.

## What an action records

- its time, status and signature;
- the programs and decoded instructions;
- the Anchor events the programs emitted, decoded against each program's IDL
  (an event that doesn't decode keeps its bytes and the reason);
- the SOL and token changes, and `outflowLamports`: everything that left the
  wallet, the network fee included (`networkFeeLamports` alone, null until
  the landing is read);
- the guard pipeline that checked it (`guardPipeline`, such as `execute-v1`;
  null or absent on older actions and on actions that never reached the
  guard);
- the accounts it touched; and
- with `--raw` or `includeRaw`, the parsed transaction with balances before
  and after.

Refusals record the `code` and rule that refused.

## Holdings

Holdings list SOL, each token (with `acquiredBySandbox` for tokens the
sandbox bought, which it may always sell) and program positions, as of a
slot. Lending and liquidity positions show as labelled raw accounts for now,
not decoded balances.

## Caveats

Actions from early in the alpha may show fewer details than newer ones.