blink

Bitcoin Lightning wallet operations via the Blink API. Enables agents to check balances, receive payments via invoices, send payments over Lightning, track transactions, monitor prices, and automatically pay for L402-gated web services.

What is Blink?

Blink is a custodial Bitcoin Lightning wallet with a GraphQL API. Key concepts:

• API Key — authentication token (format: blink_...) with scoped permissions (Read, Receive, Write)
• BTC Wallet — balance denominated in satoshis
• USD Wallet — balance denominated in cents (stablecoin pegged to USD)
• Lightning Invoice — BOLT-11 payment request string (lnbc...) used to receive payments
• Lightning Address — human-readable address (user@domain) for sending payments without an invoice
• LNURL — protocol for interacting with Lightning services via encoded URLs
• L402 — HTTP payment protocol (RFC draft) that gates resources behind a Lightning invoice. Servers return HTTP 402 with a macaroon + invoice; clients pay and retry with the token.

Environment

• Requires bash and Node.js 18+.
• Requires BLINK_API_KEY environment variable with appropriate scopes.
• For WebSocket subscriptions: Node 22+ (native) or Node 20+ with --experimental-websocket.
• Zero runtime npm dependencies. Only Node.js built-in modules are used (node:util, node:fs, node:path, node:child_process).

Use this skill for concrete wallet operations, not generic Lightning theory.

Getting Started

1. Get your API key

1. Create a free account at dashboard.blink.sv.
2. Go to API Keys and create a key with the scopes you need.
3. Set it in your environment:

export BLINK_API_KEY="blink_..."

API Key Scopes:

• Read — query balances, transaction history, price, account info
• Receive — create invoices
• Write — send payments (use with caution)

Tip: Start with Read + Receive only. Add Write when you need to send payments.

2. Verify it works

node {baseDir}/scripts/balance.js

If you see JSON with your wallet balances, you're ready.

3. Staging / Testnet (recommended for first-time setup)

To use the Blink staging environment (signet) instead of real money:

export BLINK_API_URL="https://api.staging.blink.sv/graphql"

Create a staging API key at dashboard.staging.blink.sv. The staging environment uses signet bitcoin (no real value) — perfect for testing payment flows safely.

