> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twinbay.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Mercury

> Accounts and balances, transactions, recipients, payments and approvals, events and webhooks, cards and invoices

Mercury's banking API, for agents that pay vendors, reconcile transactions or
watch balances. Mercury's own sandbox cannot send webhooks, has no way to make a
payment fail, return or be blocked, and needs a second person in a dashboard to
approve a payment request. This twin settles, fails and returns payments when the
environment advances, approves requests by directive, and delivers its event
stream to webhook endpoints with Mercury's own signature. Mercury publishes no
client library, so the conformance suite pins the OpenAPI document Mercury's
reference pages carry and validates every response the twin gives against it.

**Slug:** `mercury`

## What it models

| Area | Modelled |
| - | - |
| Starting account | One business organization with its administrator, a checking and a savings account, one ACH recipient and one payment to it still pending |
| Authentication | A `secret-token:mercury_…_yrucrem` API token as HTTP Basic or `Bearer`; read-only and read-write tokens; Mercury's three `401`s and its `403` for a write on a read-only token |
| Organization and accounts | The organization, its users, checking, savings, credit and treasury accounts, with balances projected from their transactions |
| Transactions | Both transaction lists — one paged by cursor, the older one by offset over the last 30 days — every filter, notes and categories, and settlement, failure, return and blocking on advance |
| Recipients | Recipients and recipient invites |
| Send money | ACH, check, wire and real-time payments with the 24-hour duplicate guard and `idempotencyKey`, approval requests a directive approves or rejects, internal transfers |
| Events and webhooks | The event stream as RFC 7396 merge patches with previous values, webhook endpoints filtered by event type and field, deliveries signed with `Mercury-Signature` and retried |
| Cards | Virtual cards, frozen, unfrozen and cancelled, in both of Mercury's card shapes |
| Categories and merchants | Custom expense categories, and Mercury's priority merchants |
| Accounts receivable | Customers and invoices, cancelled, paid and their PDFs |
| Documents | Monthly statements and their PDFs, treasury statements and transactions, SAFEs, attachments |
| Errors and paging | Each of Mercury's error envelopes as production answers them, cursor pagination with `limit` up to 1000, and dollars that keep their cents |

## Not modelled

OAuth2, custom tokens and their scopes, the IP allowlist a read-write token needs,
rate limiting and the MCP server. An endpoint Mercury has and the twin has not
built answers an explicit `501` `notModeled` in Mercury's envelope; a path Mercury
does not have is Mercury's own `404`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.