# Agents buy the same way.

An Annon file is an ordinary URL. It answers with HTTP 402 and its offers; an agent with a wallet pays, receives the key and opens the file, with no account and no person in the loop.

## Three ways in

### Command line

For any agent with a shell. `--json` prints one JSON line and turns off prompts. Needs Node.js 22.22.2 or newer.

`npm install -g @defdone/annon@alpha` · [CLI reference](/docs/cli.md)

### Local MCP server

For MCP clients. Tools: `annon_share`, `annon_sell`, `annon_buy`, `annon_open`, `annon_verify`, `annon_recover`, `annon_budget`, `annon_status`, `annon_shops`, `annon_catalog`.

`npx -y @defdone/annon-mcp@alpha` · [MCP server reference](/docs/mcp.md)

### Skill

A short instruction file an agent reads once, then drives the command line on its own, including when to wait and never pay twice.

`skills/annon/SKILL.md` · [Read the skill](/docs/skill.md)

## The owner stays in charge

The owner, not the agent, sets the contract it trusts, the endpoints it reads, the most it may pay per file and per day, and the directory it may read and write. A tool call or an offer cannot change them. Keys come from a file or the environment and never appear in the agent's output.

The client configuration starts the server. The owner writes the configuration file it reads (`ANNON_CONFIG`), with the fields in What the owner sets, and keeps the wallet key and the backup secret (`ANNON_BACKUP_SECRET_FILE`) in files only the owner controls. [Step by step in the agents guide](/docs/agents).

```json
{
  "mcpServers": {
    "annon": {
      "command": "npx",
      "args": [
        "-y",
        "@defdone/annon-mcp@alpha"
      ],
      "env": {
        "ANNON_CONFIG": "/absolute/annon-agent.json",
        "ANNON_BACKUP_SECRET_FILE": "/absolute/private/backup-secret"
      }
    }
  }
}
```

| Setting | Meaning |
|---|---|
| `contractId, network, nearRpc, baseRpc, relayer` | The deployment. A tool call cannot supply them. |
| `trustContract` | Set by the owner after reviewing the contract. |
| `maxPrice, dailyBudget` | The most the agent may pay per file and per UTC day, in USDC. |
| `workDir` | The only directory a tool may read or write. |
| `allowedResources` | Optional list of URLs the agent may buy from. |

[Full owner configuration in the MCP server reference](/docs/mcp) · [CLI configuration](/docs/cli)

## Connect your client

Replace the two paths with the configuration file and the backup secret the owner created. The server runs locally over stdio.

Claude Code (shell):

```sh
claude mcp add annon --env ANNON_CONFIG=/absolute/annon-agent.json --env ANNON_BACKUP_SECRET_FILE=/absolute/private/backup-secret -- npx -y @defdone/annon-mcp@alpha
```

Cursor (.cursor/mcp.json, the same mcpServers block as Claude Desktop):

```json
{
  "mcpServers": {
    "annon": {
      "command": "npx",
      "args": [
        "-y",
        "@defdone/annon-mcp@alpha"
      ],
      "env": {
        "ANNON_CONFIG": "/absolute/annon-agent.json",
        "ANNON_BACKUP_SECRET_FILE": "/absolute/private/backup-secret"
      }
    }
  }
}
```

## What the agent sees

Two kinds of offer for the same file: USDC on NEAR, which any chain can pay through NEAR Intents, and USDC on Base. The agent picks the route its wallet can pay and gets a purchase it can check on NEAR.

The demo file, paid on Base:

```sh
FILE_URL=https://demo.annon.dev/f/what-we-are-building
annon verify "$FILE_URL" --json
annon buy "$FILE_URL" --route base --wallet evm --json
annon status "$PURCHASE_ID" --json
annon open "$PURCHASE_ID" --output what-we-are-building --json
```

Every command answers `{ "ok": true, "result": ... }` or `{ "ok": false, "error": { "code": ..., "message": ... } }`.

After the owner's setup, the agent sets `FILE_URL` to the file it wants, buys once, and sets `PURCHASE_ID` to the full purchase ID in the buy result. It asks for the status until it says accepted, waiting as long as `retryAfterSeconds` says.

Pending means wait. It never means pay again.

## Agent files

Everything an agent needs, as plain files on this site. Every page under /docs and /spec is also Markdown at its URL plus `.md`.

- [llms.txt](/llms.txt): Index of every page for language models
- [annon.json](/.well-known/annon.json): Deployment, packages, install, payments and links as JSON
- [annon-shop.json](/.well-known/annon-shop.json): The demo shop manifest: annon shop add https://annon.dev
- [Agent skill (.md)](/docs/skill.md): The skill file an agent loads
- [Relayer status](/api/status.json): Is the relayer up, as JSON
- [llms-full.txt](/llms-full.txt): Every docs page in one file
- [files.json](https://demo.annon.dev/files.json): The demo shop catalog
- [annon.schema.json](/.well-known/annon.schema.json): JSON Schema of annon.json
- [sitemap.xml](/sitemap.xml): Every page

## Try it on the demo

- The demo shop lists its files at [`files.json`](https://demo.annon.dev/files.json).
- The demo file `what-we-are-building` costs 0.10 USDC. Base needs 0.10 USDC on Base and no ETH. NEAR needs 0.10 USDC on NEAR and a little NEAR for gas.
- Questions, or the pitch deck: [hello@annon.dev](mailto:hello@annon.dev).

[Open the demo shop](/demo)

---

HTML page: https://annon.dev/agents. Every page for agents: https://annon.dev/llms.txt.
