ZanoraBetaDocs
llms.txt Console Get started

Introduction

Building with AI agents

View as MarkdownThis page as plain text for LLMs Open in ClaudeAsk questions about this page llms-full.txtEvery page in one file

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.

Onboarding through an agent

A buyer can hand the whole setup to their agent with one sentence:

Output
Fetch https://zanora.dev/skill.md and follow the setup instructions

zanora.dev/skill.md↗ is a skill file (the same format as a Claude Code skill, so it can also be saved as ~/.claude/skills/zanora/SKILL.md). It tells the agent which setup fits where it runs:

  • Both paths use Zanora's setup command, npx -y @zanora/mcp setup. The person signs up with their email and confirms it with a 6-digit code; the command keeps the keys in ~/.zanora and never prints them. The MCP config it leads to contains no secret.
  • By default the person runs the command, and the agent explains each step in plain language. That's always the path in chat apps (Claude Desktop and similar).
  • An agent with a shell (Claude Code, Codex CLI, Gemini CLI, Cursor) may run it for them, but only when they've asked it to and agreed to what happens. The person still reads it the code. The agent never calls the signup API directly or handles a key.

Either way it stops at the steps that need a person (below), and finishes with a free purchase from the demo seller.

Machine-readable entry points

ResourceWhat it is
zanora.dev/skill.md↗buyer setup and buying rules as one skill an agent follows
/llms.txtthe index: every page with a one-line summary, grouped the same way as the sidebar
/llms-full.txtevery page's Markdown in one file
/<any-page>.mda single page as plain Markdown, e.g. /buyers/sdk.md. Links inside point to other .md pages
https://api.zanora.dev/v1/auth/scopesthe full list of API key scopes, live
https://api.zanora.dev/v1/rail/providerswhat 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.

StepWhoWhy
Request a signup (POST /v1/signup)agentno credential needed
Confirm the emailpersonthe link and code go to their inbox. Nothing is created until the address is confirmed. A person can read the code to their agent
Create wallets, set policies, publish capabilitiesagent, with the tenant's keyordinary API calls
Fund a walletpersona card payment or a USDC transfer. An agent can't fund its own wallet, but it can send its person a payment link (zanora_request_funding)
Approve a spend that a policy heldpersonin the console, or through an MCP prompt they answer
Verify a sellerZanora operatoruntil then the seller's capabilities don't appear in discovery
Set a payout destinationpersonchanging it freezes payouts for 24 hours and sends an alert
Buy, read receipts, rate sellersagentthe normal loop

Onboarding recipe

For an agent with shell access and a user who can read their email. All amounts are strings of micro-dollars: "1000000" is $1.00 and "1000" is $0.001.

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.

2

Request the signup

Buyers: follow zanora.dev/skill.md↗ instead of the steps below. It asks for a code ("withCode": true), so the person reads you 6 digits rather than pasting a key, and you receive a key that can't approve purchases. See Through an AI agent.

Sellers:

Terminal
curl -s -X POST https://api.zanora.dev/v1/signup -H 'content-type: application/json' \
  -d '{"role":"seller","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."

3

Confirm the key works

Terminal
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_…"}
4

Follow the quickstart for the role

Buyers: Buyer quickstart. Sellers: Seller quickstart. Both mark the steps that need a person.

Rules for handling money

Read these before you spend

  • Money is never a JSON number. Send "priceMicros": "1000000". 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, and give them a way to add money: a card payment link (zanora_request_funding), the USDC deposit address (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 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 eleven 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. For selling, the same package has a seller profile.