Blink Skill

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. 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:

CODEBLOCK0

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

CODEBLOCK1

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:

CODEBLOCK2

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. 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:

CODEBLOCK3

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. 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. 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).

1. 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.

1. 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.

1. 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.

1. 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.

1. 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.

1. 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

CODEBLOCK4

Core Commands

Check Wallet Balances

CODEBLOCK5

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)

CODEBLOCK6

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. 1. Immediately — {"event": "invoice_created", ...} with paymentRequest, paymentHash, etc.
2. When resolved — INLINECODE64

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)
• INLINECODE66 — subscription timeout (default: 300). Use 0 for no timeout.
• INLINECODE67 — skip WebSocket auto-subscribe, just create the invoice and exit
• INLINECODE68 — optional description attached to the invoice (remaining args joined)

Create Lightning Invoice (USD)

CODEBLOCK7

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)
• INLINECODE71 — subscription timeout (default: 300). Use 0 for no timeout.
• INLINECODE72 — skip WebSocket auto-subscribe, just create the invoice and exit
• INLINECODE73 — optional description attached to the invoice (remaining args joined)

Check Invoice Status

CODEBLOCK8

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

CODEBLOCK9

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)
• INLINECODE85 — 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

CODEBLOCK10

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)
• INLINECODE91 — amount in satoshis (required)
• INLINECODE92 — 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

CODEBLOCK11

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

• - lnurl — LNURL string, e.g. lnurl1... (required)
• INLINECODE98 — amount in satoshis (required)
• INLINECODE99 — 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

CODEBLOCK12

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)
• INLINECODE103 — 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

CODEBLOCK13

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
• INLINECODE110 — always INLINECODE111
• INLINECODE112 — QR module count
• INLINECODE113 — "L" (LOW)
• INLINECODE115 — absolute path to the generated PNG file (e.g. /tmp/blink_qr_1234567890.png)
• INLINECODE117 — file size in bytes

List Transactions

CODEBLOCK14

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)
• INLINECODE119 — pagination cursor from previous response's INLINECODE120
• INLINECODE121 — filter to a specific wallet currency

Get BTC/USD Price

CODEBLOCK15

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, INLINECODE133
• --currencies — list all supported display currencies (IDs, names, symbols, flags)

Account Info

CODEBLOCK16

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

CODEBLOCK17

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)

CODEBLOCK18

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	INLINECODE138 + INLINECODE139	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

CODEBLOCK19

Invoice creation output example (two-phase)

First JSON (immediate):

CODEBLOCK20

Second JSON (when payment resolves):

CODEBLOCK21

Invoice status output example

CODEBLOCK22

Payment output example (BTC wallet)

CODEBLOCK23

Payment output example (USD wallet)

CODEBLOCK24

Price output example

CODEBLOCK25

USD-to-sats conversion output example

CODEBLOCK26

Price history output example

CODEBLOCK27

Transaction list output example

CODEBLOCK28

Typical Agent Workflows

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

CODEBLOCK29

Important: The create-invoice command outputs two JSON objects separated by a newline. Parse them as separate JSON objects, not as a single JSON array. The first object arrives immediately; the second arrives when payment status resolves.

Receive a payment (polling fallback)

CODEBLOCK30

Receive a USD payment

CODEBLOCK31

Send a payment (with fee check)

CODEBLOCK32

Send from the USD wallet

CODEBLOCK33

Convert sats to USD value

CODEBLOCK34

Convert USD to sats

CODEBLOCK35

Swap BTC to USD (internal conversion)

CODEBLOCK36

Swap USD to BTC (internal conversion)

CODEBLOCK37

Pay for an L402-gated service

CODEBLOCK38

Check price history

CODEBLOCK39

Swap Commands (BTC <-> USD)

Swap between your BTC and USD wallets using Blink's intra-ledger transfer. This is an internal conversion (not a Lightning payment), so there are no routing fees — only minor rounding spread.

Get Swap Quote

CODEBLOCK40

Estimates the conversion terms without moving funds. Returns wallet balances, exchange rate snapshot, and the expected amountIn/amountOut in the output JSON.

• - direction — btc-to-usd or usd-to-btc (aliases: sell-btc, buy-usd, sell-usd, buy-btc)
• INLINECODE177 — positive integer amount to convert
• INLINECODE178 — unit of the amount (defaults to sats for btc-to-usd, cents for usd-to-btc)
• INLINECODE181 — quote TTL in seconds (default: 60)
• INLINECODE182 — flag the quote for immediate execution

No API key scope beyond Read is required for quotes.

Execute Swap

CODEBLOCK41

Executes a real BTC <-> USD conversion. First generates a quote, then performs the intra-ledger transfer. Returns pre/post balances, delta, quote terms, and transaction ID.

