Imported from manifoldlogic/claude-code-plugins (plugins/mercury/skills/mercury-api/SKILL.md). Install upstream with npx skills add manifoldlogic/claude-code-plugins --skill mercury-api. Copyright stays with the author.

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

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:

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.

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)