@avvio/payments 0.1.0 → 0.5.0

package/QUICKSTART.md

@@ -3,30 +3,65 @@
 From an API key to a completed payout, in one page. Nothing here touches a real
 payment network, and no real money can move.
 
-You need a **test key** (`ak_test_…`) from Dashboard → Developers, and your
-organization id. Set both:
+You need a **test API key** from Dashboard → Developers and your organization
+id. The complete key is shown once; copy it then because only its hash is
+stored. Set these values:
 
 ```bash
-export AVVIO_API_KEY=ak_test_…
+export AVVIO_API_KEY=avvio_test_…
 export AVVIO_ORG_ID=cmsx…        # a cuid, not an org_ prefix
 export AVVIO_BASE_URL=https://api.avvio.xyz/business/api/v1
 ```
 
+If your Avvio contact gave you a different base URL (a dedicated or sandbox
+host), use that one; the paths are identical.
+
+### Use the API key directly
+
+The complete `avvio_test_*` value is a bearer credential. Send it as
+`x-api-key`; no private key, signature, nonce, timestamp, or challenge is
+required:
+
+```bash
+curl -s "$AVVIO_BASE_URL/payments/organizations/$AVVIO_ORG_ID/balance" \
+  -H "x-api-key: $AVVIO_API_KEY"
+```
+
 Every step below is shown as a CLI command, as curl, and as Node — pick a tab
 and it stays picked for the rest of the site. Nothing here depends on a
-language. If you use Node, `npx -y @avvio/payments doctor` does step 1 and tells
-you which credential is wrong.
+language. Generated curl samples include `x-api-key`; idempotent operations also
+include `Idempotency-Key`, which must stay identical on every retry. If you use
+Node, `npx -y @avvio/payments doctor` checks the credential and tells you what is
+wrong.
+
+In ReadMe, paste the complete `avvio_test_*` key once under Authorization. Enter
+your ordinary organization id as `orgId`, then use **Try It** on any protected
+endpoint. Never paste a live key into the documentation console.
 
 ---
 
-## 1. Check the key works
+## 1. Check the key works, and read your policy
+
+{{sample:getPolicy}}
+
+One call tells you what your organization is bound by before you send anything:
+`limits` (USD caps, `null` for none), `approvals.thresholdUsd` and how many
+approvers a held payout needs, which `features` are on, `rateLimits` per
+minute, the `idempotency` windows, the currencies that need a
+`purposeOfPayment`, and `fees.payout`: the fee schedule your routing can state
+before a quote (`bps`, `fixedUsd`, per-currency overrides), with `null` where
+it's only priced inside a quote. Everything in it is read from your
+organization and your routing's configuration at request time, so plan against
+it rather than discovering a cap from a `422` later.
+
+Then the corridors:
 
 {{sample:listCorridors}}
 
 You get the currencies you can pay out to and the fields each one needs.
 
 **Read this rather than hardcoding a form.** Both the corridor list and the
-field *names* depend on how your organization is routed, and we may re-route
+field _names_ depend on how your organization is routed, and we may re-route
 you. Mexico is one field; India is two.
 
 ---
@@ -55,7 +90,7 @@ integration has to handle.
   "fee":               { "currency": "USD", "amount": "1.02" },
   "totalDebit":        { "currency": "USD", "amount": "200.00" },
   "rate": "17.010001005126146",   # full precision — round it yourself for display