• - direction — same as swap-quote
• INLINECODE184 — positive integer amount to convert
• INLINECODE185 — same as swap-quote
• INLINECODE186 — show what would be swapped without executing the transfer
• INLINECODE187 — optional memo attached to the transaction

CAUTION: Without --dry-run, this moves real funds between wallets. Requires Write scope.

AGENT: This command moves funds between wallets. Always run with --dry-run first, show the quote to the user, and get explicit confirmation before executing without --dry-run.

Swap Output Examples

Quote output:

CODEBLOCK42

Execution output:

CODEBLOCK43

L402 Client Commands

L402 is an HTTP payment protocol: a server returns HTTP 402 with a Lightning invoice, the client pays, and retries the request with a proof-of-payment token. This skill can act as an L402 client.

Supports two L402 formats:

• - Lightning Labs — INLINECODE191
• l402-protocol.org — JSON body with payment_request_url and offers array

Discover L402 Pricing (no payment)

CODEBLOCK44

Probes a URL for L402 payment requirements without paying. Returns the detected format, invoice, and decoded satoshi amount.

• - url — the URL to probe (required)
• INLINECODE195 — HTTP method to use (default: GET)
• INLINECODE196 — extra request header (repeatable)

No API key required for discovery.

Known public L402 endpoints for testing (use specific paths, not root URLs):

• - https://l402.services/geoip/8.8.8.8 — GeoIP lookup, 1 sat, Lightning Labs format
• INLINECODE198 — L402 API directory, 10 sats, Lightning Labs format

Pay for an L402-Gated Resource

CODEBLOCK45

Makes an HTTP request. If the server returns 402, automatically parses the challenge, pays the invoice via Blink, caches the token, and retries with the payment proof.

• - url — URL to access (required)
• INLINECODE200 — wallet to pay from (default: BTC)
• INLINECODE201 — refuse to pay more than N sats (safety limit)
• INLINECODE202 — discover price without paying; always bypasses the token cache so the current invoice price is always shown even if a cached token exists
• INLINECODE203 — HTTP method (default: GET)
• INLINECODE204 — extra request header (repeatable)
• INLINECODE205 — request body for POST/PUT
• INLINECODE206 — disable token cache (do not read or write ~/.blink/l402-tokens.json)
• INLINECODE208 — pay even if a valid cached token exists
• INLINECODE209 — run a fee probe (lnInvoiceFeeProbe) before paying to estimate routing fees; warns and continues if the probe fails; adds a feeProbe field to the l402_paid output

Requires Write scope on the API key.

AGENT: Always run with --dry-run first to show the satoshi cost to the user. Confirm the amount and target URL before executing without --dry-run.

Manage Token Cache

CODEBLOCK46

• - list — show all cached tokens (masks preimage for security)
• INLINECODE216 — retrieve the full token for a specific domain
• INLINECODE217 — remove all cached tokens
• INLINECODE218 — remove only expired tokens

Token cache location: INLINECODE219

L402 Output Examples

l402-discover (Lightning Labs format):

CODEBLOCK47

l402-pay (dry-run):

CODEBLOCK48

l402-pay (after payment):

CODEBLOCK49

l402-pay (after payment, with --probe):

CODEBLOCK50

L402 Producer Commands

L402 producer tools let you protect your own API resources behind a Lightning paywall. Issue challenges to clients, then verify their payment proofs before granting access.

Two-step workflow:

1. 1. When a client requests a resource, call blink l402-challenge to create a signed payment challenge and return it with HTTP 402.
2. When the client submits a payment token, call blink l402-verify to verify the preimage and macaroon signature.

Note: End-to-end round-trip testing (challenge → pay → verify) requires two separate Blink accounts. Blink does not allow paying your own invoice (CANTPAYSELF). Use a second account or wallet to pay the challenge invoice during testing.

Create an L402 Challenge

CODEBLOCK51

Creates a Lightning invoice via Blink and issues a signed macaroon bound to its payment hash. Returns a ready-to-send WWW-Authenticate header.

• - --amount <sats> — invoice amount in satoshis (required)
• INLINECODE224 — Blink BTC wallet ID (auto-resolved if omitted)
• INLINECODE225 — invoice memo / description
• INLINECODE226 — macaroon caveat expiry (e.g. 3600 = 1 hour); controls how long the challenge is valid, not the invoice expiry
• INLINECODE228 — resource identifier caveat (e.g. /api/v1/data); returned tokens will only be valid for this exact path

Requires Write scope on the API key.

Root key for HMAC signing resolves in this order:

1. 1. BLINK_L402_ROOT_KEY env var (64-char hex, 32 bytes)
2. INLINECODE231 (auto-created on first run)

