mercury-api

Mercury API Skill

Last Updated: 2026-04-02 Mercury API Version: v1 Base URL: https://api.mercury.com/api/v1 Full Endpoint Index: references/endpoint-index.md (52 endpoints)

Overview

This skill provides structured access to the Mercury banking API. Read this document first for every Mercury interaction. It routes user intent to the correct domain reference document, provides authentication and pagination patterns, and defines safety gates for financial operations.

All Mercury endpoints share the same base URL, authentication, pagination, and error patterns. Use the decision tree below to identify the correct domain, then read the linked reference document for full endpoint schemas.

Authentication Quick Reference

All requests require a Mercury API token via the MERCURY_TOKEN environment variable. Before making any API call, verify the token is set:

echo ${MERCURY_TOKEN}

If the variable is empty, instruct the user to generate a token in their Mercury dashboard and set it in their environment.

Bearer Auth (preferred):

curl -s -H "Authorization: Bearer ${MERCURY_TOKEN}" \
  "https://api.mercury.com/api/v1/accounts"

Basic Auth (alternative):

curl -s -u "${MERCURY_TOKEN}:" \
  "https://api.mercury.com/api/v1/accounts"

Mercury tokens have three tiers: Read Only (GET operations only), Read and Write (all operations, requires IP whitelisting), and Custom (selected scopes). If a request returns 403, the token may lack required permissions or the IP may not be whitelisted.

For full authentication details including token setup, IP whitelisting, rotation, and auto-downgrade policies, read references/authentication.md.

Safety Classifications

Every Mercury endpoint carries one of three safety tiers. Follow these behavioral rules strictly.

SAFE (All GET Endpoints)

Execute the request directly without asking the user for permission. Present results in conversational language. Do not dump raw JSON.

CONFIRM (Non-Financial Write Operations)

These operations modify data but do not move money. Before executing:

1. Describe the operation in plain language, showing all details.
2. Ask the user for explicit confirmation.
3. Execute only after receiving approval.

Examples: create or edit a recipient, create or update an invoice, manage webhooks, update transaction metadata, upload attachments, create or delete a customer.

Gate language example: "I'll create a new recipient named 'Acme Corp' with ACH routing to the account ending in 4321. Should I go ahead?"

CRITICAL (Money Movement Operations)

These operations send real money and cannot be undone. Before executing:

1. Display ALL operation details: amount, source account, destination, payment method.
2. Present details in human-readable format with formatted currency.
3. Ask for explicit confirmation with a clear warning.
4. Execute only after receiving an explicit "yes."

Only two endpoints carry this tier:

• POST /account/{accountId}/request-send-money -- sends money to a recipient
• POST /transfer -- moves money between Mercury accounts

Gate language example: "CRITICAL: This will send $5,000.00 from your Operating Account to Acme Corp via ACH. This moves real money and cannot be undone. Please confirm by replying 'yes' to proceed."

Cowork Policy: Never execute any write operation silently. Agents must always present full operation details and wait for explicit user approval before executing CONFIRM or CRITICAL operations. This is a hard requirement aligned with Cowork's financial safety policy.

Decision Tree

Use this tree to route user requests to the correct domain and reference document.

If the user asks about money in their account, account balances, cards, statements, treasury, or credit: Read references/accounts-and-treasury.md

If the user asks about recent transactions, payment history, transaction details, or wants to tag or annotate a transaction: Read references/transactions.md

If the user asks to send money, pay someone, set up a payee, transfer funds between accounts, or manage payment recipients: Read references/recipients-and-payments.md

If the user asks to create an invoice, check invoice status, manage customers, or handle accounts receivable: Read references/accounts-receivable.md

If the user asks about webhooks, event notifications, or integration callbacks: Read references/webhooks-and-events.md

If the user asks about their organization, team members, spending categories, or SAFEs: Read references/organization-and-users.md

If the user asks about authentication, token setup, permissions, or IP whitelisting: Read references/authentication.md

Domain Summary

Domain	Endpoints	Example Triggers	Reference
Accounts & Treasury	11	"check my balance", "show my accounts", "treasury balances"	references/accounts-and-treasury.md
Transactions	4	"show recent transactions", "transaction details", "tag a payment"	references/transactions.md
Recipients & Payments	9	"send money to", "pay Acme Corp", "who did I pay", "transfer funds"	references/recipients-and-payments.md
Accounts Receivable	13	"create an invoice", "what invoices are outstanding", "add a customer"	references/accounts-receivable.md
Webhooks & Events	8	"set up notifications", "list webhooks", "recent events"	references/webhooks-and-events.md
Organization & Users	7	"who is on my team", "show categories", "organization info"	references/organization-and-users.md
Authentication	ref	"set up my API token", "check permissions", "IP whitelist"	references/authentication.md

For the complete 52-endpoint table with HTTP methods, paths, and safety classifications, see references/endpoint-index.md.

Pagination Pattern

All list endpoints use cursor-based pagination. The response envelope includes a page object with nextPage and previousPage cursor values.

First page:

curl -s -H "Authorization: Bearer ${MERCURY_TOKEN}" \
  "https://api.mercury.com/api/v1/transactions?limit=25"

Next page (using cursor from previous response):

curl -s -H "Authorization: Bearer ${MERCURY_TOKEN}" \
  "https://api.mercury.com/api/v1/transactions?limit=25&start_after=CURSOR_UUID"

