---
name: zanora
description: Set up and use Zanora, so this agent can find and pay per call for APIs and MCP tools from its own wallet, within spending rules a person sets. Use when the user mentions Zanora, asks for their agent to pay for or buy a tool, API or data source, wants an agent wallet, or asks for a capability the agent does not have that a paid service could provide. Covers setting up with Zanora's own setup command (the person signs up with their email; no keys pass through the agent), connecting the Zanora MCP server, funding, buying, refusals and troubleshooting.
---

# Buying with Zanora

Zanora is a marketplace of paid tools and APIs that an AI agent can use when it needs to do something it can't do on its own. Each call has a price, the agent pays it from its own wallet, and every purchase comes back with a signed receipt. A person sets the spending rules, and the platform enforces them before any money moves.

Setting up takes about five minutes and uses Zanora's own setup command, `npx -y @zanora/mcp setup`. The person signs up with their own email: the account exists only once they confirm a 6-digit code from their inbox. The command keeps the keys on their computer, in files only they can read, and **never prints them**. Whoever runs the command never sees a key, and the AI client's configuration contains no secret.

The first purchase can be free: the demo seller's invoice-OCR tool costs $0.00 on the hosted platform, so the setup can be proved before anyone adds money.

## Check whether Zanora is already set up

If tools named `zanora_discover`, `zanora_invoke` and `zanora_wallet_balance` are available, call `zanora_wallet_balance`. If it answers, setup is done. Go to [Buying](#buying). If it fails, go to [Common issues](#common-issues).

## Choose the setup

- **The person runs the setup command themselves** in a terminal: [Setup B](#setup-b-the-person-runs-it). This is the default. Use it in any chat app (Claude Desktop, Claude Cowork, ChatGPT), whenever you're unsure, and whenever the person would rather do it.
- **You run the command for them**: [Setup A](#setup-a-you-run-the-command). Only if you can run shell commands (Claude Code, Codex CLI, Gemini CLI, Cursor's agent) **and** the person has asked you to set Zanora up. Tell them what will happen first (step 1) and go ahead only if they agree.

Either way it's the same command and the same result. The person signs up and holds the keys. Never call Zanora's signup API directly, and never read, print or copy the files in `~/.zanora`.

## What only a person can do

These steps are deliberately the person's. Don't try to work around them. Tell the person what to do, then wait.

| Step | Why |
|---|---|
| Sign up and confirm the email | the account is theirs. Nothing exists until they confirm the code from their inbox |
| Add money to the wallet | a card payment or a USDC transfer. An agent can't fund its own wallet |
| Approve a purchase that a spending rule held | that's what the rule is for. The agent's key can't approve, by design |

## Setup A: you run the command

You need Node.js 20 or newer (`node --version`).

### 1. Tell the person what will happen, and ask

Say:

> I can set up Zanora with its setup command. You'll sign up with your email: Zanora sends you a 6-digit code, and the account only exists once you give me that code. The command keeps the keys on this computer and never shows them to me, and the agent's key can buy but can't approve purchases or add money. Those stay with you, in the Zanora console. I need:
>
> 1. the email address and organisation name to sign up with (your own name is fine for the organisation);
> 2. whether purchases over $2.00, and any from a seller Zanora hasn't verified, should wait for your approval in the console (I'd say yes);
> 3. the most one call may cost (I'd suggest $2.00).
>
> OK to go ahead?

If they'd rather do it themselves, use [Setup B](#setup-b-the-person-runs-it).

### 2. Start the signup

```bash
npx -y @zanora/mcp setup --gateway https://api.zanora.dev --email 'EMAIL' --org 'ORGANISATION' --name AGENT_NAME --approval-rules
```

Leave out `--approval-rules` if they said no. Keep `--gateway` exactly as written: it is the Zanora deployment this guide came from, and the command stores it, so everything after uses the same one. `AGENT_NAME` is a plain name such as `claude-code`; it appears on receipts and approvals. If the command says Zanora is already set up on this machine, stop and ask the person whether they want to keep that setup or start over (`--force`).

Then say:

> Zanora has emailed you a 6-digit code. Tell me the code when you have it. It expires in 30 minutes.

### 3. Finish with the code

```bash
npx -y @zanora/mcp setup --code CODE
```

If the code is refused, the message says why. For a wrong code it says how many tries are left. If the code expired or ran out of tries, run `npx -y @zanora/mcp setup --resend`, then ask for the new code.

The command prints what it set up and how to connect. It doesn't print a key, and you don't need one.

### 4. Connect the Zanora MCP server

**Claude Code:**

```bash
claude mcp add zanora -e ZANORA_MAX_PRICE_MICROS=2000000 -- npx -y @zanora/mcp
```

**Codex CLI** (`~/.codex/config.toml`):

```toml
[mcp_servers.zanora]
command = "npx"
args = ["-y", "@zanora/mcp"]
env = { ZANORA_MAX_PRICE_MICROS = "2000000" }
```

**Gemini CLI** (`~/.gemini/settings.json`), **Cursor** (`~/.cursor/mcp.json`), or any other client, under `mcpServers`:

```json
"zanora": { "command": "npx", "args": ["-y", "@zanora/mcp"], "env": { "ZANORA_MAX_PRICE_MICROS": "2000000" } }
```

`ZANORA_MAX_PRICE_MICROS` is the per-call limit from step 1, in micro-dollars: `2000000` is $2.00. It's checked on this computer, in addition to the rules on the server. The server finds everything else in `~/.zanora`.

### 5. Finish

Tell the person:

1. Restart this session (or the client) so the Zanora tools load.
2. To try it, ask: *"Use Zanora to find an invoice OCR tool and run it on https://example.com/invoice.png, then show me the receipt."*
3. Zanora has emailed a link to set a console password. The console, https://console.zanora.dev, is where they add money, approve held purchases and change rules.
4. To buy from paid sellers, the wallet needs money. You can't add it, but you can ask: `zanora_request_funding` gives them a one-time link to pay by card, and `zanora_deposit_addresses` lists the USDC address if one exists. Card top-ups have a minimum, **$25.00** on the hosted platform; USDC has none.

## Setup B: the person runs it

Send them this, in one message, and then stop:

> Zanora gives me a wallet so I can use paid tools for things I can't do on my own, like reading invoices or searching premium data. You stay in control: you set the spending rules, and I can't add money or approve my own purchases.
>
> Setting it up takes about five minutes. You need Node.js (https://nodejs.org, the LTS version) if you don't have it.
>
> 1. Open **Terminal** (on a Mac: open Launchpad, type Terminal, open it).
> 2. Paste this line, with your own email and name, and press Return:
>
>    ```
>    npx -y @zanora/mcp setup --gateway https://api.zanora.dev --email you@example.com --org "Your name" --name claude --approval-rules
>    ```
>
>    (`--approval-rules` means purchases over $2, and any from a seller Zanora hasn't verified, wait for your approval. Leave it out if you don't want that.)
> 3. Zanora emails you a 6-digit code. Paste this, with your code, and press Return:
>
>    ```
>    npx -y @zanora/mcp setup --code 123456
>    ```
>
>    That creates your account and my wallet. The keys stay on your computer; nobody is shown them.
> 4. Connect me to it. In this app, open **Settings → Developer → Edit Config**. Paste this into the file (if it already has `"mcpServers"`, add only the `"zanora"` part inside it), then save:
>
>    ```json
>    {
>      "mcpServers": {
>        "zanora": { "command": "npx", "args": ["-y", "@zanora/mcp"], "env": { "ZANORA_MAX_PRICE_MICROS": "2000000" } }
>      }
>    }
>    ```
>
>    `2000000` means no single purchase over $2.00 (the value is in micro-dollars: millionths of a dollar).
> 5. Quit this app completely and open it again. Then ask me to "check my Zanora wallet".
>
> Zanora also emails you a link to set a password for its console, where you add money and approve purchases.

When they come back, call `zanora_wallet_balance`. If it answers, offer to try the free demo purchase from [Buying](#buying). If the Zanora tools are missing, see [Common issues](#common-issues).

### How to talk to chat-app users

- Use plain words. Say "paid tools", "add money", "sign in", "spending rules".
- Don't say "MCP server", "API", "x402", "402", "ed25519", "scopes" or "minor units" unless they ask.
- Say what they need to do next, not what you can't do.
- Say what a purchase costs in dollars before you make it, unless it's free.

## Buying

1. **Find it:** `zanora_discover` with a plain description of what you need, for example `"extract text from invoices"`. Add `maxPriceMicros` to stay under a price.
2. **Pick it:** prefer the cheapest result that meets the need, from a verified seller with good ratings. Skip any result marked `payable: false`: it's a listing you can't buy yet.
3. **Buy it:** `zanora_invoke` with the result's `capabilityId` and the input its schema asks for. This spends money. Don't call a paid tool just to see what it does.
4. **Check it:** the result carries a signed receipt. `receiptVerified` means the platform signed it, and `responseHashVerified` means it's about this answer. `zanora_receipt` re-checks a receipt later.
5. **Rate it:** `zanora_rate_provider` from 1 to 5. Ratings rank future search results.

Have a capability id from an earlier session, a receipt or the user, but no search result for it? `zanora_capability` looks it up and makes it buyable. Never build a seller's URL yourself.

`zanora_wallet_balance`, `zanora_wallet_ledger` and `zanora_purchases` answer "how much is left", "where did it go" and "what did I buy".

### Your client may ask the person first

`zanora_invoke` spends money and `zanora_request_funding` asks for it, so a client with a permission check may stop and ask the person to confirm before either one runs. Claude Code's auto mode does this. That's expected, not an error. Before you call one, say what it is for and how much, so the person knows what they're confirming. If they decline, don't try another route to the same purchase.

### Adding money by card

- A card top-up has a **minimum: $25.00** on the hosted platform. `zanora_request_funding` raises a smaller amount to the minimum and says so (`raisedToCardMinimum`). Tell the person before they pay: the link charges the minimum, and what isn't spent stays in the wallet for later purchases.
- USDC deposits have no minimum (`zanora_deposit_addresses`).
- The link works once, for 30 minutes. After the person says they've paid, check `zanora_wallet_balance`: a card payment is credited within seconds of being confirmed.

## When the answer is no

A refusal moves no money. None of these is fixed by trying again.

| Result | What to do |
|---|---|
| `POLICY_DENIED` | a spending rule said no. Never retry it. Pick another capability, or tell the user |
| `APPROVAL_REQUIRED` with an `approvalId` | a person has to approve it, in the Zanora console under **Buyer → Approvals**. Your key can't approve, so you won't be asked to and the person isn't prompted in this chat. Tell them what you want to buy, what it costs, and where to approve it. Report the id and stop; `zanora_approval_status` tells you when they decide, and the purchase works once it's approved |
| `APPROVAL_DENIED` | the person said no. Don't retry, and don't ask again |
| `INSUFFICIENT_FUNDS` | stop buying. Tell the user how much is missing, and offer a way to add it: `zanora_request_funding` with an amount (string micro-dollars, `"25000000"` is $25.00) returns a one-time card payment link to give them (at least the $25.00 card minimum, see [Adding money by card](#adding-money-by-card)); `zanora_deposit_addresses` lists a USDC address. Say what the link is for and how much before you send it. Then wait for them to say they've paid, and check `zanora_wallet_balance` |
| `PRICE_ABOVE_CLIENT_LIMIT` | it costs more than `ZANORA_MAX_PRICE_MICROS`. Pick something cheaper, or ask the user to raise the limit |
| `WALLET_PROVIDER_PAUSED` | that seller failed three paid calls in a row and was refunded each time. Choose another seller |

## Rules when money is involved

- Money on the wire is a string of micro-dollars: `"2000000"` is $2.00 and `"1000"` is $0.001. A JSON number is refused, not rounded.
- The private key file is referenced by path, never pasted, printed or put into a config value.
- Keep the workspace key out of the agent's configuration. The agent uses its own key, which can't approve.
- Spending rules are enforced on the server. Don't try to get around one by splitting a purchase, switching wallets or retrying.
- Only a person adds money. You can ask, with a payment link (`zanora_request_funding`), and tell them where. Ask for what the task needs, not more.

## Common issues

| Symptom | Cause | Fix |
|---|---|---|
| Zanora tools missing after setup | the client hasn't been restarted, or the config has an error | quit and reopen the client. In Claude Code, `claude mcp list` shows whether `zanora` started |
| `Zanora isn't set up on this machine` when the client starts | setup didn't finish, or ran as another user | run `npx -y @zanora/mcp setup --status` in a terminal |
| `refused ZANORA_API_KEY` | the key was revoked or expired | run `npx -y @zanora/mcp setup --force --email … --org …` again, or remove `ZANORA_API_KEY` from the client config if one was set by hand |
| `… agent wallets, so ZANORA_WALLET_ID is required` | the workspace has more than one agent wallet | set `ZANORA_WALLET_ID` to the one this agent should use |
| `… already has a console account` when finishing setup | the person already has a Zanora account with that email | either sign up with another address, or connect the existing account by hand: [Buy from an MCP client](https://docs.zanora.dev/buyers/mcp.md) |
| no email with the code | spam folder, or a typo in the address | `npx -y @zanora/mcp setup --resend`. A typo needs a new start with the right address |
| `APPROVAL_NOT_PERMITTED` | a decision was sent with a key that can't approve. This is intended | the person approves in **Buyer → Approvals** |
| a Zanora tool waits for confirmation | your client's permission check (for example Claude Code's auto mode) asks the person before a tool that spends or asks for money | expected: say what the call is for, and let the person confirm |
| search returns nothing | filters too narrow, or the seller isn't verified yet | broaden the query. `"invoice"` always finds the demo seller |
| `INVOKE_FAILED — fetch failed` | the seller's server can't be reached from here. Nothing was charged | choose another capability |
| `INSUFFICIENT_FUNDS` just after adding money | a card takes seconds to confirm, USDC a few minutes | wait, then check `zanora_wallet_balance` |

## More

- Buyer docs: https://docs.zanora.dev/buyers/overview.md
- The MCP server's tools and settings: https://docs.zanora.dev/buyers/mcp.md
- Notes for AI agents: https://docs.zanora.dev/agents.md
- Every docs page, indexed for agents: https://docs.zanora.dev/llms.txt
- Help: support@zanora.dev, with the workspace id (`wsp_…`) and any `approvalId` or `transactionId`. Never include a key.