AGENT: Keep BLINK_L402_ROOT_KEY or ~/.blink/l402-root-key stable across server restarts. A different root key will invalidate all previously issued macaroons.

Verify an L402 Payment Token

CODEBLOCK52

Verifies a client-submitted L402 Authorization token. Performs three layers of verification:

1. 1. Preimage check: SHA-256(preimage) === payment_hash — cryptographic proof the invoice was paid
2. Signature check: HMAC-SHA256 of macaroon body — proves the macaroon was issued by this server
3. Caveat check: expiry not exceeded, resource matches if constrained

• - --token <macaroon>:<preimage> — L402 authorization token (colon-separated, from Authorization: L402 <token> header)
• INLINECODE238 — base64url-encoded macaroon (alternative to --token)
• INLINECODE240 — 64-char hex preimage (alternative to --token)
• INLINECODE242 — expected resource identifier to check against the macaroon's resource caveat
• INLINECODE243 — additionally query the Blink API to confirm PAID status (belt-and-suspenders)

Exit code 0 when valid: true, exit code 1 when valid: false or on error.

Note: The --preimage value must be a 64-character hex string (32 bytes). Passing a plain string like fake_preimage will produce an error explaining the format requirement. For testing rejection, use a valid-format but wrong preimage: 64 zeros (0000...0000).

L402 Producer Output Examples

l402-challenge:

CODEBLOCK53

Return this to clients as:

CODEBLOCK54

l402-verify (valid payment):

CODEBLOCK55

l402-verify (invalid — wrong preimage):

CODEBLOCK56

L402 Service Discovery

Find L402-gated APIs that agents can pay for and access. Two directory sources:

• - l402.directory (default) — curated registry with rich endpoint schemas, pricing, and consumption instructions
• 402index.io — broader coverage (50+ services), simpler flat schema

Search Services

CODEBLOCK57

No API key required — both directories have free browse APIs.

AGENT: Use l402-search to find services before using l402-pay. Check pricing in the results before paying.

Get Service Details

CODEBLOCK58

• - Without --report: free, returns endpoints, pricing, consumption instructions
• With --report: 10 sats, returns uptime percentages, probe history, response times
• INLINECODE255 is subject to budget controls and domain allowlist (domain: l402.directory)

Discovery Output Example

CODEBLOCK59

Budget Controls

Prevent runaway spending in autonomous agent workflows with rolling spend limits and domain allowlist.

Configuration

Env vars take precedence over the config file (~/.blink/budget.json):

Env var	Config file key	Default	Description
INLINECODE258	INLINECODE259	none (unlimited)	Max sats in rolling 1-hour window
INLINECODE260

dailyLimitSats | none (unlimited) | Max sats in rolling 24-hour window |
| BLINK_L402_ALLOWED_DOMAINS | allowlist | none (all allowed) | Comma-separated domains for L402 auto-pay |

If no env vars and no config file exist, no limits are enforced (fully backward compatible).

Budget Commands

CODEBLOCK60

Budget Status Output Example

CODEBLOCK61

INLINECODE264 = min(hourlyRemaining, dailyRemaining) — the actual amount the agent can spend right now.

How Budget Enforcement Works

• - Checked before every outbound payment: pay-invoice, pay-lnaddress, pay-lnurl, INLINECODE268
• Domain allowlist: checked for l402-pay only — blocks auto-pay to unlisted domains
• --force bypasses budget: existing --force flag on payment commands skips budget check
• --dry-run shows budget impact: dry-run output includes a budget field showing remaining budget
• Spending recorded after success: only successful/pending payments are logged
• Auto-pruning: log entries older than 25 hours are removed automatically

AGENT: Before making a payment, check budget status with blink budget status to see remaining budget. If budget is exceeded, inform the user and suggest increasing limits with blink budget set.

Security

API Key Handling

• - Your API key is your wallet access — anyone with a Write-scoped key can spend your entire balance.
• Use minimum scopes — Read-only for balance checks, Receive for invoices, Write only when sending.
• Never expose keys in output — do not echo, log, or include BLINK_API_KEY in chat messages or files.
• Keys are for server-side / agent use only. Never embed in client-side code.

What Data Leaves the Machine

• - Outbound HTTPS to api.blink.sv (or BLINK_API_URL override) for all GraphQL queries and mutations.
• Outbound WSS to ws.blink.sv (or BLINK_WS_URL override) for subscription WebSockets.
• L402 requests go directly to the third-party URL you provide to l402-discover or l402-pay. The Blink API is contacted only when a payment is needed.
• No other network calls. Scripts do not phone home, send telemetry, or contact any undisclosed third-party services.

Filesystem Access