Replace CURSOR_UUID with the page.nextPage value from the previous response. When page.nextPage is null, there are no more results. Supported parameters: limit, order, start_after, end_before.

Common Scenarios

Scenario 1: "Check my balance"

1. Execute: GET /accounts
2. Present results conversationally:
   • "You have 2 Mercury accounts:"
   • "Operating Account (checking): balance $50,000.00, available $49,500.00"
   • "Savings Account: balance $125,000.00, available $125,000.00"
3. If multiple accounts exist and the user asked about a specific one, filter by name or type.
4. If only one account exists, present it directly without asking which one.

Scenario 2: "Show recent transactions"

1. Ask a clarifying question if needed: "Would you like transactions from all accounts or a specific one? And for what time period?"
2. Execute: GET /transactions?limit=10 (or account-scoped variant)
3. Present as a formatted list:
   • "Here are your 10 most recent transactions:"
   • "January 15, 2026 -- Acme Corp -- -$1,500.00 (ACH)"
   • "January 14, 2026 -- Deposit -- +$10,000.00 (Wire)"
4. Offer to export: "Would you like me to save these as a spreadsheet (.xlsx)?"

Scenario 3: "Send $500 to Acme Corp"

1. This is a CRITICAL operation. Look up the recipient first: GET /recipients to find Acme Corp.
2. If the recipient is not found, inform the user and offer to create one (CONFIRM gate).
3. If multiple accounts exist, ask: "Which account should I send from -- checking or savings?"
4. Present full details before executing:
   • "CRITICAL: This will send $500.00 from your Operating Account to Acme Corp via ACH. This moves real money and cannot be undone. Please confirm by replying 'yes' to proceed."
5. Only after explicit confirmation, execute: POST /account/{accountId}/request-send-money

Scenario 4: "Create an invoice for Jane Doe"

1. This is a CONFIRM operation. Check if Jane Doe exists as a customer: GET /ar/customers
2. If not found, offer to create the customer first (also CONFIRM).
3. Gather required details: invoice amount, line items, due date, destination account.
4. Present full details before executing:
   • "I'll create an invoice for Jane Doe: 1 item -- 'Consulting Services' at $2,500.00, due February 15, 2026, payment deposited to your Operating Account. Should I go ahead?"
5. Only after confirmation, execute: POST /ar/invoices

Presentation Guidelines

Follow these rules when presenting Mercury API results to the user.

Currency: Format all monetary values as "$X,XXX.XX" with commas and two decimal places. Negative amounts represent debits: "-$1,500.00".

Dates: Format all dates as "Month DD, YYYY" (e.g., "January 15, 2026"). Do not use ISO timestamps in user-facing output.

Lists: Summarize the count before listing items: "Found 3 accounts:" or "Here are your 10 most recent transactions:".

UUIDs: Never show raw UUIDs to the user. Refer to resources by name, account nickname, or other human-readable identifiers.

Ambiguity: When a request is ambiguous, ask a clarifying question before proceeding:

• "Which account -- checking or savings?"
• "For what time period -- last 7 days, last 30 days, or a custom range?"
• "Did you mean the recipient named 'Acme Corp' or 'Acme LLC'?"

Raw JSON: Never present raw JSON API responses to the user. Always parse and format results into conversational language.

Document Output Guidance

Cowork has built-in document creation capabilities. Offer to save results as documents when appropriate:

Output Type	Format	When to Offer
Transaction exports	.xlsx	When listing more than 5 transactions, or when user asks for an export
Account statements	.pdf	When user requests a statement or account summary
Spending reports	.docx	When user asks for a spending breakdown or financial summary
Invoice lists	.xlsx	When listing multiple invoices or AR summaries

Mention that outputs can be saved to the workspace folder for the user to download or share.

Error Handling Quick Reference

When a Mercury API call returns an error, interpret the status code and present a helpful message to the user. Do not show raw error JSON.

Status	Meaning	What to Tell the User
400	Bad Request	"The request had invalid parameters. Let me fix that and try again."
401	Unauthorized	"The API token appears to be missing or invalid. Please check that MERCURY_TOKEN is set correctly."
403	Forbidden	"The token does not have permission for this operation. This may require a Read and Write token, or the IP address may need to be whitelisted."
404	Not Found	"That resource was not found. It may have been deleted or the ID may be incorrect."
409	Conflict	"There was a conflict (possibly a duplicate request). I'll check the original request status first rather than retrying with a new idempotency key."
422	Unprocessable Entity	"The request was valid but Mercury rejected it due to a business rule. Let me check the details."
429	Too Many Requests	"Mercury is rate-limiting requests. I'll wait a moment and try again."
500	Server Error	"Mercury is experiencing a server issue. I'll retry in a moment."
503	Service Unavailable	"Mercury is temporarily down. Wait and retry after 30 seconds."

Mercury error responses follow the format {"errors": [{"message": "..."}]}. Use the message field to provide specific context when available.

Observability

When executing Mercury API operations on behalf of the user, follow these reporting guidelines:

• Log which endpoint was called and whether it succeeded or failed.
• For failed requests, include the HTTP status code and error message in the report.
• Redact sensitive data from any logs or reports: never include full account numbers, routing numbers, token values, or recipient bank details.
• For CRITICAL operations, log the confirmation exchange (that confirmation was requested and received).

Last Updated

• Document Date: April 2, 2026
• Mercury API Version: v1 (/api/v1/)
• Endpoint Count: 52 (OAuth2 endpoints excluded; see references/endpoint-index.md)