# SimplePay API

Fake peer-to-peer card transaction data for testing. No authentication, no API keys, no rate limits.

Base URL: `https://bank.decagon.tools`

## Connect the MCP server (Claude Code)

SimplePay exposes a Model Context Protocol server so agents such as Claude Code can call it directly as a tool. No authentication.

- MCP endpoint: `POST https://bank.decagon.tools/api/public/mcp` (streamable HTTP / JSON-RPC 2.0)
- `GET https://bank.decagon.tools/api/public/mcp` for a plain JSON description of the server.

### Option 1 — one terminal command

```bash
claude mcp add --transport http simplepay https://bank.decagon.tools/api/public/mcp
```

That's it. Restart Claude Code (or run `claude mcp list` to confirm), then ask it things like "list the SimplePay users" or "get Toby Tyler's transactions for September 2026".

### Option 2 — config file

Add this to `.mcp.json` (project) or `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "simplepay": {
      "type": "http",
      "url": "https://bank.decagon.tools/api/public/mcp"
    }
  }
}
```

### MCP tools

**`list_users`** — no arguments. Lists every person with their string user ID, name, account number, email and phone. Use this first to discover a `user_id`.

**`get_transactions`** — look up transactions by user ID and date range.

| Argument | Required | Notes |
| --- | --- | --- |
| `user_id` | yes | String user ID (e.g. `usr_toby_tyler_2254`) or internal UUID. |
| `from` | no | Inclusive start date/time, ISO 8601. |
| `to` | no | Inclusive end date/time, ISO 8601. |
| `merchant_name` | no | Filter by counterparty/merchant name, case-insensitive partial match. |
| `limit` | no | 1–1000, default 500. |

**`get_transaction`** — fetch one transaction's full details. Single required argument `transaction_id` (the `transaction_id`/`id` returned by `get_transactions`).

All tools return JSON text content plus `structuredContent` with the same shape as the matching REST endpoint. Failures come back as a tool result with `isError: true` and an `error` message.

### Raw JSON-RPC example (no MCP client needed)

```bash
curl -X POST "https://bank.decagon.tools/api/public/mcp" \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_transactions","arguments":{"user_id":"usr_toby_tyler_2254","from":"2026-09-01","to":"2026-09-30"}}}'
```

Supported methods: `initialize`, `tools/list`, `tools/call`, `ping`.

## GET /api/public/transactions

Returns every transaction for one person, newest first.

### Query parameters

| Name | Required | Notes |
| --- | --- | --- |
| `user_id` | yes | The person's string user ID (e.g. `usr_toby_tyler_2254`). The internal UUID also works. Alias: `userId`. |
| `from` | no | Inclusive start date/time, ISO 8601 (`2026-09-01` or `2026-09-01T00:00:00Z`). Alias: `start_date`. |
| `to` | no | Inclusive end date/time, ISO 8601. Alias: `end_date`. |
| `merchant_name` | no | Filter by counterparty/merchant name, case-insensitive partial match. Alias: `merchant`. |
| `limit` | no | 1–1000, default 500. |

### Example

```bash
curl "https://bank.decagon.tools/api/public/transactions?user_id=usr_toby_tyler_2254&from=2026-09-01&to=2026-09-30"
```

### Response

```json
{
  "user_id": "usr_toby_tyler_2254",
  "user_name": "Toby Tyler",
  "account_number": "7131463462",
  "date_range": { "from": "2026-09-01", "to": "2026-09-30" },
  "count": 1,
  "transactions": [
    {
      "id": "a7963676-9d48-4d4c-b9e8-191d7ba9d4ec",
      "transaction_id": "a7963676-9d48-4d4c-b9e8-191d7ba9d4ec",
      "amount": 42.18,
      "date": "2026-09-16T16:51:14.317364+00:00",
      "merchant_name": "Jordan Avery",
      "account_type": "business",
      "type": "USD",
      "currency_code": "USD",
      "status": "posted"
    }
  ]
}
```

### Field reference

- `id` / `transaction_id` — the transaction's unique ID (same value, both keys are always present). Use it with `GET /api/public/transactions/{transaction_id}`.
- `amount` — number. Up to 8 decimal places for crypto, 2 for USD.
- `date` — ISO 8601 timestamp of the transaction.
- `merchant_name` — counterparty (a person for p2p transfers, or a merchant).
- `account_type` — `business` | `merchant`.
- `type` — `USD` | `crypto`.
- `currency_code` — `USD`, `BTC`, `ETH`, `USDC`, `SOL`.
- `status` — `pending` | `posted` | `declined` | `refunded`.

### Errors

| Status | Body | Meaning |
| --- | --- | --- |
| 400 | `{"error":"user_id query parameter is required"}` | Missing `user_id`. |
| 404 | `{"error":"Unknown user_id"}` | No person with that ID. |
| 500 | `{"error":"..."}` | Server-side failure. |

CORS is open (`Access-Control-Allow-Origin: *`); `OPTIONS` returns 204.

## GET /api/public/transactions/{transaction_id}

Returns the full details of a single transaction, including which person it belongs to. No query parameters, no auth.

```bash
curl "https://bank.decagon.tools/api/public/transactions/a7963676-9d48-4d4c-b9e8-191d7ba9d4ec"
```

```json
{
  "transaction": {
    "id": "a7963676-9d48-4d4c-b9e8-191d7ba9d4ec",
    "transaction_id": "a7963676-9d48-4d4c-b9e8-191d7ba9d4ec",
    "amount": 42.18,
    "date": "2026-09-16T16:51:14.317364+00:00",
    "merchant_name": "Jordan Avery",
    "account_type": "business",
    "type": "USD",
    "currency_code": "USD",
    "status": "posted",
    "created_at": "2026-09-16T16:51:14.317364+00:00",
    "user_id": "usr_toby_tyler_2254",
    "user_name": "Toby Tyler",
    "account_number": "7131463462"
  }
}
```

| Status | Body | Meaning |
| --- | --- | --- |
| 400 | `{"error":"Invalid transaction id"}` | Not a valid transaction ID. |
| 404 | `{"error":"Unknown transaction id"}` | No transaction with that ID. |

## Machine-readable endpoints

- `GET https://bank.decagon.tools/api/public/docs` — this document as Markdown (`?format=json` for JSON).
- `GET https://bank.decagon.tools/api/public/openapi.json` — OpenAPI 3.1 spec.
- `POST https://bank.decagon.tools/api/public/mcp` — MCP server (see above).