For agents

This page is for a coding agent integrating this API, and for the human pointing
one at it. Everything here is machine-readable on purpose.

The short version

https://docs.avvio.xyz/llms.txt        index of everything, with links
https://docs.avvio.xyz/llms-full.txt   the entire corpus in one fetch
https://docs.avvio.xyz/partner-payouts.openapi.yaml   the contract

llms-full.txt is the whole of the quickstart, the error reference and the
going-live checklist concatenated, with every code sample expanded into all
three languages. One fetch, no HTML to strip, no pagination. Start there rather
than crawling the site.

Read the docs over MCP

These pages are also served as an MCP server, so an agent can ask a question and
get the two paragraphs that answer it instead of carrying the whole corpus.

claude mcp add --transport http avvio-docs https://docs.avvio.xyz/mcp

{
  "mcpServers": {
    "avvio-docs": { "type": "http", "url": "https://docs.avvio.xyz/mcp" },
  },
}

Two tools: search_docs returns the best-matching sections with their URLs, and
fetch_page returns one page in full. It is read-only, holds no key and cannot
touch the API — it is the documentation, not the product. The server below is
the one that moves money; do not confuse them.

Drive the API directly with MCP

The npm package ships an MCP server over stdio, so an agent can price and send
payouts without anyone writing an HTTP client first.

claude mcp add avvio-payments -- npx -y @avvio/payments mcp

{
  "mcpServers": {
    "avvio-payments": {
      "command": "npx",
      "args": ["-y", "@avvio/payments", "mcp"],
      "env": {
        "AVVIO_API_KEY": "akid_test_…",
        "AVVIO_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\\n…",
        "AVVIO_ORG_ID": "cmsx…",
      },
    },
  },
}

The tool list is on the MCP server page, generated from the server
itself. Two properties matter more than the list:

• Money-moving tools require confirm: true as a separate argument. An
  agent told "pay Maria" has to state the intent to move money explicitly, so a
  half-parsed instruction cannot become a payment. It costs one field and
  removes a category of accident.
• Give an agent a test key. A key starting akid_test_ cannot move real
  money, and every tool reports which mode it is in.

If you are writing the integration instead

Read these in this order. They are short and each one is answering a question
the next one assumes.

1. Quickstart — the whole flow, with curl for every step.
2. Errors — every error type, marked with whether the request
   executed and whether retrying is safe. This is the page to internalise
   before writing any retry logic.
3. Going live — reconciliation, webhooks, and what changes when
   the money is real.

Then generate a client from the OpenAPI spec rather than hand-rolling HTTP:

npx @openapitools/openapi-generator-cli generate \
  -i partner-payouts.openapi.yaml -g python -o ./avvio --package-name avvio_payouts

The four things agents get wrong here

Retrying without the same Idempotency-Key. Every mutation takes one, and a
retry that generates a fresh key is a second payment rather than a retry. Persist
the key before sending, reuse it on every attempt. This is the single most
expensive mistake available on this API.

Treating a timeout as a failure. It is an unknown outcome: the payout may
exist. Retry with the same key — a replay returns the original. Starting over is
how one wage advance becomes two.

Treating completed as final. A receiving bank can return a settled payment
days later, and the payout flips to failed with returned_by_bank. Reconcile
from GET /events and keep processing a payout after it completes.

Inventing corridor fields. The fields a beneficiary needs depend on how the
organization is routed and can change. Read
GET /recipients/{orgId}/corridors and build the request from the response.
Mexico is one field; India is two. Hardcoding either is a bug waiting for a
re-route.

There is no browser playground

x-api-key is deliberately absent from the CORS allowlist, so a browser cannot
call this API at all. Do not generate front-end code that calls it directly, and
do not suggest putting the private signing key in a client-side environment
variable. The public akid_* only identifies the key; the private half
authorizes requests. The API is server-to-server, and the
interactive surface is the CLI.

Verify before you assert

Everything on this site is generated from source: the command list from the
CLI's own help text, the tool list from the MCP server, the endpoint table and
every code sample from the OpenAPI spec, the sandbox triggers from the scenario
table the sandbox runs. If a page and the API disagree, the API is right and the
page is a bug — tell us, with the requestId.