Blink 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

Prerequisites

• Node.js 18+
• 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 build

Getting an API Key

1. Log in to your Blink wallet at 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:

# 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):

{
  "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.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 [email protected]
Assistant: [Uses pay_lightning_address tool]
Payment of 1,000 sats sent successfully to [email protected]!

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 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. For detailed API documentation, visit:

• Blink Agent Playbook: Canonical AI agent API reference — order of operations, safety constraints, and verification checklist.
• Blink Developer Docs
• Blink API Playground
• 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

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
• Blink Developer Docs
• Blink Agent Playbook
• Model Context Protocol
• MCP SDK