Blink MCP Server
OfficialThis Blink MCP server lets an AI assistant interact with a Blink Bitcoin/Lightning wallet and L402 paid APIs through MCP tools.
Wallet & account management: view account info, wallets, balances, transactions, limits, authorization scopes, network info, set default wallet/display currency, manage username.
Price & currency data: get real-time BTC prices, historical prices, supported currencies, and fiat/BTC conversion estimates.
Lightning Network: create BTC/USD/open invoices, cancel/check invoices, pay invoices, pay Lightning addresses or LNURL, and estimate Lightning fees.
On-chain Bitcoin: generate/get receiving addresses, send BTC or sweep balances, send from USD wallets, and estimate on-chain fees.
Intraledger transfers: send BTC or USD instantly to Blink wallet IDs or usernames for free.
Webhooks & subscriptions: register/list/remove webhooks and monitor invoice status, account updates, or price updates in real time.
L402 consumer: discover and pay for L402-protected URLs, with token caching and spend limits.
L402 producer: create Lightning paywalls and verify L402 payment tokens/macaroons.
L402 discovery: search l402.directory or 402index.io for paid APIs.
Safety controls: money-moving tools and webhook changes pass through a spend guard with confirmation, optional payment caps, daily budgets, recipient/webhook allowlists, and L402 host restrictions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Blink MCP Server what's my Bitcoin wallet balance?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Blink MCP Server
A Model Context Protocol (MCP) server that provides AI assistants with access to the Blink 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
Related MCP server: RGB Lightning Network MCP Server
Prerequisites
Node.js 24+
A Blink wallet account (dashboard.blink.sv)
A Blink API key
Installation
From Source
git clone https://github.com/yourusername/blink-mcp.git
cd blink-mcp
npm install
npm run buildGetting an API Key
Log in to your Blink wallet at dashboard.blink.sv
Go to Settings > API Keys
Click Create API Key
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
Copy the generated API key
Configuration
Set the following environment variables:
# Required: Your Blink API key
export BLINK_API_KEY=blink_xxxxxxxxxxxxx
# Optional: Network to use (default: mainnet)
export BLINK_NETWORK=mainnet # or 'staging' for testnetUsage 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):
{
"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:
{
"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:
BLINK_API_KEY=your_key node dist/index.jsAvailable Tools
Wallet & Account (17 tools)
Tool | Description |
| Get current user account information |
| List all wallets with balances |
| Get balance of a specific wallet |
| Get transaction history (paginated) |
| Get specific transaction details |
| View withdrawal and transfer limits |
| Set default wallet (BTC or USD) |
| Set display currency preference |
| Get current Bitcoin price |
| Get historical price data |
| Convert between fiat and Bitcoin |
| List supported currencies |
| Find wallet by Blink username |
| Check username availability |
| Set/update your username |
| View API key permissions |
| Get Lightning node info |
Lightning Network (12 tools)
Tool | Description |
| Create BTC Lightning invoice |
| Create USD-denominated invoice |
| Create open (any amount) invoice |
| Cancel unpaid invoice |
| Check invoice status by hash |
| Check status by bolt11 |
| Pay a Lightning invoice |
| Pay open invoice with amount |
| Send to Lightning address |
| Pay via LNURL |
| Estimate payment fee |
| Estimate fee for open invoice |
On-Chain Bitcoin (7 tools)
Tool | Description |
| Generate new receiving address |
| Get current address |
| Send BTC on-chain |
| Sweep entire balance |
| Send from USD wallet on-chain |
| Estimate BTC transaction fee |
| Estimate USD wallet fee |
Intraledger (Blink-to-Blink) (3 tools)
Tool | Description |
| Send BTC to wallet ID (free, instant) |
| Send USD to wallet ID |
| Send to Blink username |
Webhooks & Subscriptions (9 tools)
Tool | Description |
| List registered webhooks |
| Register webhook endpoint |
| Remove webhook |
| Subscribe to invoice updates |
| Subscribe by payment hash |
| Subscribe to all account events |
| Subscribe to price changes |
| List active subscriptions |
| Cancel a subscription |
| Cancel all subscriptions |
L402 Protocol (6 tools)
Tool | Description |
| Probe a URL for L402 payment requirements (no payment) |
| Access an L402-protected URL, paying automatically via Blink |
| Manage the L402 token cache (~/.blink/l402-tokens.json) |
| Create an L402 payment challenge (invoice + signed macaroon) |
| Verify an L402 payment token (preimage + HMAC signature + caveats) |
| 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
# Install dependencies
npm install
# Build TypeScript
npm run build
# Run in development mode
npm run dev
# Type checking
npm run typecheck
# Linting
npm run lintArchitecture
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 toolsAPI Reference
This MCP server wraps the Blink GraphQL API. For detailed API documentation, visit:
Blink Agent Playbook: Canonical AI agent API reference — order of operations, safety constraints, and verification checklist.
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 |
|
| Require confirmation before any spend or webhook change |
|
| Fallback when the client can't do elicitation: |
| (none) | Per-transaction cap in sats (authoritative for all spends, incl. |
| (none) | Rolling 24h spend cap in sats (durable across restarts) |
| (none) | Allowed recipients (ln addr / username / btc addr / wallet id) |
| (none) | Allowed webhook callback hostnames |
|
| Mandatory default cap for |
| (none) | Required for L402 network access; fail-closed when unset |
Confirmation flow. When the MCP client supports elicitation, 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 withapproval_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
Available Tools
55 toolsadd_webhookB
Register a new webhook callback endpoint to receive payment notifications
Inputs: url (required).
cancel_all_subscriptionsA
Cancel all active real-time subscriptions
Inputs: no named parameters.
cancel_invoiceA
Cancel an unpaid Lightning invoice
Inputs: wallet_id (required), payment_hash (required).
cancel_subscriptionB
Cancel an active real-time subscription
Inputs: subscription_id (required).
check_username_availableA
Check if a Blink username is available
Inputs: username (required).
convert_currencyC
Get currency conversion estimation between fiat and Bitcoin
Inputs: amount (required), currency (required).
create_invoiceB
Create a Lightning invoice to receive a specific amount of Bitcoin. Amount is in satoshis for BTC wallet.
Inputs: amount (required), wallet_id (required), memo, expires_in, +1 more.
create_invoice_no_amountA
Create a Lightning invoice without a specified amount (open invoice). The payer can choose how much to send.
Inputs: wallet_id (required), memo, expires_in, external_id.
create_invoice_usdA
Create a Lightning invoice to receive a specific amount in USD cents (Stablesats). The invoice will be denominated in satoshis but credited as USD.
Inputs: amount (required), wallet_id (required), memo, expires_in, +1 more.
create_onchain_addressA
Generate a new on-chain Bitcoin address to receive funds
Inputs: wallet_id (required).
estimate_lightning_feeA
Estimate the Lightning network fee for paying an invoice
Inputs: wallet_id (required), payment_request (required).
estimate_lightning_fee_no_amountB
Estimate the Lightning network fee for paying an open (no-amount) invoice
Inputs: amount (required), wallet_id (required), payment_request (required).
estimate_onchain_feeB
Estimate the on-chain transaction fee for sending Bitcoin (BTC wallet)
Inputs: amount (required), address (required), wallet_id (required), speed.
estimate_onchain_fee_usdA
Estimate the on-chain transaction fee for sending from USD wallet
Inputs: amount (required), address (required), wallet_id (required), speed.
get_account_infoA
Get the current user account information including wallets, balances, and settings
Inputs: no named parameters.
get_account_limitsA
Get the current account limits for withdrawals, internal sends, and currency conversion
Inputs: no named parameters.
get_authorization_scopesA
Get the permission scopes available for the current API key
Inputs: no named parameters.
get_current_onchain_addressA
Get the current (most recent) on-chain Bitcoin address for a wallet
Inputs: wallet_id (required).
get_invoice_statusA
Check the payment status of a Lightning invoice by payment hash
Inputs: payment_hash (required).
get_invoice_status_by_requestA
Check the payment status of a Lightning invoice by payment request (bolt11)
Inputs: payment_request (required).
get_network_infoA
Get global network information including Lightning node details and fee information
Inputs: no named parameters.
get_price_historyA
Get Bitcoin price history for a specified time range
Inputs: range (required).
get_realtime_priceA
Get the current real-time Bitcoin price in a specified currency
Inputs: currency.
get_supported_currenciesB
Get list of all supported display currencies
Inputs: no named parameters.
get_transaction_by_idB
Get details of a specific transaction by ID
Inputs: wallet_id (required), transaction_id (required).
get_transactionsB
Get transaction history for one or more wallets. Supports pagination.
Inputs: limit, cursor, wallet_ids.
get_wallet_balanceA
Get the balance of a specific wallet by ID. Returns balance in satoshis (BTC) or cents (USD).
Inputs: wallet_id (required).
get_walletsA
Get all wallets (BTC and USD) with their current balances. Balance is in satoshis for BTC wallet and cents for USD wallet.
Inputs: no named parameters.
l402_challenge_createA
Create an L402 payment challenge (invoice + signed macaroon) to protect a resource behind a Lightning paywall. Returns a WWW-Authenticate header that can be sent to clients with HTTP 402.
Inputs: amount_sats (required), memo, resource, wallet_id, +1 more.
l402_discoverA
Probe a URL for L402 payment requirements without paying. Returns the invoice, price in sats, and format (lightning-labs or l402-protocol). Use this before l402_pay to check the cost of accessing a resource.
Inputs: url (required), method.
l402_payA
Access an L402-protected URL by automatically paying the Lightning invoice. Checks the token cache first to avoid re-paying. Returns the response data from the protected resource after successful payment.
Inputs: url (required), wallet_id (required), force, method, +2 more.
l402_payment_verifyA
Verify an L402 payment token submitted by a client. Checks three layers: 1) preimage proves payment (SHA-256), 2) HMAC signature proves authenticity, 3) caveats (expiry, resource) are satisfied. Returns valid: true/false.
Inputs: token, macaroon, preimage, resource.
l402_searchA
Search L402 service directories to find paid APIs that can be accessed with Lightning payments. Default source: l402.directory (curated, rich schema). Alternative: 402index.io (broader coverage, 50+ services).
Inputs: query, source, status, category.
l402_storeA
Manage the local L402 token cache at ~/.blink/l402-tokens.json. List cached tokens (with masked sensitive data), get a token for a domain, or clear tokens.
Inputs: command (required), domain, reveal, expired_only.
list_subscriptionsA
List all active real-time subscriptions
Inputs: no named parameters.
list_webhooksA
List all registered webhook callback endpoints for the account
Inputs: no named parameters.
lookup_user_walletB
Look up a user's default wallet by their Blink username
Inputs: username (required), wallet_currency.
pay_invoiceB
Pay a Lightning invoice. The invoice amount must be specified in the invoice.
Inputs: wallet_id (required), payment_request (required), memo.
pay_invoice_with_amountB
Pay a Lightning invoice that has no amount specified (open invoice). You specify the amount to send.
Inputs: amount (required), wallet_id (required), payment_request (required), memo.
pay_lightning_addressC
Send Bitcoin to a Lightning Address (e.g., user@blink.sv)
Inputs: amount (required), wallet_id (required), ln_address (required).
pay_lnurlC
Pay using an LNURL (Lightning URL)
Inputs: lnurl (required), amount (required), wallet_id (required).
remove_webhookB
Remove a registered webhook callback endpoint
Inputs: id (required).
send_onchainC
Send Bitcoin on-chain to a Bitcoin address. Amount is in satoshis for BTC wallet.
Inputs: amount (required), address (required), wallet_id (required), memo, +1 more.
send_onchain_allB
Send the entire wallet balance on-chain to a Bitcoin address (sweep)
Inputs: address (required), wallet_id (required), memo, speed.
send_onchain_usdC
Send on-chain Bitcoin from a USD (Stablesats) wallet. Amount is in cents.
Inputs: amount (required), address (required), wallet_id (required), memo, +1 more.
send_to_usernameA
Send Bitcoin to a Blink user by their username. This looks up their wallet and does an intraledger transfer (free, instant).
Inputs: amount (required), username (required), wallet_id (required), memo, +1 more.
send_to_walletA
Send Bitcoin directly to another Blink wallet (free, instant, intraledger transfer). Amount is in satoshis for BTC wallets.
Inputs: amount (required), wallet_id (required), recipient_wallet_id (required), memo.
send_to_wallet_usdA
Send USD (Stablesats) directly to another Blink wallet (free, instant, intraledger transfer). Amount is in cents.
Inputs: amount (required), wallet_id (required), recipient_wallet_id (required), memo.
set_default_walletA
Set the default wallet for the account (BTC or USD wallet)
Inputs: wallet_id (required).
set_display_currencyB
Set the display currency for the account (e.g., USD, EUR, BTC)
Inputs: currency (required).
set_usernameA
Set or update the username for the current user
Inputs: username (required).
subscribe_account_updatesA
Subscribe to all real-time account updates including incoming/outgoing transactions and price updates
Inputs: no named parameters.
subscribe_invoice_statusC
Subscribe to real-time updates for a Lightning invoice payment status. Returns a subscription ID to track or cancel.
Inputs: payment_request (required).
subscribe_invoice_status_by_hashB
Subscribe to real-time updates for a Lightning invoice by payment hash
Inputs: payment_hash (required).
subscribe_price_updatesC
Subscribe to real-time Bitcoin price updates in a specified currency
Inputs: currency.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 55 tools
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.
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.
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.
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
Related MCP Connectors
Give AI agents a Bitcoin wallet with Lightning Network payments and L402 support.
Non-custodial crypto payments for AI assistants: balances, payments, and create payment links.
Crypto pay links and API for people and AI agents. BTC, Lightning, USDC, USDT, EURC, SOL, ETH.
Pay-per-action access to APIs and MCP tools over Lightning L402 and Base USDC x402.
Related MCP Servers
- AlicenseBqualityFmaintenanceEnables interaction with lightning addresses and common lightning tools via your LLM, providing Lightning Network functionality through natural language.313 npm1MIT
- AlicenseBqualityDmaintenanceEnables AI assistants to interact with RGB assets, Lightning Network operations, and Bitcoin transactions through RGB Lightning Node APIs. Supports asset management, invoice creation/payment, channel management, on-chain transactions, and asset swaps.1810 npm1MIT
- AlicenseNot gradedqualityDmaintenanceEnables Bitcoin Lightning wallet integration with LLMs through Nostr Wallet Connect (NWC). Supports lightning payments, LNURL operations, and L402 authentication for AI-powered bitcoin transactions.Apache 2.0

Breez MCP Serverofficial
AlicenseNot gradedqualityCmaintenanceEnables Lightning Network wallet operations through the Breez SDK, allowing users to check balances, send/receive payments, create invoices, and manage Bitcoin Lightning transactions via natural language.7MIT