-  "limits": { "min": "5.00", "max": "5000.00" }
+  "limits": { "min": "1.00", "max": "5000.00" }
 }
 ```
 
@@ -63,8 +98,24 @@ No beneficiary needed — this is what you show while someone is still typing an
 amount. The fee comes **out of** the send, so
 `destinationAmount = (sourceAmount − fee) × rate`.
 
+**Three names, two things.** `quote()` in the SDK and `quote` in the CLI call
+`GET /rates`: this indicative price, no beneficiary. `POST /quotes/offramp`
+(`pricePayout()` in the SDK) is the two-step flow's binding quote against a
+real `destinationAccountId`, the one `POST /quotes/accept` executes. The one-call `POST /payouts` in §5 quotes
+and accepts for you.
+
+**Two rates, two names.** The `rate` here is the **indicative mid-rate before
+the fee**: what one unit converts at. The `rate` on a payout is the **effective
+rate**, destination over source with the fee inside, so for the same conversion
+it reads lower by exactly the fee share (`17.0100` here, `16.9233` on the
+payout, say). That's not the rate moving between the two calls; net the fee out
+of the payout's `sourceAmount` and the two agree.
+
 On a **payout** the fee is already inside the two amounts, so the identity there
-is simply `destinationAmount = sourceAmount × rate`. `rate` on a payout always
+is simply `destinationAmount = sourceAmount × rate`. The payout object still
+reports it as `fee` (`{currency, amount}`, or `null` when the network has not
+disclosed one), the same value its events and its `/balance_transactions` row
+carry. `rate` on a payout always
 means destination units per one source unit, whichever network carried it — it is
 derived from the payout's own amounts rather than passed through, because the
 networks state it in different directions and on different bases.
@@ -75,19 +126,37 @@ networks state it in different directions and on different bases.
 
 {{sample:createBeneficiary}}
 
-Two ids, two jobs. `endUserId` is **your** id for the person *sending* — it
-scopes the beneficiary so one of your users never sees another's saved
-accounts. `externalId` is your id for the beneficiary, and makes a repeat
-create return the existing one instead of registering a second bank account.
+**The one decision first.** Paying your own workers or vendors: omit `endUser`
+and `endUserId`. Paying on behalf of your customers: `endUser` is the customer
+who is sending, never the beneficiary.
+
+Two ids, two jobs. `endUserId` is **your** id for the party _sending_ through
+your platform, your own customer, never the beneficiary. It scopes the
+beneficiary so one of your customers never sees another's saved accounts, and
+the per-end-user daily cap counts against it. `externalId` is your id for the
+beneficiary, and makes a repeat create return the existing one instead of
+registering a second bank account.
+
+Three parties, then. **You** are the partner and the sender of record.
+**`endUser`** is your customer the money is sent for. The **recipient** is the
+account being paid. Payroll makes the roles concrete: an earned-wage-access
+platform paying a worker on behalf of an employer sends
+`endUserId: "employer_acme"` (the company drawing down its payroll) and
+`externalId: "hris_emp_4471"` (the worker's HRIS id, one per bank account),
+with `reference: "PAYROLL-2026-09-01"` on the payout naming the run. If you
+are the sender yourself, with no customer between you and the beneficiary,
+omit `endUser` entirely.
 
 **An `externalId` identifies one account.** Re-sending it with the SAME account
-replays and returns the existing beneficiary. Re-sending it with a DIFFERENT
-account is refused with `BENEFICIARY_EXTERNAL_ID_CONFLICT` — a second account
-needs a second `externalId`. Nothing is silently substituted.
+replays and returns the existing beneficiary, still with **`201`**: the status
+does not tell a repeat from a fresh create, the unchanged `id` does. Re-sending
+it with a DIFFERENT account is refused with `BENEFICIARY_EXTERNAL_ID_CONFLICT` —
+a second account needs a second `externalId`. Nothing is silently substituted.
 
 `type`, `name`, `email` and `method` are always required, whatever the corridor.
 The corridors call describes the fields inside `recipientDetails`; these four sit
-outside it and apply everywhere.
+outside it and apply everywhere. `method.rail` is optional; omit it and the
+corridor's default rail is used.
 
 Keep `paymentMethods[0].destinationAccountId` from the response.
 
@@ -98,9 +167,13 @@ Keep `paymentMethods[0].destinationAccountId` from the response.
 {{sample:createPayout}}
 
 ```jsonc
