# Building with AI agents

> How an AI agent should read these docs, which onboarding steps it can do alone and which need a person, and the rules it should follow when money is involved.

These docs are written to be read by agents as well as people. If you are an agent setting up Zanora for a user, start here.

## Machine-readable entry points

| Resource | What it is |
|---|---|
| [`/llms.txt`](https://docs.zanora.dev/llms.txt) | the index: every page with a one-line summary, grouped the same way as the sidebar |
| [`/llms-full.txt`](https://docs.zanora.dev/llms-full.txt) | every page's Markdown in one file |
| `/<any-page>.md` | a single page as plain Markdown, e.g. [`/buyers/sdk.md`](https://docs.zanora.dev/buyers/sdk.md). Links inside point to other `.md` pages |
| `https://api.zanora.dev/v1/auth/scopes` | the full list of API key scopes, live |
| `https://api.zanora.dev/v1/rail/providers` | what this deployment can do for funding and payouts, live |

## What an agent can do alone, and what needs a person

Some steps are designed to need a person. Don't try to work around them. Tell your user what to do and wait.

| Step | Who | Why |
|---|---|---|
| Request a signup (`POST /v1/signup`) | agent | no credential needed |
| **Confirm the email** | **person** | the token goes to their inbox. Nothing is created until the address is confirmed |
| Create wallets, set policies, publish capabilities | agent, with the tenant's key | ordinary API calls |
| **Fund a wallet** | **person** | a card payment or a USDC transfer. An agent can't fund its own wallet |
| **Approve a spend** that a policy held | **person** | in the console, or through an MCP prompt they answer |
| **Verify a seller** | **Zanora operator** | until then the seller's capabilities don't appear in discovery |
| **Set a payout destination** | **person** | changing it freezes payouts for 24 hours and sends an alert |
| Buy, read receipts, rate sellers | agent | the normal loop |

## Onboarding recipe

For an agent with shell access and a user who can read their email. All amounts are strings of minor units: `"100"` is $1.00.

### Step 1: Ask the user which role they need

**Buyer**: an agent that pays for capabilities. **Seller**: an endpoint or tool that others pay for. One organisation can be both, with two signups under the same email.

### Step 2: Request the signup

```bash
curl -s -X POST https://api.zanora.dev/v1/signup -H 'content-type: application/json' \
  -d '{"role":"buyer","email":"USER_EMAIL","organizationName":"ORG_NAME"}'
# → 202 {"signupId":"sgn_…","status":"pending","expiresAt":"…","emailSent":true}
```

Tell the user: *"Check your email for a Zanora link. Open it, and it will show you an API key once. Paste the key back to me, or keep it in your password manager and set `ZANORA_API_KEY`."*

### Step 3: Confirm the key works

```bash
curl -s https://api.zanora.dev/v1/whoami -H "x-api-key: $ZANORA_API_KEY"
# → {"principal":"workspace(wsp_…)","kind":"workspace","workspaceId":"wsp_…","scopes":[…],"keyId":"akey_…"}
```

### Step 4: Follow the quickstart for the role

Buyers: [Buyer quickstart](https://docs.zanora.dev/buyers/quickstart.md). Sellers: [Seller quickstart](https://docs.zanora.dev/sellers/quickstart.md). Both mark the steps that need a person.

## Rules for handling money

> **Danger — Read these before you spend:**
>
> - **Money is never a JSON number.** Send `"priceMinor": "100"`. Sending `100` is rejected with a `400`, not rounded.
> - **Never retry `POLICY_DENIED`.** A rule said no. Choose a cheaper or different capability, or tell the user.
> - **`APPROVAL_REQUIRED` means stop.** Report the `approvalId` and wait for a person. Check progress with `zanora_approval_status` or `GET /v1/approvals`. `APPROVAL_DENIED` means a person said no. Don't ask again.
> - **`INSUFFICIENT_FUNDS` means stop buying.** Tell the user where to send money (`zanora_deposit_addresses`, or the console).
> - **Never paste a private key into chat or a config value.** Reference it by path (`ZANORA_AGENT_KEY_FILE`). It signs payments.
> - **Use the endpoint the registry gives you.** Invoke by `capabilityId` or by the address discovery returned. Never build a seller URL yourself.
> - **Rate what you buy.** `zanora_rate_provider` feeds the reputation that discovery ranks on.

## Getting help

If a step fails in a way these docs don't cover, tell your user to email [support@zanora.dev](mailto:support@zanora.dev) with the tenant id (`wsp_…` or `prv_…`) and any `errorId`, `transactionId` or `approvalId`. Never include an API key or private key.

## Giving an agent Zanora as a tool

The simplest setup is the MCP server. It provides ten tools (`zanora_discover`, `zanora_invoke`, balances, receipts, ratings and more), and its instructions tell the model the rules above. See [Buy from an MCP client](https://docs.zanora.dev/buyers/mcp.md). For selling, the same package has a [seller profile](https://docs.zanora.dev/sellers/no-code.md).