ZZanoraDocs
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.

Machine-readable entry points

ResourceWhat it is
/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 token goes to their inbox. Nothing is created until the address is confirmed
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
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 minor units: "100" is $1.00.

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

Terminal
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."

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 "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 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. For selling, the same package has a seller profile.