-{ "payoutId": "…", "status": "pending", "reference": "ZZ-2026-0042", … }
+// 200
+{ "payoutId": "…", "status": "pending", "fee": { "currency": "USD", "amount": "1.02" }, "reference": "ZZ-2026-0042", … }
 ```
 
+An accepted payout answers `200` with the payout body. `202` means your
+organization requires approval and no payout exists yet.
+
 **`expectDestination` is the one field not to skip.** Between pricing and
 sending, a rate can move. Pass the number you showed your user and we refuse to
 send if it has drifted more than 2% — nothing goes, and you re-quote. Without
@@ -112,8 +185,18 @@ it, you send at whatever the quote says.
 
 {{sample:getPayout}}
 
-`pending → processing → completed`. This endpoint is always live and is
-authoritative — more so than a webhook you may have missed.
+`pending → processing → completed`, though not every payout is seen in every
+state: a rail that settles on acceptance can go straight from `pending` to
+`completed`, and in sandbox `processing` lasts eight seconds on most timelines,
+so a poll or a webhook may never catch it (`0002` holds it for fifty). This
+endpoint is always live and is authoritative — more so than a webhook you may
+have missed.
+
+Reading one is `GET /payments/organizations/{orgId}/orders/{payoutId}`, and the
+list is `GET /payments/organizations/{orgId}/orders`. Note the asymmetry, because
+guessing costs you an afternoon: you **send** to `/payouts` and **read** from
+`/orders`. Only the sub-resources of a payout you already have — `/cancel`,
+`/funding`, `/funding/confirm` — hang off `/payouts/{payoutId}`.
 
 ---
 
@@ -127,21 +210,33 @@ Three endpoints you will need on day one.
 curl -s "$AVVIO_BASE_URL/payments/organizations/$AVVIO_ORG_ID/balance" \
   -H "x-api-key: $AVVIO_API_KEY"
 
-curl -s "$AVVIO_BASE_URL/payments/organizations/$AVVIO_ORG_ID/balance/history" \
+curl -s "$AVVIO_BASE_URL/payments/organizations/$AVVIO_ORG_ID/balance_transactions" \
   -H "x-api-key: $AVVIO_API_KEY"
 ```
 
