A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Mercury API is how an app or AI agent works with a Mercury banking account: reading account balances and transaction history, managing recipients, sending money to a saved recipient, and issuing or freezing cards. Access is granted through an API token, and a token is created at a read-only or a read-and-write level, with write-capable tokens required to be locked to a set of approved IP addresses. Mercury serves a single versioned API and can push an event to a registered endpoint when something changes.
How an app or AI agent connects to Mercury determines what it can reach. There is a route for making calls with an API token, a route for receiving events, and a hosted server that exposes Mercury tools to agents, and each is governed by the token behind it and the read or write level that token carries.
The REST API takes JSON request bodies, returns JSON, and pages through lists with a cursor, under https://api.mercury.com/api/v1. A call authenticates with an API token, sent as a Bearer token or as the HTTP Basic auth username with an empty password. The token's read-only or read-and-write level sets what the call can do.
A first-party hosted Model Context Protocol server at https://mcp.mercury.com/mcp exposes Mercury data to AI clients like Claude and ChatGPT as a custom connector. It authenticates with OAuth 2.0, supporting Dynamic Client Registration, and is scoped to read-only access, covering tools like getAccount, getAccounts, getTransaction, listTransactions, getRecipients, getTreasury, and getOrganization. Mercury does not offer a self-hosted MCP.
Mercury POSTs an event to an HTTPS endpoint registered through the API when something changes, like a transaction being created or updated or an account balance changing. The webhook carries a signing secret, returned only at creation, that the receiver uses to verify the event came from Mercury. Failed deliveries are retried with exponential backoff, and filters can narrow which events are sent.
A third-party integration can connect to a Mercury account on a user's behalf through an OAuth 2.0 authorization-code flow, starting at the authorize endpoint and exchanging the code for an access token at the token endpoint. This is the route for apps that act for many Mercury users rather than holding one organization's static token.
A Read Only token can fetch accounts, transactions, recipients, cards, treasury, and statements, but cannot move money or change data. It does not require IP whitelisting. It is sent as a Bearer token or as the HTTP Basic auth username with an empty password.
A Read and Write token can do everything a Read Only token can, plus send money and manage recipients without separate admin approval. Mercury requires it to be restricted to approved IP addresses or ranges, so a request from an unapproved address is rejected.
A Custom token grants only the scopes selected when it is created, so it carries the fewest permissions a task needs. Scopes cannot be edited after creation. Any write scope on a Custom token also requires the IP restriction; a write-free Custom token does not.
OAuth 2.0 lets a third-party integration connect on a Mercury user's behalf, rather than using one organization's static token. The flow starts at the authorize endpoint and exchanges a code for an access token at the token endpoint.
The Mercury API is split into areas an agent can act on, like accounts, transactions, recipients, sending money, cards, and treasury. Each area has its own methods, and writes in some areas move real money or issue spending cards.
Methods for reading accounts, their balances, cards, transactions, and statements.
Methods for reading transactions and editing their notes, categories, and attachments.
Methods for sending money to a recipient and moving funds between accounts.
Methods for creating and reading the payees a payment can be sent to.
Methods for issuing, reading, freezing, and cancelling cards.
Methods for reading treasury accounts, their transactions and statements, and credit accounts.
Methods for reading account statements and downloading them as PDF.
Methods for reading events and registering webhooks to receive them.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
AccountsMethods for reading accounts, their balances, cards, transactions, and statements.4 | ||||||
| GET | /api/v1/accounts | Retrieve a paginated list of all accounts in the organization. | read | Read Only | Current | |
Reachable by a Read Only token; exposes account balances. Acts onaccount Permission (capability) Read OnlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/accounts/:id | Retrieve a single account by its id, including its balance. | read | Read Only | Current | |
Read-only. Acts onaccount Permission (capability) Read OnlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/accounts/:id/cards | Retrieve the cards associated with an account. | read | Read Only | Current | |
Read-only. Acts oncard Permission (capability) Read OnlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/account/:id/transactions | Retrieve a paginated list of transactions for a single account. | read | Read Only | Current | |
Read-only; supports date, status, and category filters. Acts ontransaction Permission (capability) Read OnlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TransactionsMethods for reading transactions and editing their notes, categories, and attachments.4 | ||||||
| GET | /api/v1/transactions | Retrieve a paginated list of transactions across all accounts. | read | Read Only | Current | |
Read-only; cursor-paginated with filters. Acts ontransaction Permission (capability) Read OnlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/transactions/:id | Retrieve a single transaction by its id. | read | Read Only | Current | |
Read-only. Acts ontransaction Permission (capability) Read OnlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v1/transactions/:id | Update a transaction's metadata, like its note or category. | write | Read and Write | Current | |
Changes metadata only; does not move money. Needs a write-capable token. Acts ontransaction Permission (capability) Read and WriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/transactions/:id/attachments | Upload an attachment, like a receipt, to a transaction. | write | Read and Write | Current | |
Needs a write-capable token. Acts onattachment Permission (capability) Read and WriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Send moneyMethods for sending money to a recipient and moving funds between accounts.2 | ||||||
| POST | /api/v1/account/:id/transactions | Send money from an account to an existing recipient by ach, check, or domestic wire. | write | Read and Write | Current | |
Moves real money; needs a write-capable, IP-restricted token, a recipientId, amount, paymentMethod, and idempotencyKey. A domesticWire also needs a purpose. May require approval depending on account controls. Acts ontransaction Permission (capability) Read and WriteVersionAvailable since the API’s base version Webhook event transaction.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/internal-transfers | Transfer funds between two accounts in the same organization. | write | Read and Write | Current | |
Moves money between owned accounts; needs a write-capable token. Acts oninternal_transfer Permission (capability) Read and WriteVersionAvailable since the API’s base version Webhook event transaction.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
RecipientsMethods for creating and reading the payees a payment can be sent to.4 | ||||||
| POST | /api/v1/recipients | Add a new recipient that money can later be sent to. | write | Read and Write | Current | |
Adds a payee; needs a write-capable token. Acts onrecipient Permission (capability) Read and WriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/recipients | Retrieve all recipients in the organization. | read | Read Only | Current | |
Read-only. Acts onrecipient Permission (capability) Read OnlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/recipients/:id | Retrieve a single recipient by its id. | read | Read Only | Current | |
Read-only. Acts onrecipient Permission (capability) Read OnlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v1/recipients/:id | Update an existing recipient's details. | write | Read and Write | Current | |
Changes a payee's details; needs a write-capable token. Acts onrecipient Permission (capability) Read and WriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CardsMethods for issuing, reading, freezing, and cancelling cards.7 | ||||||
| POST | /api/v1/cards | Issue a new virtual debit or credit card for a user. | write | Read and Write | Current | |
Issues a real spending card; needs userId, type, kind, and a write-capable token. Acts oncard Permission (capability) Read and WriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/cards | Retrieve a list of cards. | read | Read Only | Current | |
Read-only. Acts oncard Permission (capability) Read OnlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/cards/:id | Retrieve a single card by its id. | read | Read Only | Current | |
Read-only. Acts oncard Permission (capability) Read OnlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v1/cards/:id | Update a card's nickname or spending limits. | write | Read and Write | Current | |
Changes card limits or label; needs a write-capable token. Acts oncard Permission (capability) Read and WriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/cards/:id/freeze | Temporarily freeze an active card. | write | Read and Write | Current | |
Pauses a card; the card must be active. Needs a write-capable token. Acts oncard Permission (capability) Read and WriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/cards/:id/unfreeze | Unfreeze a previously frozen card. | write | Read and Write | Current | |
Reactivates a frozen card; needs a write-capable token. Acts oncard Permission (capability) Read and WriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v1/cards/:id | Cancel a card permanently. | write | Read and Write | Current | |
Permanently cancels a card; needs a write-capable token. Acts oncard Permission (capability) Read and WriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Treasury & creditMethods for reading treasury accounts, their transactions and statements, and credit accounts.3 | ||||||
| GET | /api/v1/treasury | Retrieve a paginated list of treasury accounts, with balances and net returns. | read | Read Only | Current | |
Read-only. Acts ontreasury_account Permission (capability) Read OnlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/treasury/:id/transactions | Retrieve transactions for a treasury account. | read | Read Only | Current | |
Read-only. Acts ontransaction Permission (capability) Read OnlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/credit | Retrieve a list of credit accounts. | read | Read Only | Current | |
Read-only. Acts oncredit_account Permission (capability) Read OnlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
StatementsMethods for reading account statements and downloading them as PDF.2 | ||||||
| GET | /api/v1/accounts/:id/statements | Retrieve the statements for an account. | read | Read Only | Current | |
Read-only. Acts onstatement Permission (capability) Read OnlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/statements/:id/pdf | Download a statement as a PDF. | read | Read Only | Current | |
Read-only. Acts onstatement Permission (capability) Read OnlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Events & webhooksMethods for reading events and registering webhooks to receive them.3 | ||||||
| GET | /api/v1/events | Retrieve a paginated list of account events. | read | Read Only | Current | |
Read-only. Acts onevent Permission (capability) Read OnlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v1/webhooks | Register a webhook endpoint to receive account events, returning a signing secret once. | write | Read and Write | Current | |
Registers where events are delivered; the signing secret is returned only on creation. Needs a write-capable token. Acts onwebhook Permission (capability) Read and WriteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v1/webhooks | Retrieve the registered webhooks. | read | Read Only | Current | |
Read-only. Acts onwebhook Permission (capability) Read OnlyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Mercury can notify an app when something happens in an account, like a transaction posting or a balance changing. It POSTs an event to a registered endpoint, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
transaction.created | A new transaction was created in an account, like an outbound payment being initiated. | /api/v1/account/:id/transactions/api/v1/internal-transfers |
transaction.updated | An existing transaction changed, like its status moving from pending to posted. | In-app only |
checkingAccount.balance.updated | The balance of a checking account changed. | In-app only |
savingsAccount.balance.updated | The balance of a savings account changed. | In-app only |
treasuryAccount.balance.updated | The balance of a treasury account changed. | In-app only |
creditAccount.balance.updated | The balance of a credit account changed. | In-app only |
Mercury pages through lists with a cursor and meters how fast an app can call. It does not publish a fixed per-method request ceiling, so an integration should handle a rate-limit response and back off.
Mercury does not publish a fixed numeric request ceiling per method in its developer docs. It meters request volume and an integration should treat a rate-limit response as a signal to slow down, retrying with exponential backoff. Write-capable tokens are further constrained by IP restriction rather than by a documented per-method quota, so a request from an unapproved address is rejected regardless of rate.
List endpoints are cursor-paginated. A response carries pagination cursors, like a next-page and previous-page cursor, that an integration follows to walk through results. Transaction and account lists also accept filters such as date ranges and status to narrow what is returned before paging.
Amounts on a send-money request are in US dollars with a minimum of 0.01. A webhook signing secret is returned only once, at creation, and cannot be retrieved later. Attachments can be uploaded to transactions and recipients, and statements and invoices can be downloaded as PDF.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | unauthorized | No valid API token was provided, or the token has been deleted or downgraded below what the request needs. | Send a valid token in the Authorization header, and confirm it still holds the required read or write level. |
| 403 | forbidden | The token is valid but lacks permission for the request, for example a Read Only token attempting a write, or a write token calling from an IP address outside the approved list. | Use a token with the needed write level, and call from an approved IP address. |
| 404 | not_found | The requested object does not exist or is not visible to this token's organization. | Verify the id and confirm it belongs to an account the token can see. |
| 429 | too_many_requests | Requests arrived faster than Mercury allows. | Back off and retry with exponential backoff, and smooth the request rate. |
Mercury serves a single versioned API and ships dated changes through its changelog rather than minting a new version string for additive features.
Mercury serves a single versioned API under the v1 path and ships additive changes through its changelog rather than minting a new version string. The entries below are notable dated additions; relative dates are approximate to the month, taken from the public changelog.
Mercury added an API to issue and manage cards, covering virtual debit and credit cards, spending limits, and lifecycle actions like freeze, unfreeze, and cancel.
The categories endpoints were expanded to create, edit, and delete expense categories programmatically.
The Send Money API gained checks and domestic wires as payment methods, treasury statement retrieval was added, and a Mercury node launched for the n8n automation platform.
Three SAFE data endpoints were added, webhooks and events gained account-balance notifications, and attachment uploads to transactions and recipients became available.
Webhooks were introduced so an integration can receive real-time notifications instead of polling, and recipient endpoints began returning associated attachments.
Build against v1 and track the changelog for additive changes.
Mercury API changelog ↗Bollard AI sits between a team's AI agents and Mercury. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.