Skip to main content
Glama
Blink MCP Server

Blink MCP Server

Official
by blinkbitcoin
README.md
# Blink MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that provides AI assistants with access to the [Blink](https://blink.sv) Bitcoin and Lightning Network API.

## Features

- **Lightning Network**: Create and pay invoices, send to Lightning addresses
- **On-Chain Bitcoin**: Generate addresses, send transactions, estimate fees
- **Stablesats (USD)**: Full support for USD-denominated wallets
- **Intraledger Transfers**: Free instant transfers between Blink users
- **Webhooks**: Register callbacks for payment notifications
- **Real-time Subscriptions**: Monitor invoice status and account updates
- **Price Data**: Get real-time and historical Bitcoin prices
- **L402 Consumer**: Discover, pay for, and cache tokens for L402-gated APIs
- **L402 Producer**: Create Lightning paywalls and verify payment tokens
- **L402 Discovery**: Search l402.directory and 402index.io for paid APIs

## Prerequisites

- Node.js 24+
- A Blink wallet account ([dashboard.blink.sv](https://dashboard.blink.sv))
- A Blink API key

## Installation

### From Source

```bash
git clone https://github.com/yourusername/blink-mcp.git
cd blink-mcp
npm install
npm run build
```

### Getting an API Key

1. Log in to your Blink wallet at [dashboard.blink.sv](https://dashboard.blink.sv)
2. Go to **Settings** > **API Keys**
3. Click **Create API Key**
4. Select the permissions you need:
   - **Read**: View balances, transactions, and account info
   - **Receive**: Create invoices and addresses to receive payments
   - **Write**: Send payments and modify account settings
5. Copy the generated API key

## Configuration

Set the following environment variables:

```bash
# Required: Your Blink API key
export BLINK_API_KEY=blink_xxxxxxxxxxxxx

# Optional: Network to use (default: mainnet)
export BLINK_NETWORK=mainnet  # or 'staging' for testnet
```

## Usage with Claude Desktop

Add to your Claude Desktop configuration (`~/.config/claude/claude_desktop_config.json` on Linux/Mac or `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "blink": {
      "command": "node",
      "args": ["/path/to/blink-mcp/dist/index.js"],
      "env": {
        "BLINK_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

Or if installed globally via npm:

```json
{
  "mcpServers": {
    "blink": {
      "command": "blink-mcp",
      "env": {
        "BLINK_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

## Usage with Other MCP Clients

The server uses stdio transport. Run it with:

```bash
BLINK_API_KEY=your_key node dist/index.js
```

## Available Tools

### Wallet & Account (17 tools)

| Tool                       | Description                          |
| -------------------------- | ------------------------------------ |
| `get_account_info`         | Get current user account information |
| `get_wallets`              | List all wallets with balances       |
| `get_wallet_balance`       | Get balance of a specific wallet     |
| `get_transactions`         | Get transaction history (paginated)  |
| `get_transaction_by_id`    | Get specific transaction details     |
| `get_account_limits`       | View withdrawal and transfer limits  |
| `set_default_wallet`       | Set default wallet (BTC or USD)      |
| `set_display_currency`     | Set display currency preference      |
| `get_realtime_price`       | Get current Bitcoin price            |
| `get_price_history`        | Get historical price data            |
| `convert_currency`         | Convert between fiat and Bitcoin     |
| `get_supported_currencies` | List supported currencies            |
| `lookup_user_wallet`       | Find wallet by Blink username        |
| `check_username_available` | Check username availability          |
| `set_username`             | Set/update your username             |
| `get_authorization_scopes` | View API key permissions             |
| `get_network_info`         | Get Lightning node info              |

### Lightning Network (12 tools)

| Tool                               | Description                      |
| ---------------------------------- | -------------------------------- |
| `create_invoice`                   | Create BTC Lightning invoice     |
| `create_invoice_usd`               | Create USD-denominated invoice   |
| `create_invoice_no_amount`         | Create open (any amount) invoice |
| `cancel_invoice`                   | Cancel unpaid invoice            |
| `get_invoice_status`               | Check invoice status by hash     |
| `get_invoice_status_by_request`    | Check status by bolt11           |
| `pay_invoice`                      | Pay a Lightning invoice          |
| `pay_invoice_with_amount`          | Pay open invoice with amount     |
| `pay_lightning_address`            | Send to Lightning address        |
| `pay_lnurl`                        | Pay via LNURL                    |
| `estimate_lightning_fee`           | Estimate payment fee             |
| `estimate_lightning_fee_no_amount` | Estimate fee for open invoice    |

### On-Chain Bitcoin (7 tools)

| Tool                          | Description                    |
| ----------------------------- | ------------------------------ |
| `create_onchain_address`      | Generate new receiving address |
| `get_current_onchain_address` | Get current address            |
| `send_onchain`                | Send BTC on-chain              |
| `send_onchain_all`            | Sweep entire balance           |
| `send_onchain_usd`            | Send from USD wallet on-chain  |
| `estimate_onchain_fee`        | Estimate BTC transaction fee   |
| `estimate_onchain_fee_usd`    | Estimate USD wallet fee        |

### Intraledger (Blink-to-Blink) (3 tools)

| Tool                 | Description                           |
| -------------------- | ------------------------------------- |
| `send_to_wallet`     | Send BTC to wallet ID (free, instant) |
| `send_to_wallet_usd` | Send USD to wallet ID                 |
| `send_to_username`   | Send to Blink username                |

### Webhooks & Subscriptions (9 tools)

| Tool                               | Description                     |
| ---------------------------------- | ------------------------------- |
| `list_webhooks`                    | List registered webhooks        |
| `add_webhook`                      | Register webhook endpoint       |
| `remove_webhook`                   | Remove webhook                  |
| `subscribe_invoice_status`         | Subscribe to invoice updates    |
| `subscribe_invoice_status_by_hash` | Subscribe by payment hash       |
| `subscribe_account_updates`        | Subscribe to all account events |
| `subscribe_price_updates`          | Subscribe to price changes      |
| `list_subscriptions`               | List active subscriptions       |
| `cancel_subscription`              | Cancel a subscription           |
| `cancel_all_subscriptions`         | Cancel all subscriptions        |

### L402 Protocol (6 tools)

| Tool                     | Description                                                        |
| ------------------------ | ------------------------------------------------------------------ |
| `l402_discover`          | Probe a URL for L402 payment requirements (no payment)             |
| `l402_pay`               | Access an L402-protected URL, paying automatically via Blink       |
| `l402_store`             | Manage the L402 token cache (~/.blink/l402-tokens.json)            |
| `l402_challenge_create`  | Create an L402 payment challenge (invoice + signed macaroon)       |
| `l402_payment_verify`    | Verify an L402 payment token (preimage + HMAC signature + caveats) |
| `l402_search`            | Search L402 service directories (l402.directory or 402index.io)    |

## Example Conversations

### Check Balance

```
User: What's my Bitcoin balance?
Assistant: [Uses get_wallets tool]
Your BTC wallet has 50,000 sats and your USD wallet has $12.50.
```

### Create Invoice

```
User: Create an invoice for 10,000 sats
Assistant: [Uses create_invoice tool]
Here's your Lightning invoice for 10,000 sats:
lnbc100u1p...
```

### Send Payment

```
User: Send 1000 sats to user@blink.sv
Assistant: [Uses pay_lightning_address tool]
Payment of 1,000 sats sent successfully to user@blink.sv!
```

### Monitor Invoice

```
User: Let me know when invoice lnbc... is paid
Assistant: [Uses subscribe_invoice_status tool]
I'm now monitoring the invoice. I'll notify you when it's paid.
```

## Development

```bash
# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode
npm run dev

# Type checking
npm run typecheck

# Linting
npm run lint
```

## Architecture

```
src/
├── index.ts              # MCP server entry point
├── client.ts             # Blink GraphQL client
├── types.ts              # TypeScript type definitions
├── graphql/
│   └── operations.ts     # GraphQL queries, mutations, subscriptions
└── tools/
    ├── wallet.ts         # Wallet and account tools
    ├── lightning.ts      # Lightning Network tools
    ├── onchain.ts        # On-chain Bitcoin tools
    ├── intraledger.ts    # Blink-to-Blink transfer tools
    ├── webhooks.ts       # Webhook and subscription tools
    └── l402.ts           # L402 consumer, producer, and discovery tools
```

## API Reference

This MCP server wraps the [Blink GraphQL API](https://dev.blink.sv/). For detailed API documentation, visit:

- [Blink Agent Playbook](https://dev.blink.sv/api/agent-playbook): Canonical AI agent API reference — order of operations, safety constraints, and verification checklist.
- [Blink Developer Docs](https://dev.blink.sv/)
- [Blink API Playground](https://api.blink.sv/)
- [llms.txt](https://dev.blink.sv/llms.txt): Machine-readable discovery metadata for AI agents.

## Security Considerations

- **API Key Security**: Never commit your API key to version control
- **Permission Scoping**: Use the minimum required permissions for your use case
- **Write Operations**: Be cautious with write permissions as they allow sending funds
- **Environment Variables**: Store API keys in environment variables, not in config files

### Spend Guard

Because this server holds a Blink API key and exposes tools that move funds, an
agent processing untrusted content (a web page, email, invoice memo, etc.) could
be steered into making a payment via indirect prompt injection. To mitigate
this, every money-moving tool passes through a central **spend guard** before it
executes, enforcing (in order): recipient allowlist → per-transaction cap →
rolling 24h budget → **human confirmation**. Webhook changes (`add_webhook`,
`remove_webhook`) pass through the same confirmation step.

The guard is **safe-by-default**: with no configuration, all spend tools and
webhook changes require explicit confirmation before running.

| Variable | Default | Effect |
| -------- | ------- | ------ |
| `BLINK_REQUIRE_CONFIRMATION` | `true` | Require confirmation before any spend or webhook change |
| `BLINK_APPROVAL_MODE` | `fail-closed` | Fallback when the client can't do elicitation: `fail-closed` or `stderr-code` |
| `BLINK_MAX_PAYMENT_SATS` | _(none)_ | Per-transaction cap in sats (authoritative for all spends, incl. `l402_pay`) |
| `BLINK_DAILY_BUDGET_SATS` | _(none)_ | Rolling 24h spend cap in sats (durable across restarts) |
| `BLINK_RECIPIENT_ALLOWLIST` | _(none)_ | Allowed recipients (ln addr / username / btc addr / wallet id) |
| `BLINK_WEBHOOK_ALLOWLIST` | _(none)_ | Allowed webhook callback hostnames |
| `BLINK_L402_MAX_SATS` | `1000` | Mandatory default cap for `l402_pay` |
| `BLINK_L402_HOST_ALLOWLIST` | _(none)_ | **Required** for L402 network access; fail-closed when unset |

**Confirmation flow.** When the MCP client supports
[elicitation](https://modelcontextprotocol.io/), the guard prompts inline and
blocks until the user accepts — this is the preferred, injection-safe path.

For clients **without** elicitation support, a token returned through the tool
channel is *not* a human boundary (a prompt-injected loop could simply echo it
back), so there is no such token. Instead `BLINK_APPROVAL_MODE` controls the
fallback:

- **`fail-closed`** (default): the spend is refused.
- **`stderr-code`**: the server prints a one-time approval code to its **console
  (stderr)** — which the model cannot read — and the human operator re-issues
  the tool call with `approval_code="<code>"`. The code never enters model
  context, so injection alone cannot obtain it.

**Amount enforcement.** `BLINK_MAX_PAYMENT_SATS` and `BLINK_DAILY_BUDGET_SATS`
are enforced for every spend tool. Fixed-amount Lightning invoices are decoded
from the bolt11 before payment so `pay_invoice` is subject to the same caps and
budget as amount-carrying tools. USD-wallet amounts (`send_onchain_usd`,
`send_to_wallet_usd`, `send_to_username` with `wallet_currency: "USD"`) are in
cents; when a cap or budget is configured they are converted to sats at Blink's
current rate before being checked against it, and refused if the conversion
fails. For `l402_pay`, whose amount is only known after fetching the
invoice, the caps are re-checked *after decoding* and before payment.

The 24h budget is reserved atomically right before a payment executes, so
concurrent calls cannot overspend it. The reservation is released when the
payment definitely **fails** (failed attempts never burn budget) and kept when it
succeeds — or when the outcome is unknown (e.g. a timeout or a `PENDING`
payment), since the funds may have moved. It is persisted to a `0600` ledger at
`~/.blink/spend-ledger.json` so it survives restarts; the ledger is locked
against concurrent server processes, written atomically, and if it becomes
unreadable spends are refused (while a budget is configured) rather than the
budget silently resetting. A lock file left behind by a hard-killed process
(`~/.blink/spend-ledger.json.lock`) is never removed automatically; spends are
refused with an error naming the file until you delete it.

**Sweeps and undecodable amounts.** When a per-transaction cap or daily budget
is configured, `send_onchain_all` (full-balance sweep) and any `pay_invoice`
whose bolt11 amount cannot be decoded are **refused** — the amount cannot be
verified against the cap, so the guard fails closed rather than bypassing it.
With no caps configured, these still require confirmation.

**L402 hardening.** `l402_pay` enforces a mandatory spend cap
(`max_amount_sats` or `BLINK_L402_MAX_SATS`) plus the global caps above, and
refuses invoices whose amount cannot be decoded. Server-side L402 fetches
**require `BLINK_L402_HOST_ALLOWLIST`** (fail-closed when unset), are HTTPS-only,
and reject private, loopback, link-local and other non-public addresses
(including IPv4 embedded in IPv6). Redirects are followed manually and every hop
of every L402 request (the HEAD probe, the resource GET, and the l402-protocol
invoice POST) is re-validated before it is sent; credentials are dropped when a
redirect changes origin. Sockets are not pinned to the checked address, so DNS
rebinding is not fully closed: the host allowlist limits that exposure to hosts
you trust, so only allowlist hosts whose DNS you trust. Cached L402 tokens
are stored `0600`, and `l402_store get` masks payment secrets unless called
with `reveal: true`.

**Webhooks.** A webhook receives a notification for every payment on the
account, so registering one is treated like a spend: `add_webhook` and
`remove_webhook` require human confirmation (same flow as above).
`add_webhook` also requires an HTTPS URL with a DNS hostname (IP literals and
`localhost` are rejected) and, when `BLINK_WEBHOOK_ALLOWLIST` is set, a listed
hostname.

## Troubleshooting

### "BLINK_API_KEY environment variable is required"

Make sure you've set the `BLINK_API_KEY` environment variable with your API key.

### "GraphQL Error: Not authorized"

Your API key may not have the required permissions. Check your key's scopes in the Blink wallet settings.

### WebSocket connection issues

Real-time subscriptions require a stable connection. Check your network and firewall settings.

## License

MIT

## Contributing

Contributions are welcome! Please open an issue or submit a pull request.

## Links

- [Blink Wallet](https://blink.sv)
- [Blink Developer Docs](https://dev.blink.sv/)
- [Blink Agent Playbook](https://dev.blink.sv/api/agent-playbook)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [MCP SDK](https://github.com/modelcontextprotocol/sdk)

TDQS

B3.1/5.0

Scored across 55 tools

Disambiguation3/5

The BTC/USD tool pairs (send_onchain vs send_onchain_usd, send_to_wallet vs send_to_wallet_usd, estimate_onchain_fee vs estimate_onchain_fee_usd, create_invoice vs create_invoice_usd) and the invoice-status quartet (get_invoice_status, get_invoice_status_by_request, subscribe_invoice_status, subscribe_invoice_status_by_hash) create real selection friction. Descriptions do a decent job of explaining the differences, but an agent must read carefully to avoid picking the wrong variant. Multi-mode tools like l402_store (list/get/clear in one) add further ambiguity.

Naming Consistency3/5

Mostly snake_case verb_noun with a coherent variant-suffix scheme (_usd, _no_amount, _by_request, _by_hash, _all), which is readable. However the l402_ family is noun-prefixed with non-verb names (l402_discover, l402_store, l402_challenge_create) and a few tools use different molds (check_username_available, lookup_user_wallet), so it's mixed rather than uniform.

Tool Count2/5

55 tools is well above what a wallet API surface needs; many are near-duplicates that could be collapsed into one tool with a wallet/currency parameter (all the *_usd variants, the three create_invoice variants, the four estimate_*_fee tools). The L402 and subscription families are legitimate, but the BTC/USD duplication inflates the count significantly.

Completeness4/5

Coverage is strong: receive (invoices, on-chain addresses), send (invoice, LNURL, lightning address, intraledger, on-chain sweep), fees, webhooks, real-time subscriptions, account settings, and a full L402 client+server flow. Minor gaps exist — no explicit USD-wallet invoice payment tool (create_invoice_usd has no pay counterpart), no webhook get/update-by-id, and no contacts directory.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues