# Banking API guide

Base URL: https://api.bankmcp.app/v1
Reference: https://docs.bankmcp.app/reference
Schema: https://docs.bankmcp.app/openapi.json

## Create an API key

Use Account → API keys at https://app.bankmcp.app/account, or the MCP `create_api_key` tool. MCP requires the explicit `api-keys:create` OAuth permission and the banking scopes for the requested API permissions. Reauthorize the assistant once if needed. Example arguments:

```json
{
  "name": "Spending dashboard",
  "permissions": ["accounts:read", "balances:read", "transactions:read"],
  "resources": { "type": "all" },
  "ttl_seconds": 604800
}
```

Omitted TTL means three UTC calendar months, clamped to month end. Custom TTL is a positive integer number of seconds, at most 2147483647. Omitted permissions and resources mean full access. The server rejects scope escalation instead of silently reducing access. The result includes the one-time secret, expiration, restrictions and API/docs URLs.

Keys have independent lifetimes: disconnecting the issuing assistant does not revoke them. Revocation, expiration, account deletion and explicit sign-out-everywhere stop access. Ordinary browser sign-out does not. Save the secret immediately; it cannot be retrieved again. A lost creation response requires inspecting your key list and explicitly creating a replacement, not blindly retrying.

## Permissions and resources

Each reference operation names its required permission. Resource restrictions are additional:

- `{"type":"all"}` allows all current and future accounts.
- `{"type":"banks","bank_ids":["DE:N26"]}` allows those connected banks, including their future accounts.
- `{"type":"accounts","account_ids":["account-id"]}` allows only those accounts. Grants retain stable internal identity through bank reconnection; discover current API account IDs again after reconnecting.

Account-only keys cannot run bank-wide refresh/import/disconnect or create connection links. Customer-wide merchant operations require all-account access and enabled enrichment. Out-of-scope resources return 404 without confirming their existence. Bank lists contain identity only, not balances. Linked wallet data from excluded accounts is not returned. API keys cannot create additional keys or sign in as a customer or administrator.

## Server-backed dashboard example

Set `BANKING_API_KEY` in your backend's secret environment. This Bun example requires a separate dashboard session, issued by your application's authentication layer. Do not expose the route publicly or use the banking key as a browser credential.

```ts
const api = 'https://api.bankmcp.app/v1';
const key = process.env.BANKING_API_KEY;
if (!key) throw new Error('Missing BANKING_API_KEY');

// Implement this using your application's existing authentication/session library.
import { requireDashboardUser } from './auth';

Bun.serve({
  port: 3000,
  async fetch(request) {
    const user = await requireDashboardUser(request);
    if (!user) return new Response('Unauthorized', { status: 401 });
    // This example is a single-owner dashboard. Multi-user apps must select a
    // different Banking key belonging to each signed-in user.
    const response = await fetch(`${api}/accounts`, {
      headers: { Authorization: `Bearer ${key}` },
    });
    if (!response.ok)
      return Response.json(
        { error: 'Bank data unavailable' },
        {
          status: response.status === 429 ? 429 : 502,
          headers: { 'Cache-Control': 'no-store' },
        },
      );
    const data = await response.json();
    return Response.json(data, { headers: { 'Cache-Control': 'no-store' } });
  },
});
```

For balances use `GET /accounts/{id}/balances`; for transactions use `GET /accounts/{id}/transactions?limit=100`. URL-encode IDs. Follow `next_cursor` with identical account/date filters until null. The maximum transaction page size is 500. Data may be incomplete: inspect `coverage`, `warning`, `retrieved_at` and `complete`. Reads do not refresh banks; request `POST /banks/{id}/refresh` explicitly and allow background jobs to finish. Connection links open the customer portal; the customer must approve the connection at their bank.

Amounts are exact decimal strings. Use decimal arithmetic, keep currencies separate, and avoid double-counting different balance types. Cross-account wallet links may be absent under restricted keys; do not infer invisible transactions or aggregate incomplete data as a full financial total.

## Errors and retries

Responses use `error`, `code`, and optional `action`. 400 means invalid input, 401 invalid/expired/revoked key, 403 missing permission or insufficient resource scope, 404 missing/inaccessible resource, 409 conflicting work, 413 oversized body, 429 rate limit, and 503 temporarily unavailable or disabled capability. There is no SQL endpoint. External merchant enrichment remains deployment-gated.

Limits: 300 requests/minute per key, user and client IP per Cloudflare location. User limits are shared with portal/MCP activity. On 429 wait for `Retry-After`. Request bodies are limited to 64 KiB. Retry transient reads with bounded backoff; do not blindly retry key creation or destructive actions.

The interactive reference talks directly to Banking without a proxy, and does not persist keys in local storage. Cross-origin browser calls are enabled for the docs origin; use a backend for dashboards.

## Replacement and revocation

Create a replacement key with the desired expiration, operations and accounts, update your backend environment, verify a request, then revoke the old key in Banking Account. Changing the display name does not affect access. Public API documentation does not remove the current pilot eligibility restriction.

## Command-line access

Install with `curl -fsS https://bankmcp.app/install.sh | sh`, then run
`banking auth login` and `banking accounts list`. See the [CLI guide](/cli.md)
for secure headless authentication, page-preserving exports and all commands.