• - RC file reading: If BLINK_API_KEY is not found in process.env, the client scans ~/.profile, ~/.bashrc, ~/.bash_profile, and ~/.zshrc for a line matching export BLINK_API_KEY=.... Only the value of that specific export is extracted — no other data is read from these files. The environment variable is always checked first.
• QR PNG generation: The qr command writes temporary PNG files to /tmp/blink_qr_*.png. These are standard image files with no embedded metadata beyond the QR content.
• L402 token cache: The l402-pay command writes paid tokens to ~/.blink/l402-tokens.json. This file contains macaroons and preimages for previously-paid L402 services. Use blink l402-store clear to remove all cached tokens. Pass --no-store to disable caching entirely.
• Budget files: Budget config at ~/.blink/budget.json and spending log at ~/.blink/spending-log.json. The spending log is auto-pruned (entries older than 25h removed). Use blink budget reset to clear the log.

Stateless Design

Most scripts are stateless. Exceptions:

• - l402-pay maintains a token cache at ~/.blink/l402-tokens.json to avoid re-paying for previously-accessed L402 services. Use --no-store to run without any persistence.
• All payment commands (pay-invoice, pay-lnaddress, pay-lnurl, l402-pay) log spending to ~/.blink/spending-log.json for budget enforcement. This log is auto-pruned and can be cleared with blink budget reset.

Payment Safety

• - Sending is irreversible — Lightning payments cannot be reversed once settled.
• Test on staging first — use BLINK_API_URL=https://api.staging.blink.sv/graphql to point at the signet staging environment with test funds.
• USD invoices expire fast — ~5 minutes due to exchange rate lock.
• Price queries are public — blink price works without an API key; only wallet operations require authentication.
• L402 preimage resolution — After payment, l402-pay retrieves the preimage inline from the mutation response (settlementVia.preImage). If the inline preimage is unavailable (e.g. race condition or network issue), it falls back to a transactions query matched by payment hash. If the transaction is not yet indexed, it falls back to a SHA-256(invoice) placeholder, which works with servers using token-based verification but may fail with servers that cryptographically verify the preimage against the payment hash.

Reference Files

• - blink-api-and-auth: API endpoints, authentication, scopes, staging/testnet configuration, and error handling.
• payment-operations: send workflows, BTC vs USD wallet selection, fee probing, and safety guardrails.
• invoice-lifecycle: invoice creation, two-phase output parsing, monitoring strategies, QR generation, and expiration handling.
• swap-operations: BTC <-> USD internal conversion, quote/execute workflow, rounding behavior, and effective cost formulas.
• 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 (endpoints, source URLs, hard rules).

Files

• - {baseDir}/scripts/balance.js — Check wallet balances
• INLINECODE314 — Create BTC Lightning invoices (auto-subscribes to payment status)
• INLINECODE315 — Create USD-denominated Lightning invoices (auto-subscribes to payment status)
• INLINECODE316 — Check invoice payment status (polling)
• INLINECODE317 — Pay BOLT-11 invoices (BTC or USD wallet)
• INLINECODE318 — Pay to Lightning Addresses (BTC or USD wallet)
• INLINECODE319 — Pay to LNURL strings (BTC or USD wallet)
• INLINECODE320 — Estimate payment fees (BTC or USD wallet)
• INLINECODE321 — Render invoice QR code (terminal + PNG file)
• INLINECODE322 — List transaction history
• INLINECODE323 — Get BTC/USD exchange rate
• INLINECODE324 — Show account info and limits
• INLINECODE325 — Subscribe to invoice payment status (standalone)
• INLINECODE326 — Subscribe to realtime account updates
• INLINECODE327 — Shared swap helpers (quote estimation, execution, wallet pair management)
• INLINECODE328 — Get BTC <-> USD conversion quote
• INLINECODE329 — Execute BTC <-> USD wallet conversion
• INLINECODE330 — Probe a URL for L402 payment requirements (no payment)
• INLINECODE331 — Auto-pay L402-gated resources via Blink + token caching
• INLINECODE332 — Manage the L402 token cache (~/.blink/l402-tokens.json)
• INLINECODE333 — Shared macaroon module: encode/decode/sign/verify + root key management
• INLINECODE334 — Create L402 payment challenges (invoice + signed macaroon)
• INLINECODE335 — Verify L402 client payment tokens (preimage + HMAC + caveats)
• INLINECODE336 — Search L402 service directories (l402.directory, 402index.io)
• INLINECODE337 — Get full L402 service details + paid health reports
• INLINECODE338 — Shared budget module: config resolution, spend log, rolling limits, domain allowlist
• INLINECODE339 — Budget controls CLI (status, set, log, reset, allowlist)