-`balance/history` is the ledger behind the number: every funding, every payout
-debit, and every `reversal` when money comes back. Read it whenever the balance
-is not what you expect — it answers the question directly rather than making you
-infer it from payouts.
+`balance_transactions` is the ledger behind the number, one row per change to
+what you can spend, each with the balance after it. Six row `type`s:
+
+- `funding`: money in (a sandbox `fund`, a settled wire or crypto deposit).
+- `hold`: reserved when a payout is accepted, before the network has answered.
+  Negative, `orderId: null`; it's joined to its payout by `snapshotId`.
+- `hold_release`: the reservation given back, whether the payout went through
+  (paired with a `payout` row, net zero) or was refused (`reason` says why).
+- `payout`: the debit for a payout the network accepted; `fee` is inside it.
+- `payout_return`: money back on a canceled or returned payout.
+- `adjustment`: an operator correction, with a `reason`.
+
+Read it whenever the balance is not what you expect — it answers the question
+directly rather than making you infer it from payouts. The recipe for keeping
+your own ledger in step with it is in
+[RECONCILIATION.md](RECONCILIATION.md#reconciling-your-balance-get-balance_transactions).
 
 **Stopping a payout that has not been funded yet:**
 
 {{sample:cancelPayout}}
 
-It reports `canceled`, the money returns to your balance with a `reversal` row,
-and the payout can no longer be funded. **Once a payout is funded it cannot be
+It reports `canceled`, the money returns to your balance with a `payout_return`
+row, and the payout can no longer be funded. **Once a payout is funded it cannot be
 cancelled** — you get `PAYOUT_NOT_CANCELABLE`, and that is the honest answer
 rather than a cancellation that does not happen. So cancel is for "created by
 mistake", not for "stop one already in flight".
@@ -155,7 +250,10 @@ The id you authenticate with — the one in every URL — is **not** the
 internal one, and using it in a URL gives:
 
 ```jsonc
-{ "type": "FORBIDDEN", "detail": "This API key cannot access that organization" }
+{
+  "type": "FORBIDDEN",
+  "detail": "This API key cannot access that organization",
+}
 ```
 
 which reads as a credentials problem when it is not. **Keep using the org id you
@@ -168,10 +266,12 @@ were issued.** Ignore `organizationId` in response bodies.
 Create a second beneficiary whose account number ends **`0003`**:
 
 ```
-"clabeNumber": "012345678901230003"
+"clabeNumber": "012180000000070003"
 ```
 
-Pay it, then keep polling past `completed`. It flips:
+Pay it, then keep polling past `completed`. In sandbox the return lands 30
+seconds after `completed` (40 seconds after create; give it a minute), so it
+flips:
 
 ```jsonc
 { "status": "failed", "failureCode": "returned_by_bank", "fundsReturned": true }
@@ -184,15 +284,15 @@ in a paragraph you would skim.
 
 Other triggers, and exactly what each does:
 
-| account ends | what happens |
-|---|---|
-| `0001` | fails at the rail with `failureCode: account_invalid`, funds returned |
-| `0002` | settles slowly — useful for testing a poll loop |
-| `0003` | completes, then flips to `failed` / `returned_by_bank` (above) |
-| `0004` | `compliance_rejected`, and the money does **not** come back |
-| `0005` | the quote expires — the payout is refused at **create** with `400 BAD_REQUEST`, so no payout exists to poll |
-| `0006` | waits for you to fund it from your own wallet |
-| anything else | completes |
+| account ends  | what happens                                                                                                |
+| ------------- | ----------------------------------------------------------------------------------------------------------- |
+| `0001`        | fails at the rail with `failureCode: account_invalid`, funds returned                                       |
+| `0002`        | settles slowly — useful for testing a poll loop                                                             |
+| `0003`        | completes, then flips to `failed` / `returned_by_bank` (above)                                              |
+| `0004`        | `compliance_rejected`, and the money does **not** come back                                                 |
+| `0005`        | the quote expires — the payout is refused at **create** with `400 BAD_REQUEST`, so no payout exists to poll |
+| `0006`        | waits for you to fund it from your own wallet                                                               |
+| anything else | completes                                                                                                   |
 
 `0006` is worth running too. Some routings do not settle on acceptance — they
 price the payout and wait for your funds. It returns `requiresFunding: true`
@@ -203,9 +303,11 @@ Read the deposit instructions from `GET /payments/organizations/{orgId}/payouts/
 report the transaction:
 
 ```bash
+# Generate once for this logical operation; reuse for every retry.
+export AVVIO_IDEMPOTENCY_KEY=$(uuidgen)
 curl -s -X POST "$AVVIO_BASE_URL/payments/organizations/$AVVIO_ORG_ID/payouts/$PAYOUT_ID/funding/confirm" \
   -H "x-api-key: $AVVIO_API_KEY" \
-  -H "idempotency-key: $(uuidgen)" \
+  -H "Idempotency-Key: $AVVIO_IDEMPOTENCY_KEY" \
   -H "content-type: application/json" \
   -d '{"transactionHash":"0x…"}'
 ```
@@ -218,12 +320,12 @@ fundable. One transfer funds exactly one payout.
 The sandbox has no chain to read, so the **last four digits of the hash** choose
 the outcome, the same way the account number does:
 
-| hash ends | you get |
-|---|---|
-| `0001` | `FUNDING_TRANSACTION_INVALID` — 400, we read the chain and it does not fund this payout |
-| `0002` | `FUNDING_NOT_YET_VERIFIABLE` — 409, not mined yet; retry the same request |
-| anything else | accepted, and the payout settles |
-| a hash already used | `FUNDING_TRANSACTION_ALREADY_USED` — 409, naming the payout it funded |
+| hash ends           | you get                                                                                 |
+| ------------------- | --------------------------------------------------------------------------------------- |
+| `0001`              | `FUNDING_TRANSACTION_INVALID` — 400, we read the chain and it does not fund this payout |
+| `0002`              | `FUNDING_NOT_YET_VERIFIABLE` — 409, not mined yet; retry the same request               |
+| anything else       | accepted, and the payout settles                                                        |
+| a hash already used | `FUNDING_TRANSACTION_ALREADY_USED` — 409, naming the payout it funded                   |
 
 Testing that branch here is the alternative to discovering it in production.
 
@@ -237,18 +339,23 @@ sandbox secret and prove your handler works now:
 ```bash
 curl -s -X POST "$AVVIO_BASE_URL/payments/organizations/$AVVIO_ORG_ID/sandbox/webhook-endpoints" \
   -H "x-api-key: $AVVIO_API_KEY" \
-  -H "idempotency-key: $(uuidgen)" \
   -H "content-type: application/json" \
-  -d '{"url":"http://localhost:4000/hooks"}'
+  -d '{"url":"https://example.ngrok-free.app/hooks"}'
 ```
 
 ```jsonc
-{ "id": "…", "url": "…", "secret": "whsec_…",
-  "warning": "Store this secret now — it is not retrievable." }
+{
+  "id": "…",
+  "url": "…",
+  "secret": "whsec_…",
+  "warning": "Store this secret now — it is not retrievable.",
+}
 ```
 
-`http://localhost` works **in sandbox only**, so your first receiver can be a
-script rather than a tunnel. Live endpoints are https and are created from the
+When testing against the hosted API, use a publicly reachable HTTPS receiver;
+a development tunnel is fine. `http://localhost` is accepted by the sandbox
+route only when the Avvio backend itself runs locally. A hosted backend resolves
+`localhost` to itself, not to your laptop. Live endpoints are created from the
 dashboard by a human, because a credential able to repoint its own webhook URL
 could redirect every payout notification.
 
@@ -303,14 +410,15 @@ separate `sourceCurrency`. They are two schemas in the spec — `Payout` and
 
 ## Then
 
+- [Agent quickstart](./AGENT_QUICKSTART.md) — the one prompt to hand an agent with a test key
 - [Errors](./ERRORS.md) — every code, and what to do about each
-- [Webhooks](../PARTNER_PAYOUTS_API.md#webhooks) — verification and delivery
+- [Webhooks](./WEBHOOKS.md) — verification and delivery
 - [Going live](./GOING_LIVE.md) — the checklist
 
 ## Two rules worth internalising now
 
 **A timeout is an unknown outcome, not a failure.** If a send times out, the
-payout may exist. Retry with the *same* `Idempotency-Key` — a replay returns the
+payout may exist. Retry with the _same_ `Idempotency-Key` — a replay returns the
 original. Calling again without it is a second payment.
 
 **Webhooks are the fast path, not the guarantee.** Reconcile against the payout

package/README.md

@@ -2,6 +2,8 @@
 
 Pay out to your own customers, from your balance, over one API.
 
+**Docs:** [docs.avvio.xyz](https://docs.avvio.xyz) · **Product:** [avvio.xyz](https://avvio.xyz) · **Partner program:** [avvio.xyz/partners](https://avvio.xyz/partners)
+
 One package, three ways to use it: a **Node client**, a **CLI**, and an **MCP
 server** so an agent can drive payouts directly. All three share the same core,
 so they cannot drift apart.
@@ -23,30 +25,28 @@ Node 18 or newer.
 npm i @avvio/payments
 ```
 
-Not published yet. Until it is, install the tarball from the repo:
-
-```bash
-cd packages/avvio-payments && npm pack
-npm i /path/to/avvio-payments-0.1.0.tgz
-```
-
 ```bash
-export AVVIO_API_KEY=ak_test_…      # server-side only
+export AVVIO_API_KEY=avvio_test_…   # complete bearer key; shown once
 export AVVIO_ORG_ID=cmsx…   # a cuid, not an org_ prefix
-export AVVIO_BASE_URL=https://api.avvio.xyz/api/v1   # optional
+export AVVIO_BASE_URL=https://api.avvio.xyz/business/api/v1   # optional
 ```
 
-Calling the API directly instead? The credential goes in an `x-api-key`
-header, and every mutation needs an `Idempotency-Key`:
+The API key is the complete credential. Calling the API directly? Send it in
+`x-api-key`; there is no private key, request signature, nonce, timestamp, or
+authentication challenge:
 
 ```bash
 curl "$AVVIO_BASE_URL/recipients/$AVVIO_ORG_ID/corridors" \
   -H "x-api-key: $AVVIO_API_KEY"
 ```
 
-> **Never ship the key to a browser or a mobile app.** It is a bearer
-> credential for your money. Our CORS policy does not allow the header, so a
-> browser cannot send one even by accident.
+Only operations marked idempotent in the API reference take an
+`Idempotency-Key`; generate it once and reuse it with every retry of the same
+logical request.
+
+> **Treat the complete API key like a database password.** Keep it in
+> server-side secret storage. Use only an `avvio_test_*` key in ReadMe's Try It
+> console and never embed a key in your own browser or mobile application.
 
 Start here:
 
@@ -70,13 +70,13 @@ npx -y @avvio/payments quote --amount 200 --to MXN
 npx -y @avvio/payments beneficiary create \
   --name "Maria Gonzalez" --email maria@example.com \
   --currency MXN --end-user employee_42 \
-  --field clabeNumber=012345678901234567
+  --field clabeNumber=012180000080004471
 
 npx -y @avvio/payments pay --amount 200 --to <destinationAccountId> \
   --end-user employee_42 --expect 3410.00
 ```
 
-Use a `ak_test_` key and none of this touches a payment network. The **last four
+Use an `avvio_test_` key and none of this touches a payment network. The **last four
 digits** of the account number choose what happens — `0003` completes and is
 then returned by the bank, which is the case worth testing before you go live.
 
@@ -92,12 +92,14 @@ const avvio = new PayoutsClient();
 
 // Which world this key pays into, from its prefix. Worth asserting in your own
 // test suite before anything sends: a live key in a payroll fixture pays real
-// people. Anything not recognisably `ak_test_` reports 'live'.
+// people. The client rejects anything that is not a complete `avvio_*` credential.
 if (avvio.mode !== 'test') throw new Error('refusing to run tests against live');
 
 // Show the price while your user is still typing. No beneficiary needed.
 const quote = await avvio.quote({ amount: '200.00', to: 'MXN' });
 // → { sourceAmount, destinationAmount, fee, rate, limits, indicative: true }
+// quote() calls GET /rates: an indicative price. The two-step flow's binding
+// quote is POST /quotes/offramp (`pricePayout()` here), which needs a beneficiary.
 
 const beneficiary = await avvio.createBeneficiary({
   name: 'Maria Gonzalez',
@@ -105,7 +107,7 @@ const beneficiary = await avvio.createBeneficiary({
   currency: 'MXN',
   endUserId: 'employee_42',          // scopes it to ONE of your users
   externalId: 'emp42_maria',         // makes a repeat create safe
-  details: { clabeNumber: '012345678901234567' },
+  details: { clabeNumber: '012180000080004471' },
 });
 
 const payout = await avvio.payout({
@@ -224,24 +226,34 @@ seven days the record is gone and the key is unknown to us.
 First, get a signing secret. In sandbox you can issue one yourself:
 
 ```bash
-npx -y @avvio/payments webhook create --url http://localhost:4000/hooks
+npx -y @avvio/payments webhook create --url https://example.ngrok-free.app/hooks
 # Signing secret (shown once — store it now):
 #   whsec_…
 ```
 
-`http://localhost` is accepted **in sandbox only**, so your first receiver can be
-a script on your laptop rather than a tunnel you have to stand up first. Live
-endpoints are https-only and are created from the dashboard by a human — a
-credential that could repoint its own webhook URL could quietly redirect every
+When calling the hosted API, use a publicly reachable HTTPS receiver; a
+development tunnel is fine. `http://localhost` works only when the Avvio backend
+itself is running locally, because a hosted backend resolves localhost to itself,
+not to your laptop. Live endpoints are created from the dashboard by a human —
+a credential that could repoint its own webhook URL could quietly redirect every
 payout notification, so that one stays off the API.
 
 The secret is shown **once** and is not retrievable. Store it before you close
 the terminal.
 
 ```bash
-npx -y @avvio/payments webhook deliveries <endpointId>   # what we sent, what came back
+npx -y @avvio/payments webhook deliveries <endpointId>   # a sandbox endpoint you registered
+npx -y @avvio/payments webhook endpoints                 # what is registered on your org
+npx -y @avvio/payments webhook attempts <endpointId>     # the last 50 attempts, newest first
 ```
 
+`attempts` answers "did you send me that event" without opening a dashboard:
+each row carries `eventId` — the `svix-id` we sent, so it is what your dedupe
+keys on — plus `attempts`, `lastError` (your server's own response) and
+`nextAttemptAt`. Retries back off over roughly 70 hours; after that only the
+event feed still has it. Payloads are not returned, and a dashboard replay
+re-fires under the same `eventId`, so your deduplication still holds.
+
 ```js
 const { verifyWebhook } = require('@avvio/payments');
 
@@ -323,6 +335,10 @@ avvio-payments funding pay_01J…                       # address, amount, netwo
 avvio-payments funding confirm pay_01J… --tx 0xabc…   # after you have broadcast it
 ```
 
+`funding` is a pure read — poll it as often as you like. `expiresAt` comes back
+`null`: there is no countdown on the deposit address, so ask `status <payoutId>`
+whether an old set of instructions is still good rather than running a timer.
+
 `confirm` reports a transfer that has **already left your wallet**, so it is
 strict about the hash: a truncated paste is refused here, before anything is
 reported, rather than coming back as a rejection that reads like your transfer
@@ -330,6 +346,60 @@ failed. Pass `--idempotency-key` if you want a timed-out confirm to be safely
 repeatable. Bare `funding`, with no payout id, is still the other question —
 where to wire a top-up for your balance.
 
+## Mass payouts
+
+Up to 1,000 payouts in one request. Each line of `items` is exactly a
+`POST /payouts` wire body, and the **idempotency key covers the run** — a
+submit loop that dies and resubmits the same file under the same key gets the
+same batch back, never a second payroll. `externalReferenceId` is **required
+and unique per organization**: the same run id under a fresh key is refused
+with `PAYOUT_BATCH_DUPLICATE_REFERENCE` naming the original batch, which is
+what stops a crashed submit job from paying a payroll twice. A corrected
+resubmission is a new run and needs its own id. Batches are on by default
+(`MASS_PAYOUTS_DISABLED` only if your organization opted out) and submission is
+limited to 30 requests a minute.
+
+```js
+const batch = await avvio.createPayoutBatch({
+  externalReferenceId: 'payroll-2026-09-01',   // REQUIRED: your run id, unique per org
+  idempotencyKey: 'payroll-2026-09-01-run1',   // persist this BEFORE you send
+  items: [
+    { amount: '200.00', destinationAccountId: 'acct_…', reference: 'PR-0042' },
+    { amount: '150.00', destinationAccountId: 'acct_…', reference: 'PR-0043' },
+  ],
+});
+```
+
+The `202` means **received, not paid**: every line is validated first (nothing
+priced, nothing debited). With `autoCommit: true` — the default — a clean run
+goes straight to creation; any validation errors and it holds at
+`awaiting_confirmation` for your call:
+
+```js
+let run = await avvio.getPayoutBatch(batch.batchId);
+if (run.status === 'awaiting_confirmation') {
+  const bad = await avvio.listPayoutBatchItems(batch.batchId, { status: 'invalid' });
+  // each item echoes your instruction back verbatim — join on content
+  await avvio.confirmPayoutBatch(batch.batchId);   // proceed with the valid lines
+  // …or avvio.cancelPayoutBatch(batch.batchId) to stop the whole run
+}
+```
+
+A batch tracks **creation, not settlement**: `completed` means every line
+either became a payout or was refused — read `run.counts`. Join the run to your
+ledger with `listPayoutBatchItems(batchId, { status: 'created' })`; each
+created line carries a `payoutId` that lives the ordinary payout lifecycle —
+`payout.*` webhooks, the event feed, `getPayout()`.
+
+One item status is special: **`requires_review` means the outcome is unknown**
+(the process died mid-create). It is never retried automatically — re-running a
+line that may already have paid is how a crash becomes a double payment —
+and it is never folded into `create_failed`. Contact support with the
+`batchId`. `listPayoutBatches({ externalReferenceId })` finds your runs, and
+the `payout_batch.*` webhooks (`awaiting_confirmation`, `completed`,
+`canceled`, `failed`) arrive on the same signing and retry ladder as
+`payout.*`.
+
 ## MCP
 
 For an agent that pays people.
@@ -341,7 +411,7 @@ For an agent that pays people.
       "command": "npx",
       "args": ["-y", "@avvio/payments", "mcp"],
       "env": {
-        "AVVIO_API_KEY": "ak_test_…",
+        "AVVIO_API_KEY": "avvio_test_…",
         "AVVIO_ORG_ID": "cmsx…"
       }
     }
@@ -349,17 +419,33 @@ For an agent that pays people.
 }
 ```
 
-Fifteen tools: `list_corridors`, `get_requirements`, `quote`,
-`create_beneficiary`, `list_beneficiaries`, `send_payout`, `get_payout`,
-`list_payouts`, `funding_accounts`, `list_events`, `get_balance`,
-`get_funding`, `create_payout_link`, `confirm_funding`, `cancel_payout`. Ten
-reads are marked read-only so a host can auto-approve them.
-
-> **Three tools move money or end a payment**, and each requires an explicit
-> `confirm: true`: `send_payout`, `confirm_funding` and `cancel_payout`.
-> `send_payout` additionally requires an `idempotencyKey`, so a half-parsed
-> instruction cannot become a payment and a reflexive retry cannot become two.
-> Start with a test key.
+Twenty-five tools: `get_policy`, `list_corridors`, `get_requirements`, `quote`,
+`create_beneficiary`, `list_beneficiaries`, `get_beneficiary`,
+`get_beneficiary_by_external_id`, `update_beneficiary`,
+`delete_beneficiary_method`, `list_payment_reasons`, `send_payout`,
+`get_payout`, `list_payouts`, `funding_accounts`, `list_events`, `get_balance`,
+`list_balance_transactions`, `list_approvals`, `get_approval`,
+`list_audit_events`, `get_funding`, `create_payout_link`,
+`confirm_funding`, `cancel_payout`.
+Eighteen reads are marked read-only so a host can auto-approve them.
+Approving a held payout has no tool, by design: a key cannot approve, and
+neither can an agent holding one.
+
+> **Four tools move money or destroy something**, and each requires an explicit
+> `confirm: true`: `send_payout`, `confirm_funding`, `cancel_payout` and
+> `delete_beneficiary_method`. `send_payout` additionally requires an
+> `idempotencyKey`, so a half-parsed instruction cannot become a payment and a
+> reflexive retry cannot become two. Start with a test key.
+
+Some client methods are deliberately NOT agent tools: `deleteBeneficiary`
+removes a whole record and every method on it, `getBeneficiaryMethodDetails`
+returns full account numbers that do not belong in a model's context when
+`last4` answers the question, and
+quote behind it, and the webhook reads are ops work rather than payout work.
+The batch methods (`createPayoutBatch` and its five companions) are excluded
+too: one confirm committing up to 1,000 payments does not belong behind a
+single tool call — an agent pays one person at a time via `send_payout`.
+Reach for those from Node or the CLI.
 
 ## CLI reference
 
@@ -369,18 +455,31 @@ reads are marked read-only so a host can auto-approve them.
 | `doctor` | Check credentials, connectivity, balance |
 | `fund [--amount]` | Credit your sandbox balance |
 | `balance` | What you can currently send |
+| `balance-transactions [--cursor] [--type]` | Every change to your balance, newest first, with `balanceAfter` |
+| `policy` | Your caps, approval threshold, features and rate limits. Read it first |
 | `corridors` | Currencies you can pay out to |
 | `requirements <CCY>` | Fields that corridor needs |
 | `quote --amount --to` | Price with no beneficiary |
 | `beneficiary create` | Register who is paid. `--external-id` makes a repeat create safe |
 | `beneficiary list [--end-user]` | Saved beneficiaries |
+| `beneficiary get <id>` | One beneficiary. `--external-id` looks it up by YOUR id |
+| `beneficiary update <id>` | Contact details only — bank details are not editable |
+| `beneficiary delete <id>` | Removes them and every payment method on them |
+| `beneficiary method delete <id> <methodId>` | Removes one account; the rest stay payable |
+| `beneficiary method details <id> <methodId>` | The full account on file, not just `last4` |
+| `payment-reasons` | Reasons a payout may state, where a corridor asks for one |
 | `pay --amount --to [--expect]` | Send. `--expect` refuses the send if the rate moved |
 | `status <payoutId> [--watch]` | One payout, live. `--watch` polls until it stops moving |
 | `payouts` | Recent payouts |
-| `events [--since] [--follow]` | The change feed. `--follow` tails it as JSON lines |
+| `events [--since] [--type] [--follow]` | The change feed. `--type` narrows it; `--follow` tails it as JSON lines |
+| `approvals [--status]` | Payouts and runs waiting on your approvers (a 202 from `pay` or a batch confirm) |
+| `approval <approvalId>` | One approval; `executed` ones name the `payoutId` |
+| `audit-events [--action] [--cursor]` | Who did what, with which credential, newest first |
 | `funding` | Where to wire a top-up |
 | `funding <payoutId>` | Deposit instructions for a payout you fund yourself |
 | `funding confirm <payoutId> --tx` | Report the transfer you already sent |
+| `webhook endpoints` | Endpoints registered for your org (read-only) |
+| `webhook attempts <endpointId>` | Last 50 delivery attempts: `eventId`, `attempts`, `lastError` |
 | `mcp` | Run as an MCP server |
 
 Every command takes `--json`.