If BLINK_API_URL is not set, production (https://api.blink.sv/graphql) is used by default.

API key auto-detection

Scripts automatically resolve BLINK_API_KEY using this order:

1. process.env.BLINK_API_KEY (checked first)
2. Shell rc files: ~/.profile, ~/.bashrc, ~/.bash_profile, ~/.zshrc — scanned for an export BLINK_API_KEY=... line only

No source ~/.profile prefix is needed. The rc file scan uses a targeted regex that reads only the BLINK_API_KEY export line — no other data is extracted from these files.

Optional: CLI wrapper (full GitHub repo only)

If you have cloned the full GitHub repo, you can optionally install a blink CLI command:

npm install   # install dev dependencies (eslint, prettier)
npm link      # creates global 'blink' command
blink --help  # verify

Note: npm link modifies global npm state. This is optional — all functionality is available by running scripts directly with node {baseDir}/scripts/<script>.js. The ClawHub-installed version does not require or use npm link.

Agent Safety Policy

These rules are mandatory for any AI agent using this skill:

1. Ask before spending. Never execute pay-invoice, pay-lnaddress, pay-lnurl, or swap-execute without explicit user confirmation of the amount and recipient.
2. Dry-run first. For swaps, always run with --dry-run before executing for real unless the user explicitly says to skip it.
3. Check balance before sending. Always run balance before any payment or swap to verify sufficient funds.
4. Probe fees before paying. Run fee-probe before pay-invoice to show the user the fee cost.
5. Use minimum scopes. Only request Write-scoped API keys when send operations are actually needed.
6. Never log or display the API key. Treat BLINK_API_KEY as a secret. Do not echo it, include it in messages, or write it to files.
7. Prefer staging for testing. When the user is testing or learning, suggest setting BLINK_API_URL to the staging endpoint.
8. Respect irreversibility. Warn the user that Lightning payments and swaps cannot be reversed once executed.
9. L402 auto-pay requires confirmation. Never call l402-pay without dry-running first (--dry-run) and confirming the satoshi amount with the user. The token cache (~/.blink/l402-tokens.json) means subsequent calls may reuse a paid token silently — inform the user when a cached token is used.

Bitcoin Units

• BTC wallet amounts are always in satoshis (sats). 1 BTC = 100,000,000 sats.
• USD wallet amounts are always in cents. $1.00 = 100 cents.
• When displaying amounts to users, use the formatted fields from output JSON (e.g. btcBalanceUsdFormatted, usdBalanceFormatted).
• Do not perform manual BTC-to-USD conversion math — use blink price <sats> or the btcBalanceUsd field from balance output instead.
• For swap amounts, the --unit flag controls interpretation: sats for BTC, cents for USD.

Workflow

1. Pick the operation path first:

• Receive payments (invoice creation, QR codes, payment monitoring).
• Send payments (invoice pay, Lightning Address, LNURL, BTC or USD wallet).
• Swap between wallets (BTC <-> USD internal conversion).
• Read-only queries (balance, transactions, price, account info).

2. Configure API access from blink-api-and-auth:

• Set BLINK_API_KEY with the correct scopes for your operation.
• Optionally set BLINK_API_URL for staging/testnet.
• Verify connectivity with blink balance.

3. For sending payments, follow payment-operations:

• Check balance before sending.
• Probe fees with blink fee-probe.
• Choose BTC or USD wallet with --wallet flag.
• Execute payment and verify in transaction history.

4. For receiving payments, follow invoice-lifecycle:

• Create BTC or USD invoice.
• Parse two-phase output (invoice created, then payment resolution).
• Generate QR code and send to payer.
• Monitor via auto-subscribe, polling, or standalone subscription.

5. For swapping between wallets, follow swap-operations:

• Quote first with blink swap-quote.
• Review quote terms (amountIn/amountOut, exchange rate).
• Execute with blink swap-execute (use --dry-run first).
• Verify settlement from postBalance/balanceDelta.

6. For accessing L402-gated services:

• Discover price with blink l402-discover <url> (no payment needed).
• Dry-run with blink l402-pay <url> --dry-run and confirm cost with user.
• Pay with blink l402-pay <url> --max-amount <sats> (Write scope required).
• Token is cached; subsequent requests reuse it without re-paying.

7. Apply safety constraints:

• Use minimum API key scopes for the task.
• Test on staging before production.
• Always check balance before sending.
• Payments are irreversible once settled.

Quick Commands

# Check balances
blink balance

# Create BTC invoice (auto-subscribes to payment)
blink create-invoice 1000 "Payment for service"

# Pay a Lightning invoice
blink pay-invoice lnbc1000n1...

# Pay from USD wallet
blink pay-invoice lnbc1000n1... --wallet USD

# Get current BTC/USD price
blink price

# Swap 1000 sats to USD
blink swap-execute btc-to-usd 1000

# Get swap quote without executing
blink swap-quote usd-to-btc 500 --unit cents

# Probe an L402-gated URL (discover price without paying)
blink l402-discover https://api.example.com/resource

# Pay for an L402-gated resource (dry-run first)
blink l402-pay https://api.example.com/resource --dry-run
blink l402-pay https://api.example.com/resource --max-amount 1000

# List cached L402 tokens
blink l402-store list

Core Commands

Check Wallet Balances

blink balance

Returns JSON with all wallet balances (BTC in sats, USD in cents), wallet IDs, pending incoming amounts, and a pre-computed USD estimate for the BTC wallet. Use btcBalanceUsd for the BTC wallet's USD value — do not calculate it yourself.

Create Lightning Invoice (BTC)

blink create-invoice <amount_sats> [--timeout <seconds>] [--no-subscribe] [memo...]

Generates a BOLT-11 Lightning invoice for the specified amount in satoshis. Returns the paymentRequest string that can be paid by any Lightning wallet. The BTC wallet ID is resolved automatically.

Auto-subscribe: After creating the invoice, the script automatically opens a WebSocket subscription and waits for payment. It outputs two JSON objects to stdout:

1. Immediately — {"event": "invoice_created", ...} with paymentRequest, paymentHash, etc.
2. When resolved — {"event": "subscription_result", "status": "PAID"|"EXPIRED"|"TIMEOUT", ...}

The agent should read the first JSON to share the invoice/QR with the user right away, then wait for the second JSON to confirm payment.

• amount_sats — amount in satoshis (required)
• --timeout <seconds> — subscription timeout (default: 300). Use 0 for no timeout.
• --no-subscribe — skip WebSocket auto-subscribe, just create the invoice and exit
• memo... — optional description attached to the invoice (remaining args joined)

Create Lightning Invoice (USD)

blink create-invoice-usd <amount_cents> [--timeout <seconds>] [--no-subscribe] [memo...]

Creates a Lightning invoice denominated in USD cents. The sender pays in BTC/Lightning, but the received amount is locked to a USD value at the current exchange rate. Credited to the USD wallet. Expires in ~5 minutes due to exchange rate lock.

Auto-subscribe: Same two-phase output as create-invoice — first JSON is the created invoice, second JSON is the payment resolution (PAID/EXPIRED/TIMEOUT).

• amount_cents — amount in USD cents, e.g. 100 = $1.00 (required)
• --timeout <seconds> — subscription timeout (default: 300). Use 0 for no timeout.
• --no-subscribe — skip WebSocket auto-subscribe, just create the invoice and exit
• memo... — optional description attached to the invoice (remaining args joined)

Check Invoice Status

blink check-invoice <payment_hash>

Checks the payment status of a Lightning invoice by its payment hash. Use after creating an invoice to detect when it has been paid. Returns status: PAID, PENDING, or EXPIRED.

• payment_hash — the 64-char hex payment hash from create-invoice output (required)

Pay Lightning Invoice

blink pay-invoice <bolt11_invoice> [--wallet BTC|USD]

Pays a BOLT-11 Lightning invoice from the BTC or USD wallet. Returns payment status: SUCCESS, PENDING, FAILURE, or ALREADY_PAID. The wallet ID is resolved automatically.

• bolt11_invoice — the BOLT-11 payment request string, e.g. lnbc... (required)
• --wallet BTC|USD — wallet to pay from (default: BTC). When USD is selected, the Blink API debits the USD equivalent from the USD wallet.

Requires Write scope on the API key.

AGENT: This command spends funds. Always run balance and fee-probe first, then confirm amount and recipient with the user before executing.

Pay to Lightning Address

blink pay-lnaddress <lightning_address> <amount_sats> [--wallet BTC|USD]

Sends satoshis to a Lightning Address (e.g. user@blink.sv). Returns payment status. The wallet ID is resolved automatically.

• lightning_address — recipient in user@domain format (required)
• amount_sats — amount in satoshis (required)
• --wallet BTC|USD — wallet to pay from (default: BTC). When USD is selected, the amount is still specified in satoshis; the Blink API debits the USD equivalent from the USD wallet automatically.

Requires Write scope on the API key.

AGENT: This command spends funds. Always run balance first, confirm the Lightning Address and amount with the user, then execute.

Pay to LNURL

blink pay-lnurl <lnurl> <amount_sats> [--wallet BTC|USD]

Sends satoshis to a raw LNURL payRequest string. For Lightning Addresses (user@domain), use pay-lnaddress instead.

• lnurl — LNURL string, e.g. lnurl1... (required)
• amount_sats — amount in satoshis (required)
• --wallet BTC|USD — wallet to pay from (default: BTC). When USD is selected, the amount is still specified in satoshis; the Blink API debits the USD equivalent from the USD wallet automatically.

Requires Write scope on the API key.

AGENT: This command spends funds. Always run balance first, confirm the LNURL and amount with the user, then execute.

Estimate Payment Fee

blink fee-probe <bolt11_invoice> [--wallet BTC|USD]

Estimates the fee for paying a Lightning invoice without actually sending. Use before pay-invoice to check costs. Payments to other Blink users and direct-channel nodes are free (0 sats).

• bolt11_invoice — the BOLT-11 payment request string (required)
• --wallet BTC|USD — wallet to probe from (default: BTC). When USD is selected, uses lnUsdInvoiceFeeProbe to estimate fees from the USD wallet's perspective.

Render Invoice QR Code

blink qr <bolt11_invoice>

Renders a terminal QR code for a Lightning invoice (BOLT-11) to stderr and generates a PNG image file to /tmp. The stdout JSON includes a pngPath field with the absolute path to the PNG file.

Sending the QR image to a user: After running this script, use the pngPath from the JSON output to send the PNG as a media attachment to the user in the current chat. The agent should use its native message-send capability with the file path.

• bolt11_invoice — the BOLT-11 payment request string (required)

Output JSON includes:

• invoice — uppercased invoice string
• qrRendered — always true
• qrSize — QR module count
• errorCorrection — "L" (LOW)
• pngPath — absolute path to the generated PNG file (e.g. /tmp/blink_qr_1234567890.png)
• pngBytes — file size in bytes

List Transactions

blink transactions [--first N] [--after CURSOR] [--wallet BTC|USD]

Lists recent transactions (incoming and outgoing) with pagination. Returns direction, amount, status, type (lightning/onchain/intraledger), and metadata.

• --first N — number of transactions to return (default: 20, max: 100)
• --after CURSOR — pagination cursor from previous response's endCursor
• --wallet BTC|USD — filter to a specific wallet currency

Get BTC/USD Price

blink price [amount_sats]
blink price --usd <amount_usd>
blink price --history <range>
blink price --currencies

Multi-purpose exchange rate tool. All price queries are public (no API key required), though the key is sent if available.

Modes:

• No args — current BTC/USD price and sats-per-dollar rate
• <amount_sats> — convert a satoshi amount to USD (e.g. blink price 1760 → $1.20)
• --usd <amount> — convert a USD amount to sats (e.g. blink price --usd 5.00 → 7350 sats)
• --history <range> — historical BTC price data with summary stats (high/low/change). Ranges: ONE_DAY, ONE_WEEK, ONE_MONTH, ONE_YEAR, FIVE_YEARS
• --currencies — list all supported display currencies (IDs, names, symbols, flags)

Account Info

blink account-info

Shows account level, spending limits (withdrawal, internal send, convert), default wallet, and wallet summary with pre-computed USD estimates for BTC balances. Limits are denominated in USD cents with a rolling 24-hour window.

Realtime Subscriptions

Blink supports GraphQL subscriptions over WebSocket using the graphql-transport-ws protocol. Requires Node 22+ for native WebSocket, or Node 20+ with the --experimental-websocket flag.

Subscribe to Invoice Payment Status

blink subscribe-invoice <bolt11_invoice> [--timeout <seconds>]

Watches a single invoice and exits when it is PAID or EXPIRED. Status updates are printed to stderr. JSON result is printed to stdout.

Subscribe to Account Updates (myUpdates)

blink subscribe-updates [--timeout <seconds>] [--max <count>]

Streams account updates in real time. Each event is output as a JSON line (NDJSON) to stdout. Use --max to stop after N events.

API Reference

| Operation | GraphQL | Scope Required | | ------------------ | ------------------------------------------- | ----------------- | | Check balance | query me + currencyConversionEstimation | Read | | Create BTC invoice | mutation lnInvoiceCreate | Receive | | Create USD invoice | mutation lnUsdInvoiceCreate | Receive | | Check invoice | query invoiceByPaymentHash | Read | | Pay invoice | mutation lnInvoicePaymentSend | Write | | Pay LN address | mutation lnAddressPaymentSend | Write | | Pay LNURL | mutation lnurlPaymentSend | Write | | Fee estimate (BTC) | mutation lnInvoiceFeeProbe | Read | | Fee estimate (USD) | mutation lnUsdInvoiceFeeProbe | Read | | Swap BTC→USD | mutation intraLedgerPaymentSend | Write | | Swap USD→BTC | mutation intraLedgerUsdPaymentSend | Write | | Transactions | query transactions | Read | | Price / convert | query currencyConversionEstimation | None (public) | | Price history | query btcPriceList | None (public) | | Currency list | query currencyList | None (public) | | Realtime price | query realtimePrice | None (public) | | Account info | query me + currencyConversionEstimation | Read | | Subscribe invoice | subscription lnInvoicePaymentStatus | Read | | Subscribe updates | subscription myUpdates | Read | | L402 discover | external HTTP (no Blink API) | None | | L402 pay | mutation lnInvoicePaymentSend (on 402) | Write |

API Endpoint: https://api.blink.sv/graphql (production) Authentication: X-API-KEY header

USD wallet notes: The lnInvoicePaymentSend, lnAddressPaymentSend, and lnurlPaymentSend mutations all accept either a BTC or USD wallet ID. When a USD wallet ID is provided, the API debits the USD equivalent automatically. Amounts for lnAddressPaymentSend and lnurlPaymentSend are always specified in satoshis regardless of wallet type.

Output Format

All commands output structured JSON to stdout. Status messages and errors go to stderr. Exit code 0 on success, 1 on failure.

Balance output example

{
  "wallets": [
    { "id": "abc123", "currency": "BTC", "balance": 1760, "unit": "sats" },
    { "id": "def456", "currency": "USD", "balance": 1500, "unit": "cents" }
  ],
  "btcWalletId": "abc123",
  "btcBalance": 1760,
  "btcBalanceSats": 1760,
  "btcBalanceUsd": 1.2,
  "btcBalanceUsdFormatted": "$1.20",
  "usdWalletId": "def456",
  "usdBalance": 1500,
  "usdBalanceCents": 1500,
  "usdBalanceFormatted": "$15.00"
}

Invoice creation output example (two-phase)

First JSON (immediate):

{
  "event": "invoice_created",
  "paymentRequest": "lnbc500n1...",
  "paymentHash": "abc123...",
  "satoshis": 500,
  "status": "PENDING",
  "createdAt": "2026-02-23T00:00:00Z",
  "walletId": "abc123"
}

Second JSON (when payment resolves):

{
  "event": "subscription_result",
  "paymentRequest": "lnbc500n1...",
  "status": "PAID",
  "isPaid": true,
  "isExpired": false,
  "isPending": false
}

Invoice status output example

{
  "paymentHash": "abc123...",
  "paymentStatus": "PAID",
  "satoshis": 500,
  "isPaid": true,
  "isExpired": false,
  "isPending": false
}

Payment output example (BTC wallet)

{
  "status": "SUCCESS",
  "walletId": "abc123",
  "walletCurrency": "BTC",
  "balanceBefore": 50000
}

Payment output example (USD wallet)

{
  "status": "SUCCESS",
  "walletId": "def456",
  "walletCurrency": "USD",
  "balanceBefore": 1500,
  "balanceBeforeFormatted": "$15.00"
}

Price output example

{
  "btcPriceUsd": 68036.95,
  "satsPerDollar": 1470,
  "conversion": {
    "sats": 1760,
    "usd": 1.2,
    "usdFormatted": "$1.20"
  }
}

USD-to-sats conversion output example

{
  "btcPriceUsd": 68036.95,
  "satsPerDollar": 1470,
  "conversion": {
    "usd": 5.0,
    "usdFormatted": "$5.00",
    "sats": 7350
  }
}

Price history output example

{
  "range": "ONE_DAY",
  "dataPoints": 24,
  "summary": {
    "current": 68036.95,
    "oldest": 67500.0,
    "high": 68500.0,
    "low": 67200.0,
    "changeUsd": 536.95,
    "changePct": 0.8
  },
  "prices": [{ "timestamp": 1740000000, "date": "2025-02-20T00:00:00.000Z", "btcPriceUsd": 67500.0 }]
}

Transaction list output example

{
  "transactions": [
    {
      "id": "tx_123",
      "direction": "RECEIVE",
      "status": "SUCCESS",
      "amount": 1000,
      "currency": "BTC",
      "type": "lightning",
      "paymentHash": "abc...",
      "createdAt": 1740000000
    }
  ],
  "count": 1,
  "pageInfo": {
    "hasNextPage": false,
    "endCursor": "cursor_abc"
  }
}

Typical Agent Workflows

Receive a payment (recommended — auto-subscribe + QR image)

# 1. Create invoice — script auto-subscribes and outputs two JSON objects
blink create-invoice 1000 "Payment for service"
# → First JSON: {"event": "invoice_created", "paymentRequest": "lnbc...", ...}

<!-- Content truncated for initial SEO render. Open the source file tab for the full file. -->