blink

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Blink Skill

Bitcoin Lightning wallet operations via the Blink API. Enables agents to check balances, receive payments via invoices, send payments over Lightning, swap between BTC and USD wallets, track transactions, and monitor prices.

通过Blink API实现Bitcoin Lightning钱包操作，支持Agent查询余额、通过发票接收付款、通过Lightning网络发送付款、在BTC与USD钱包间兑换、跟踪交易及监控价格。

What is Blink?

什么是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

Blink是一款托管式Bitcoin Lightning钱包，提供GraphQL API。核心概念：

API Key — 认证令牌（格式：
```
blink_...
```
），带有权限范围（Read、Receive、Write）
BTC钱包 — 余额以聪（satoshis）为单位
USD钱包 — 余额以美分为单位（与美元挂钩的稳定币）
Lightning发票 — BOLT-11付款请求字符串（格式：
```
lnbc...
```
），用于接收付款
Lightning地址 — 人类可读地址（格式：
```
user@domain
```
），无需发票即可发送付款
LNURL — 通过编码URL与Lightning服务交互的协议

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.

需要
```
bash
```
和Node.js 18或更高版本。
需要配置带有相应权限范围的
```
BLINK_API_KEY
```
环境变量。
对于WebSocket订阅：需使用Node 22+（原生支持）或Node 20+并添加
```
--experimental-websocket
```
参数。
无运行时npm依赖，仅使用Node.js内置模块（
```
node:util
```
、
```
node:fs
```
、
```
node:path
```
、
```
node:child_process
```
）。

本Skill用于具体钱包操作，而非通用Lightning网络理论讲解。

Getting Started

快速开始

1. Get your API key

1. 获取API密钥

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

bash

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.

在dashboard.blink.sv创建免费账户。
进入API Keys页面，创建带有所需权限范围的密钥。
在环境中配置该密钥：

bash

export BLINK_API_KEY="blink_..."

API密钥权限范围：

Read（只读） — 查询余额、交易历史、价格及账户信息
Receive（收款） — 创建发票
Write（付款） — 发送付款（请谨慎使用）

提示： 建议仅先启用Read+Receive权限，当需要发送付款时再添加Write权限。

2. Verify it works

2. 验证功能可用

bash

node {baseDir}/scripts/balance.js

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

bash

node {baseDir}/scripts/balance.js

如果看到包含钱包余额的JSON输出，说明配置完成。

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

3. 测试环境/测试网（首次设置推荐使用）

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

bash

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.

BLINK_API_URL

is not set, production (

https://api.blink.sv/graphql

) is used by default.

若要使用Blink测试环境（signet网络）而非真实资金，请执行：

bash

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

在dashboard.staging.blink.sv创建测试环境API密钥。测试环境使用signet比特币（无实际价值），非常适合安全测试付款流程。

若未设置

BLINK_API_URL

，默认使用生产环境（

https://api.blink.sv/graphql

）。

API key auto-detection

API密钥自动检测

Scripts automatically resolve

BLINK_API_KEY

using this order:

```
process.env.BLINK_API_KEY
```
(checked first)

Shell rc files:

~/.profile

~/.bashrc

~/.bash_profile

~/.zshrc

— scanned for an

export BLINK_API_KEY=...

line only

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.

脚本会按以下顺序自动解析

BLINK_API_KEY

：

```
process.env.BLINK_API_KEY
```
（优先检查）

Shell配置文件：

~/.profile

、

~/.bashrc

、

~/.bash_profile

、

~/.zshrc

— 仅扫描包含

export BLINK_API_KEY=...

的行

无需添加

source ~/.profile

前缀。配置文件扫描使用针对性正则表达式，仅提取

BLINK_API_KEY

的导出行，不会读取这些文件中的其他数据。

Agent Safety Policy

Agent安全策略

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

Ask before spending. Never execute
```
pay_invoice.js
```
,
```
pay_lnaddress.js
```
,
```
pay_lnurl.js
```
, or
```
swap_execute.js
```
without explicit user confirmation of the amount and recipient.
Dry-run first. For swaps, always run with
```
--dry-run
```
before executing for real unless the user explicitly says to skip it.
Check balance before sending. Always run
```
balance.js
```
before any payment or swap to verify sufficient funds.
Probe fees before paying. Run
```
fee_probe.js
```
before
```
pay_invoice.js
```
to show the user the fee cost.
Use minimum scopes. Only request Write-scoped API keys when send operations are actually needed.
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.
Prefer staging for testing. When the user is testing or learning, suggest setting
```
BLINK_API_URL
```
to the staging endpoint.
Respect irreversibility. Warn the user that Lightning payments and swaps cannot be reversed once executed.

任何使用该Skill的AI Agent都必须遵守以下规则：

付款前确认：在未获得用户对金额和收款方的明确确认前，绝不能执行
```
pay_invoice.js
```
、
```
pay_lnaddress.js
```
、
```
pay_lnurl.js
```
或
```
swap_execute.js
```
。
先执行试运行：对于兑换操作，除非用户明确要求跳过，否则必须先使用
```
--dry-run
```
参数试运行，再执行真实操作。
付款前查余额：在执行任何付款或兑换操作前，必须先运行
```
balance.js
```
验证资金是否充足。
付款前查手续费：在执行
```
pay_invoice.js
```
前，必须运行
```
fee_probe.js
```
向用户展示手续费成本。
最小权限原则：仅当确实需要执行付款操作时，才申请带有Write权限的API密钥。
绝不泄露API密钥：将
```
BLINK_API_KEY
```
视为机密信息，不要回显、包含在消息中或写入文件。
测试优先使用测试环境：当用户进行测试或学习时，建议将
```
BLINK_API_URL
```
设置为测试环境端点。
告知不可逆性：提醒用户Lightning付款和兑换操作一旦完成，无法撤销。

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
```
node {baseDir}/scripts/price.js <sats>
```
or the
```
btcBalanceUsd
```
field from
```
balance
```
output instead.
For swap amounts, the
```
--unit
```
flag controls interpretation:
```
sats
```
for BTC,
```
cents
```
for USD.

BTC钱包的金额始终以**聪（satoshis，简称sats）**为单位。1 BTC = 100,000,000 聪。
USD钱包的金额始终以美分为单位。$1.00 = 100 美分。
向用户展示金额时，请使用输出JSON中的格式化字段（如
```
btcBalanceUsdFormatted
```
、
```
usdBalanceFormatted
```
）。
不要手动进行BTC与USD的转换计算，请使用
```
node {baseDir}/scripts/price.js <sats>
```
或
```
balance
```
输出中的
```
btcBalanceUsd
```
字段。
对于兑换金额，
```
--unit
```
参数控制单位解读：
```
sats
```
代表BTC，
```
cents
```
代表USD。

Workflow

工作流程

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

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
```
balance.js
```
.

For sending payments, follow payment-operations:

Check balance before sending.
Probe fees with
```
fee_probe.js
```
.
Choose BTC or USD wallet with
```
--wallet
```
flag.
Use
```
--dry-run
```
to preview without sending. Use
```
--max-amount
```
to cap outgoing amounts.
Execute payment and verify in transaction history.

For swapping between wallets, follow swap-operations:

Get a quote with
```
swap_quote.js
```
to preview the conversion.
Execute with
```
swap_execute.js
```
(use
```
--dry-run
```
first).

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.

Apply safety constraints:

Use minimum API key scopes for the task.
Test on staging before production.
Always check balance before sending.
Use
```
--dry-run
```
on payment and swap commands to preview before executing.
Use
```
--max-amount <sats>
```
to enforce a per-payment ceiling (pay_lnaddress, pay_lnurl).
Use
```
--force
```
to override balance-check failures when you know the payment should proceed.
Payments are irreversible once settled.

首先选择操作路径：

接收付款（创建发票、生成二维码、监控付款状态）
发送付款（支付发票、Lightning地址、LNURL、BTC或USD钱包）
钱包间兑换（BTC与USD内部转换）
只读查询（余额、交易、价格、账户信息）

参考blink-api-and-auth配置API访问：

设置带有对应操作权限的
```
BLINK_API_KEY
```
可选：设置
```
BLINK_API_URL
```
以使用测试环境
通过
```
balance.js
```
验证连通性

发送付款请参考payment-operations：

付款前查询余额
使用
```
fee_probe.js
```
查询手续费
使用
```
--wallet
```
参数选择BTC或USD钱包
使用
```
--dry-run
```
参数预览付款（不实际发送），使用
```
--max-amount
```
参数设置付款上限
执行付款并在交易历史中验证

钱包间兑换请参考swap-operations：

使用
```
swap_quote.js
```
获取兑换报价以预览转换结果
使用
```
swap_execute.js
```
执行兑换（先使用
```
--dry-run
```
试运行）

接收付款请参考invoice-lifecycle：

创建BTC或USD发票
解析两阶段输出（发票创建完成、付款状态确认）
生成二维码并发送给付款方
通过自动订阅、轮询或独立订阅监控付款状态

应用安全约束：

为任务使用最小权限的API密钥
先在测试环境测试，再使用生产环境
付款前务必查询余额
付款和兑换命令先使用
```
--dry-run
```
参数预览，再执行真实操作
使用
```
--max-amount <sats>
```
参数设置单笔付款上限（适用于pay_lnaddress、pay_lnurl）
当确认付款应执行时，使用
```
--force
```
参数覆盖余额检查失败的限制
付款一旦完成，无法撤销

Quick Commands

快速命令

bash

undefined

bash

undefined

Check balances

查询余额

node {baseDir}/scripts/balance.js

Create BTC invoice (auto-subscribes to payment)

创建BTC发票（自动订阅付款状态）

node {baseDir}/scripts/create_invoice.js 1000 "Payment for service"

node {baseDir}/scripts/create_invoice.js 1000 "服务付款"

Pay a Lightning invoice

支付Lightning发票

node {baseDir}/scripts/pay_invoice.js lnbc1000n1...

Pay from USD wallet

从USD钱包支付

node {baseDir}/scripts/pay_invoice.js lnbc1000n1... --wallet USD

Get current BTC/USD price

获取当前BTC/USD价格

node {baseDir}/scripts/price.js

Quote BTC -> USD internal swap (dry-run)

获取BTC转USD内部兑换报价（试运行）

node {baseDir}/scripts/swap_quote.js btc-to-usd 5000

Execute USD -> BTC internal swap

执行USD转BTC内部兑换

node {baseDir}/scripts/swap_execute.js usd-to-btc 500 --unit cents

undefined

node {baseDir}/scripts/swap_execute.js usd-to-btc 500 --unit cents

undefined

Core Commands

核心命令

Check Wallet Balances

查询钱包余额

bash

node {baseDir}/scripts/balance.js

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.

bash

node {baseDir}/scripts/balance.js

返回包含所有钱包余额（BTC以聪为单位，USD以美分为单位）、钱包ID、待入账金额以及BTC钱包预计算USD估值的JSON数据。请使用

btcBalanceUsd

字段获取BTC钱包的USD价值，不要自行计算。

Create Lightning Invoice (BTC)

创建Lightning BTC发票

bash

node {baseDir}/scripts/create_invoice.js <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:

Immediately —

{"event": "invoice_created", ...}

with

paymentRequest

paymentHash

, etc.

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)

bash

node {baseDir}/scripts/create_invoice.js <amount_sats> [--timeout <seconds>] [--no-subscribe] [memo...]

生成指定聪数的BOLT-11 Lightning发票，返回可被任何Lightning钱包支付的

paymentRequest

字符串。BTC钱包ID会自动解析。

自动订阅：创建发票后，脚本会自动打开WebSocket订阅并等待付款，向标准输出输出两个JSON对象：

立即输出 —

{"event": "invoice_created", ...}

，包含

paymentRequest

、

paymentHash

等信息

状态确认时输出 —

{"event": "subscription_result", "status": "PAID"|"EXPIRED"|"TIMEOUT", ...}

Agent应立即读取第一个JSON并向用户分享发票/二维码，然后等待第二个JSON以确认付款状态。

```
amount_sats
```
— 聪数金额（必填）
```
--timeout <seconds>
```
— 订阅超时时间（默认：300秒），设置为0表示无超时
```
--no-subscribe
```
— 跳过WebSocket自动订阅，仅创建发票后退出
```
memo...
```
— 发票附加的可选描述（剩余参数将被拼接）

Create Lightning Invoice (USD)

创建Lightning USD发票

bash

node {baseDir}/scripts/create_invoice_usd.js <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.js

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

bash

node {baseDir}/scripts/create_invoice_usd.js <amount_cents> [--timeout <seconds>] [--no-subscribe] [memo...]

创建以USD美分为单位的Lightning发票。付款方使用BTC/Lightning网络付款，但收款金额会锁定为当前汇率下的USD价值，并计入USD钱包。由于汇率锁定，发票约5分钟后过期。

自动订阅：与

create_invoice.js

的两阶段输出相同——第一个JSON为创建完成的发票，第二个JSON为付款状态确认（PAID/EXPIRED/TIMEOUT）。

```
amount_cents
```
— USD美分金额，例如100 = $1.00（必填）
```
--timeout <seconds>
```
— 订阅超时时间（默认：300秒），设置为0表示无超时
```
--no-subscribe
```
— 跳过WebSocket自动订阅，仅创建发票后退出
```
memo...
```
— 发票附加的可选描述（剩余参数将被拼接）

Check Invoice Status

检查发票状态

bash

node {baseDir}/scripts/check_invoice.js <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.js
```
output (required)

bash

node {baseDir}/scripts/check_invoice.js <payment_hash>

通过付款哈希检查Lightning发票的付款状态，可在创建发票后用于检测是否已付款。返回状态：

PAID

、

PENDING

或

EXPIRED

。

```
payment_hash
```
— 来自
```
create_invoice.js
```
输出的64位十六进制付款哈希（必填）

Pay Lightning Invoice

支付Lightning发票

bash

node {baseDir}/scripts/pay_invoice.js <bolt11_invoice> [--wallet BTC|USD] [--dry-run] [--force]

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.
```
--dry-run
```
— preview the payment without sending (returns wallet info and invoice details)
```
--force
```
— attempt payment even when the wallet balance appears insufficient

Requires Write scope on the API key.

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

bash

node {baseDir}/scripts/pay_invoice.js <bolt11_invoice> [--wallet BTC|USD] [--dry-run] [--force]

从BTC或USD钱包支付BOLT-11 Lightning发票，返回付款状态：

SUCCESS

、

PENDING

、

FAILURE

或

ALREADY_PAID

。钱包ID会自动解析。

```
bolt11_invoice
```
— BOLT-11付款请求字符串，例如
```
lnbc...
```
（必填）
```
--wallet BTC|USD
```
— 付款钱包（默认：BTC）。选择USD时，Blink API会从USD钱包扣除等值USD金额。
```
--dry-run
```
— 预览付款（不实际发送），返回钱包信息和发票详情
```
--force
```
— 即使钱包余额显示不足，仍尝试付款

API密钥需要Write权限。

AGENT提示： 该命令会消耗资金。执行前务必先运行
balance.js
和
fee_probe.js
，然后与用户确认金额和收款方。

Pay to Lightning Address

向Lightning地址付款

bash

node {baseDir}/scripts/pay_lnaddress.js <lightning_address> <amount_sats> [--wallet BTC|USD] [--dry-run] [--force] [--max-amount <sats>]

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.
```
--dry-run
```
— preview the payment without sending (returns wallet info and amount details)
```
--force
```
— attempt payment even when the wallet balance appears insufficient
```
--max-amount <sats>
```
— reject the payment if the amount exceeds this ceiling (in satoshis)

Requires Write scope on the API key.

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

bash

node {baseDir}/scripts/pay_lnaddress.js <lightning_address> <amount_sats> [--wallet BTC|USD] [--dry-run] [--force] [--max-amount <sats>]

向Lightning地址（例如

user@blink.sv

）发送聪数，返回付款状态。钱包ID会自动解析。

```
lightning_address
```
— 收款方地址，格式为
```
user@domain
```
（必填）
```
amount_sats
```
— 聪数金额（必填）
```
--wallet BTC|USD
```
— 付款钱包（默认：BTC）。选择USD时，金额仍以聪为单位指定，Blink API会自动从USD钱包扣除等值USD金额。
```
--dry-run
```
— 预览付款（不实际发送），返回钱包信息和金额详情
```
--force
```
— 即使钱包余额显示不足，仍尝试付款
```
--max-amount <sats>
```
— 如果金额超过该上限，拒绝付款（单位：聪）

API密钥需要Write权限。

AGENT提示： 该命令会消耗资金。执行前务必先运行
balance.js
，与用户确认Lightning地址和金额后再执行。

Pay to LNURL

向LNURL付款

bash

node {baseDir}/scripts/pay_lnurl.js <lnurl> <amount_sats> [--wallet BTC|USD] [--dry-run] [--force] [--max-amount <sats>]

Sends satoshis to a raw LNURL payRequest string. For Lightning Addresses (

user@domain

), use

pay_lnaddress.js

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.
```
--dry-run
```
— preview the payment without sending (returns wallet info and amount details)
```
--force
```
— attempt payment even when the wallet balance appears insufficient
```
--max-amount <sats>
```
— reject the payment if the amount exceeds this ceiling (in satoshis)

Requires Write scope on the API key.

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

bash

node {baseDir}/scripts/pay_lnurl.js <lnurl> <amount_sats> [--wallet BTC|USD] [--dry-run] [--force] [--max-amount <sats>]

向原始LNURL付款请求字符串发送聪数。对于Lightning地址（

user@domain

），请使用

pay_lnaddress.js

。

```
lnurl
```
— LNURL字符串，例如
```
lnurl1...
```
（必填）
```
amount_sats
```
— 聪数金额（必填）
```
--wallet BTC|USD
```
— 付款钱包（默认：BTC）。选择USD时，金额仍以聪为单位指定，Blink API会自动从USD钱包扣除等值USD金额。
```
--dry-run
```
— 预览付款（不实际发送），返回钱包信息和金额详情
```
--force
```
— 即使钱包余额显示不足，仍尝试付款
```
--max-amount <sats>
```
— 如果金额超过该上限，拒绝付款（单位：聪）

API密钥需要Write权限。

AGENT提示： 该命令会消耗资金。执行前务必先运行
balance.js
，与用户确认LNURL和金额后再执行。

Estimate Payment Fee

估算付款手续费

bash

node {baseDir}/scripts/fee_probe.js <bolt11_invoice> [--wallet BTC|USD]

Estimates the fee for paying a Lightning invoice without actually sending. Use before

pay_invoice.js

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.

bash

node {baseDir}/scripts/fee_probe.js <bolt11_invoice> [--wallet BTC|USD]

估算支付Lightning发票的手续费，无需实际发送付款。请在

pay_invoice.js

前使用该命令检查成本。向其他Blink用户和直接通道节点付款免手续费（0聪）。

```
bolt11_invoice
```
— BOLT-11付款请求字符串（必填）
```
--wallet BTC|USD
```
— 估算手续费的钱包（默认：BTC）。选择USD时，使用
```
lnUsdInvoiceFeeProbe
```
从USD钱包视角估算手续费。

Render Invoice QR Code

生成发票二维码

bash

node {baseDir}/scripts/qr_invoice.js <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

bash

node {baseDir}/scripts/qr_invoice.js <bolt11_invoice>

在终端渲染Lightning发票（BOLT-11）的二维码到标准错误输出，并在

/tmp

目录生成PNG图片文件。标准输出的JSON包含

pngPath

字段，为PNG文件的绝对路径。

向用户发送二维码图片：运行该脚本后，使用JSON输出中的

pngPath

，通过当前聊天的原生消息发送能力将PNG作为媒体附件发送给用户。

```
bolt11_invoice
```
— BOLT-11付款请求字符串（必填）

输出JSON包含：

```
invoice
```
— 大写的发票字符串
```
qrRendered
```
— 始终为
```
true
```
```
qrSize
```
— QR码模块数量
```
errorCorrection
```
—
```
"L"
```
（低容错）
```
pngPath
```
— 生成的PNG文件绝对路径（例如
```
/tmp/blink_qr_1234567890.png
```
）
```
pngBytes
```
— 文件大小（字节）

List Transactions

列出交易记录

bash

node {baseDir}/scripts/transactions.js [--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

bash

node {baseDir}/scripts/transactions.js [--first N] [--after CURSOR] [--wallet BTC|USD]

分页列出近期交易（入账和出账），返回交易方向、金额、状态、类型（lightning/onchain/intraledger）及元数据。

```
--first N
```
— 返回交易数量（默认：20，最大：100）
```
--after CURSOR
```
— 分页游标，来自上一次响应的
```
endCursor
```
```
--wallet BTC|USD
```
— 按钱包币种过滤

Get BTC/USD Price

获取BTC/USD价格

bash

node {baseDir}/scripts/price.js [amount_sats]
node {baseDir}/scripts/price.js --usd <amount_usd>
node {baseDir}/scripts/price.js --history <range>
node {baseDir}/scripts/price.js --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.
```
price.js 1760
```
→
```
$1.20
```
)

--usd <amount>
— convert a USD amount to sats (e.g.

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

bash

node {baseDir}/scripts/price.js [amount_sats]
node {baseDir}/scripts/price.js --usd <amount_usd>
node {baseDir}/scripts/price.js --history <range>
node {baseDir}/scripts/price.js --currencies

多功能汇率工具。所有价格查询均为公开（无需API密钥），但若已配置密钥会自动发送。

模式：

无参数 — 当前BTC/USD价格和每美元对应的聪数
<amount_sats>
— 将聪数转换为USD（例如
```
price.js 1760
```
→
```
$1.20
```
）

--usd <amount>
— 将USD转换为聪数（例如

price.js --usd 5.00

→

7350 sats

）

--history <range>
— BTC历史价格数据及汇总统计（最高价/最低价/涨跌幅）。支持范围：
```
ONE_DAY
```
、
```
ONE_WEEK
```
、
```
ONE_MONTH
```
、
```
ONE_YEAR
```
、
```
FIVE_YEARS
```
--currencies
— 列出所有支持的显示币种（ID、名称、符号、标识）

Account Info

账户信息

bash

node {baseDir}/scripts/account_info.js

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.

bash

node {baseDir}/scripts/account_info.js

显示账户等级、支出限额（提现、内部转账、兑换）、默认钱包及钱包汇总信息（包含BTC余额的预计算USD估值）。限额以USD美分为单位，按24小时滚动窗口计算。

Quote Internal BTC <-> USD Swap

获取BTC<->USD内部兑换报价

bash

node {baseDir}/scripts/swap_quote.js <direction> <amount> [--unit sats|cents] [--ttl-seconds N] [--immediate]

Builds a deterministic quote-like receipt for internal wallet conversion.

```
direction
```
—
```
btc-to-usd
```
or
```
usd-to-btc
```
```
amount
```
— positive integer amount (unit inferred by direction unless
```
--unit
```
is set)
```
--unit sats|cents
```
— optional override for input unit
```
--ttl-seconds N
```
— quote validity window in seconds (default: 60)
```
--immediate
```
— mark intent for immediate execution mode in quote receipt

Uses Blink's conversion estimation path for pricing and records:

pre-swap balances
quote id / expiry metadata
amount in/out terms

execution path (

intraLedgerPaymentSend

intraLedgerUsdPaymentSend

)

bash

node {baseDir}/scripts/swap_quote.js <direction> <amount> [--unit sats|cents] [--ttl-seconds N] [--immediate]

生成内部钱包转换的确定性报价凭证。

```
direction
```
—
```
btc-to-usd
```
或
```
usd-to-btc
```
```
amount
```
— 正整数金额（单位由方向推断，除非设置
```
--unit
```
）
```
--unit sats|cents
```
— 可选，覆盖输入单位
```
--ttl-seconds N
```
— 报价有效期（秒，默认：60）
```
--immediate
```
— 标记报价为立即执行模式

使用Blink的转换估算路径计算价格，记录：

兑换前余额
报价ID/到期元数据
出入金额条款

执行路径（

intraLedgerPaymentSend

或

intraLedgerUsdPaymentSend

）

Execute Internal BTC <-> USD Swap

执行BTC<->USD内部兑换

bash

node {baseDir}/scripts/swap_execute.js <direction> <amount> [--unit sats|cents] [--ttl-seconds N] [--immediate] [--dry-run] [--memo "text"]

Executes a wallet-native internal conversion between your BTC and USD wallets.

```
--dry-run
```
— returns an execution receipt without performing the mutation
```
--memo "text"
```
— optional memo attached to the internal transfer

Execution receipts include quote terms, pre/post balances, balance deltas, and final status.

Fee/settlement interpretation:

```
quote.feeSats
```
,
```
quote.feeBps
```
, and
```
quote.slippageBps
```
are currently returned as zero in live runs.
You can still see a small quote-to-settlement spread (often 1 sat or 1 cent) due to integer rounding between sats and cents.
Always compute effective cost from
```
quote.amountOut
```
versus
```
balanceDelta
```
instead of relying only on explicit fee fields.

For deeper behavior details and formulas, see swap-operations.

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
.

bash

node {baseDir}/scripts/swap_execute.js <direction> <amount> [--unit sats|cents] [--ttl-seconds N] [--immediate] [--dry-run] [--memo "text"]

在BTC与USD钱包间执行原生内部转换。

```
--dry-run
```
— 返回执行凭证但不实际执行转换
```
--memo "text"
```
— 附加到内部转账的可选备注

执行凭证包含报价条款、兑换前后余额、余额变化及最终状态。

手续费/结算说明：

在实际运行中，
```
quote.feeSats
```
、
```
quote.feeBps
```
和
```
quote.slippageBps
```
当前返回为0。
由于聪和美分之间的整数四舍五入，仍可能看到报价与结算之间的微小差价（通常为1聪或1美分）。
请始终通过
```
quote.amountOut
```
与
```
balanceDelta
```
计算实际成本，不要仅依赖显式手续费字段。

如需了解更深入的行为细节和公式，请参考swap-operations。

AGENT提示： 该命令会在钱包间转移资金。执行前务必先使用
--dry-run
参数，向用户展示报价并获得明确确认后，再移除
--dry-run
执行真实操作。

Realtime Subscriptions

实时订阅

Blink supports GraphQL subscriptions over WebSocket using the

graphql-transport-ws

protocol. Node 20 requires the

--experimental-websocket

flag.

Blink支持通过WebSocket使用

graphql-transport-ws

协议的GraphQL订阅。Node 20需要添加

--experimental-websocket

参数。

Subscribe to Invoice Payment Status

订阅发票付款状态

bash

node --experimental-websocket {baseDir}/scripts/subscribe_invoice.js <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.

bash

node --experimental-websocket {baseDir}/scripts/subscribe_invoice.js <bolt11_invoice> [--timeout <seconds>]

监控单个发票，当状态变为PAID或EXPIRED时退出。状态更新输出到标准错误，JSON结果输出到标准输出。

Subscribe to Account Updates (myUpdates)

订阅账户更新（myUpdates）

bash

node --experimental-websocket {baseDir}/scripts/subscribe_updates.js [--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.

bash

node --experimental-websocket {baseDir}/scripts/subscribe_updates.js [--timeout <seconds>] [--max <count>]

实时流式传输账户更新，每个事件以JSON行（NDJSON）输出到标准输出。使用

--max

参数可在接收N个事件后停止。

API Reference

API参考

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
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
Swap quote (BTC <-> USD)	`query currencyConversionEstimation`	Read
Swap execute BTC -> USD	`mutation intraLedgerPaymentSend`	Write
Swap execute USD -> BTC	`mutation intraLedgerUsdPaymentSend`	Write
Subscribe invoice	`subscription lnInvoicePaymentStatus`	Read
Subscribe updates	`subscription myUpdates`	Read

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.

操作	GraphQL	所需权限
查询余额	`query me` + `currencyConversionEstimation`	只读
创建BTC发票	`mutation lnInvoiceCreate`	收款
创建USD发票	`mutation lnUsdInvoiceCreate`	收款
检查发票状态	`query invoiceByPaymentHash`	只读
支付发票	`mutation lnInvoicePaymentSend`	付款
向Lightning地址付款	`mutation lnAddressPaymentSend`	付款
向LNURL付款	`mutation lnurlPaymentSend`	付款
估算BTC付款手续费	`mutation lnInvoiceFeeProbe`	只读
估算USD付款手续费	`mutation lnUsdInvoiceFeeProbe`	只读
列出交易记录	`query transactions`	只读
价格/转换	`query currencyConversionEstimation`	无（公开）
价格历史	`query btcPriceList`	无（公开）
币种列表	`query currencyList`	无（公开）
实时价格	`query realtimePrice`	无（公开）
账户信息	`query me` + `currencyConversionEstimation`	只读
BTC<->USD兑换报价	`query currencyConversionEstimation`	只读
执行BTC转USD	`mutation intraLedgerPaymentSend`	付款
执行USD转BTC	`mutation intraLedgerUsdPaymentSend`	付款
订阅发票状态	`subscription lnInvoicePaymentStatus`	只读
订阅账户更新	`subscription myUpdates`	只读

API端点：

https://api.blink.sv/graphql

（生产环境） 认证方式：

X-API-KEY

请求头

USD钱包说明：

lnInvoicePaymentSend

、

lnAddressPaymentSend

和

lnurlPaymentSend

突变都接受BTC或USD钱包ID。当提供USD钱包ID时，API会自动扣除等值USD金额。

lnAddressPaymentSend

和

lnurlPaymentSend

的金额始终以聪为单位指定，与钱包类型无关。

Output Format

输出格式

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

所有脚本向标准输出输出结构化JSON，状态消息和错误输出到标准错误。成功时退出码为0，失败时为1。

Balance output example

余额输出示例

json

{
  "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"
}

json

{
  "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):

json

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

Second JSON (when payment resolves):

json

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

第一个JSON（立即输出）：

json

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

第二个JSON（付款状态确认时输出）：

json

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

Invoice status output example

发票状态输出示例

json

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

json

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

Payment output example (BTC wallet)

BTC钱包付款输出示例

json

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

json

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

Payment output example (USD wallet)

USD钱包付款输出示例

json

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

json

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

Price output example

价格输出示例

json

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

json

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

USD-to-sats conversion output example

USD转聪数转换输出示例

json

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

json

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

Price history output example

价格历史输出示例

json

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

json

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

Transaction list output example

交易记录列表输出示例

json

{
  "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"
  }
}

json

{
  "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"
  }
}

Swap quote output example

兑换报价输出示例

json

{
  "event": "swap_quote",
  "dryRun": true,
  "direction": "BTC_TO_USD",
  "preBalance": {
    "btcWalletId": "btc_wallet_id",
    "usdWalletId": "usd_wallet_id",
    "btcBalanceSats": 250000,
    "usdBalanceCents": 150000
  },
  "quote": {
    "quoteId": "blink-swap-1740000000-424242",
    "amountIn": { "value": 5000, "unit": "sats" },
    "amountOut": { "value": 340, "unit": "cents" },
    "expiresAtEpochSeconds": 1740000060,
    "immediateExecution": false,
    "executionPath": "blink:intraLedgerPaymentSend"
  }
}

json

{
  "event": "swap_quote",
  "dryRun": true,
  "direction": "BTC_TO_USD",
  "preBalance": {
    "btcWalletId": "btc_wallet_id",
    "usdWalletId": "usd_wallet_id",
    "btcBalanceSats": 250000,
    "usdBalanceCents": 150000
  },
  "quote": {
    "quoteId": "blink-swap-1740000000-424242",
    "amountIn": { "value": 5000, "unit": "sats" },
    "amountOut": { "value": 340, "unit": "cents" },
    "expiresAtEpochSeconds": 1740000060,
    "immediateExecution": false,
    "executionPath": "blink:intraLedgerPaymentSend"
  }
}

Swap execution output example

兑换执行输出示例

json

{
  "event": "swap_execution",
  "dryRun": false,
  "direction": "USD_TO_BTC",
  "status": "SUCCESS",
  "succeeded": true,
  "preBalance": {
    "btcBalanceSats": 250000,
    "usdBalanceCents": 150000
  },
  "postBalance": {
    "btcBalanceSats": 253650,
    "usdBalanceCents": 149500
  },
  "balanceDelta": {
    "btcDeltaSats": 3650,
    "usdDeltaCents": -500
  },
  "quote": {
    "quoteId": "blink-swap-1740000015-556677",
    "executionPath": "blink:intraLedgerUsdPaymentSend"
  },
  "execution": {
    "path": "blink:intraLedgerUsdPaymentSend",
    "transactionId": "tx_abc123"
  }
}

json

{
  "event": "swap_execution",
  "dryRun": false,
  "direction": "USD_TO_BTC",
  "status": "SUCCESS",
  "succeeded": true,
  "preBalance": {
    "btcBalanceSats": 250000,
    "usdBalanceCents": 150000
  },
  "postBalance": {
    "btcBalanceSats": 253650,
    "usdBalanceCents": 149500
  },
  "balanceDelta": {
    "btcDeltaSats": 3650,
    "usdDeltaCents": -500
  },
  "quote": {
    "quoteId": "blink-swap-1740000015-556677",
    "executionPath": "blink:intraLedgerUsdPaymentSend"
  },
  "execution": {
    "path": "blink:intraLedgerUsdPaymentSend",
    "transactionId": "tx_abc123"
  }
}

Typical Agent Workflows

典型Agent工作流

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

接收付款（推荐：自动订阅+二维码图片）

bash

undefined

bash

undefined

1. Create invoice — script auto-subscribes and outputs two JSON objects

1. 创建发票——脚本自动订阅并输出两个JSON对象

node {baseDir}/scripts/create_invoice.js 1000 "Payment for service"

node {baseDir}/scripts/create_invoice.js 1000 "服务付款"

→ First JSON: {"event": "invoice_created", "paymentRequest": "lnbc...", ...}

→ 第一个JSON: {"event": "invoice_created", "paymentRequest": "lnbc...", ...}

→ Read paymentRequest from first JSON immediately

→ 立即读取第一个JSON中的paymentRequest

2. Generate QR code PNG

2. 生成二维码PNG

node {baseDir}/scripts/qr_invoice.js <paymentRequest>

→ JSON includes "pngPath": "/tmp/blink_qr_123456.png"

→ JSON包含"pngPath": "/tmp/blink_qr_123456.png"

→ Send the PNG file to the user as a media attachment in the current chat

→ 将PNG文件作为媒体附件发送给当前聊天的用户

3. The create_invoice.js script is still running, waiting for payment

3. create_invoice.js脚本仍在运行，等待付款

→ Second JSON: {"event": "subscription_result", "status": "PAID", ...}

→ 第二个JSON: {"event": "subscription_result", "status": "PAID", ...}

→ When PAID: notify the user that payment has been received

→ 状态为PAID时：通知用户付款已收到

→ When EXPIRED: notify the user the invoice expired

→ 状态为EXPIRED时：通知用户发票已过期


**Important**: The `create_invoice.js` script 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.


**重要提示**：`create_invoice.js`脚本输出两个用换行分隔的JSON对象，请将它们解析为独立的JSON对象，而非单个JSON数组。第一个对象立即输出；第二个对象在付款状态确认时输出。

Receive a payment (polling fallback)

接收付款（轮询备选方案）

bash

undefined

bash

undefined

1. Create invoice without auto-subscribe

1. 创建发票，不自动订阅

node {baseDir}/scripts/create_invoice.js 1000 --no-subscribe "Payment for service"

node {baseDir}/scripts/create_invoice.js 1000 --no-subscribe "服务付款"

2. Give the paymentRequest to the payer

2. 将paymentRequest提供给付款方

3. Poll for payment

3. 轮询付款状态

node {baseDir}/scripts/check_invoice.js <payment_hash>

4. Verify balance

4. 验证余额

node {baseDir}/scripts/balance.js

undefined

node {baseDir}/scripts/balance.js

undefined

Receive a USD payment

接收USD付款

bash

undefined

bash

undefined

Same two-phase pattern as BTC, but using create_invoice_usd.js

与BTC付款流程相同，但使用create_invoice_usd.js

Note: USD invoices expire in ~5 minutes

注意：USD发票约5分钟后过期

node {baseDir}/scripts/create_invoice_usd.js 500 "Five dollars for service"

node {baseDir}/scripts/create_invoice_usd.js 500 "五美元服务费用"

→ First JSON: {"event": "invoice_created", "amountCents": 500, "amountUsd": "$5.00", ...}

→ 第一个JSON: {"event": "invoice_created", "amountCents": 500, "amountUsd": "$5.00", ...}

Generate QR and send to user, then wait for second JSON

生成二维码并发送给用户，然后等待第二个JSON

undefined

undefined

Send a payment (with fee check)

发送付款（含手续费检查）

bash

undefined

bash

undefined

1. Check current balance

1. 查询当前余额

node {baseDir}/scripts/balance.js

2. Estimate fee

2. 估算手续费

node {baseDir}/scripts/fee_probe.js lnbc1000n1...

3. Send payment

3. 发送付款

node {baseDir}/scripts/pay_invoice.js lnbc1000n1...

4. Verify in transaction history

4. 在交易历史中验证

node {baseDir}/scripts/transactions.js --first 1

undefined

node {baseDir}/scripts/transactions.js --first 1

undefined

Send from the USD wallet

从USD钱包付款

bash

undefined

bash

undefined

Pay an invoice from the USD wallet

从USD钱包支付发票

node {baseDir}/scripts/fee_probe.js lnbc1000n1... --wallet USD node {baseDir}/scripts/pay_invoice.js lnbc1000n1... --wallet USD

Send to a Lightning Address from the USD wallet

从USD钱包向Lightning地址付款

node {baseDir}/scripts/pay_lnaddress.js user@blink.sv 1000 --wallet USD

Send via LNURL from the USD wallet

从USD钱包通过LNURL付款

node {baseDir}/scripts/pay_lnurl.js lnurl1... 1000 --wallet USD

Note: for lnaddress and lnurl, the amount is always in satoshis.

注意：对于lnaddress和lnurl，金额始终以聪为单位指定。

The Blink API debits the USD equivalent from the USD wallet automatically.

Blink API会自动从USD钱包扣除等值USD金额。

undefined

undefined

Convert sats to USD value

将聪数转换为USD价值

bash

undefined

bash

undefined

Check how much 1760 sats is worth in USD

查询1760聪对应的USD价值

node {baseDir}/scripts/price.js 1760

→ $1.20

undefined

undefined

Convert USD to sats

将USD转换为聪数

bash

undefined

bash

undefined

How many sats is $5.00?

$5.00对应多少聪？

node {baseDir}/scripts/price.js --usd 5.00

→ 7350 sats

undefined

undefined

Swap BTC to USD (quote then execute)

BTC转USD兑换（先报价再执行）

bash

undefined

bash

undefined

1. Build quote and inspect terms

1. 生成报价并查看条款

node {baseDir}/scripts/swap_quote.js btc-to-usd 10000

2. Execute the swap

2. 执行兑换

node {baseDir}/scripts/swap_execute.js btc-to-usd 10000

undefined

node {baseDir}/scripts/swap_execute.js btc-to-usd 10000

undefined

Swap USD to BTC (dry-run then execute)

USD转BTC兑换（先试运行再执行）

bash

undefined

bash

undefined

1. Dry-run execution receipt without moving funds

1. 试运行执行凭证，不转移资金

node {baseDir}/scripts/swap_execute.js usd-to-btc 500 --unit cents --dry-run

2. Real execution

2. 真实执行

node {baseDir}/scripts/swap_execute.js usd-to-btc 500 --unit cents

undefined

node {baseDir}/scripts/swap_execute.js usd-to-btc 500 --unit cents

undefined

Check price history

查询价格历史

bash

undefined

bash

undefined

Get BTC price over the last 24 hours

获取过去24小时的BTC价格

node {baseDir}/scripts/price.js --history ONE_DAY

Get BTC price over the last month

获取过去一个月的BTC价格

node {baseDir}/scripts/price.js --history ONE_MONTH

undefined

node {baseDir}/scripts/price.js --history ONE_MONTH

undefined

Security

安全说明

API Key Handling

API密钥处理

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.

API密钥等同于钱包访问权限——拥有Write权限的任何人都可以转走您的全部余额。
最小权限原则——查询余额使用只读权限，收款使用收款权限，仅当需要付款时才使用付款权限。
绝不暴露密钥——不要回显、记录或在聊天消息/文件中包含
```
BLINK_API_KEY
```
。
密钥仅用于服务器端/Agent，绝不要嵌入客户端代码。

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.
No other network calls. Scripts do not phone home, send telemetry, or contact any third-party services.

HTTPS出站：所有GraphQL查询和突变均发送至
```
api.blink.sv
```
（或
```
BLINK_API_URL
```
指定的地址）。
WSS出站：订阅WebSocket连接至
```
ws.blink.sv
```
（或
```
BLINK_WS_URL
```
指定的地址）。
无其他网络请求：脚本不会向其他第三方服务发送遥测数据或进行其他网络调用。

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.
No other filesystem writes. Scripts do not create config files, databases, or caches.

RC文件读取：如果在
```
process.env
```
中未找到
```
BLINK_API_KEY
```
，客户端会扫描
```
~/.profile
```
、
```
~/.bashrc
```
、
```
~/.bash_profile
```
和
```
~/.zshrc
```
中匹配
```
export BLINK_API_KEY=...
```
的行，仅提取该特定导出的值——不会读取这些文件中的其他数据。环境变量始终优先检查。
QR PNG生成：
```
qr
```
命令会将临时PNG文件写入
```
/tmp/blink_qr_*.png
```
，这些是标准图片文件，除QR内容外无其他嵌入元数据。
无其他文件写入：脚本不会创建配置文件、数据库或缓存。

Stateless Design

无状态设计

This skill stores no data between runs. There are no databases, config files, session tokens, or caches. Each script invocation is independent — it reads the API key, makes API calls, outputs JSON, and exits.

本Skill在运行之间不存储任何数据，没有数据库、配置文件、会话令牌或缓存。每次脚本调用都是独立的——读取API密钥、调用API、输出JSON然后退出。

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 —
```
price.js
```
works without an API key; only wallet operations require authentication.

付款不可逆——Lightning付款一旦完成，无法撤销。
先在测试环境测试——使用
```
BLINK_API_URL=https://api.staging.blink.sv/graphql
```
指向signet测试环境，使用测试资金。
USD发票过期快——由于汇率锁定，约5分钟后过期。
价格查询公开——
```
price.js
```
无需API密钥即可使用；仅钱包操作需要认证。

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: wallet-native BTC<->USD conversion flows, quote/execution receipts, and fallback behavior.

blink-api-and-auth：API端点、认证方式、权限范围、测试环境配置及错误处理。
payment-operations：付款工作流、BTC与USD钱包选择、手续费估算及安全防护。
invoice-lifecycle：发票创建、两阶段输出解析、监控策略、二维码生成及过期处理。
swap-operations：BTC<->USD原生兑换流程、报价/执行凭证及备选行为。

Files

文件列表

```
{baseDir}/scripts/balance.js
```
— Check wallet balances
```
{baseDir}/scripts/create_invoice.js
```
— Create BTC Lightning invoices (auto-subscribes to payment status)
```
{baseDir}/scripts/create_invoice_usd.js
```
— Create USD-denominated Lightning invoices (auto-subscribes to payment status)
```
{baseDir}/scripts/check_invoice.js
```
— Check invoice payment status (polling)
```
{baseDir}/scripts/pay_invoice.js
```
— Pay BOLT-11 invoices (BTC or USD wallet)
```
{baseDir}/scripts/pay_lnaddress.js
```
— Pay to Lightning Addresses (BTC or USD wallet)
```
{baseDir}/scripts/pay_lnurl.js
```
— Pay to LNURL strings (BTC or USD wallet)
```
{baseDir}/scripts/fee_probe.js
```
— Estimate payment fees (BTC or USD wallet)
```
{baseDir}/scripts/qr_invoice.js
```
— Render invoice QR code (terminal + PNG file)
```
{baseDir}/scripts/transactions.js
```
— List transaction history
```
{baseDir}/scripts/price.js
```
— Get BTC/USD exchange rate
```
{baseDir}/scripts/account_info.js
```
— Show account info and limits
```
{baseDir}/scripts/swap_quote.js
```
— Build BTC<->USD swap quote receipts (dry-run)
```
{baseDir}/scripts/swap_execute.js
```
— Execute BTC<->USD wallet-native swaps (or dry-run receipts)
```
{baseDir}/scripts/subscribe_invoice.js
```
— Subscribe to invoice payment status (standalone)
```
{baseDir}/scripts/subscribe_updates.js
```
— Subscribe to realtime account updates

```
{baseDir}/scripts/balance.js
```
— 查询钱包余额
```
{baseDir}/scripts/create_invoice.js
```
— 创建BTC Lightning发票（自动订阅付款状态）
```
{baseDir}/scripts/create_invoice_usd.js
```
— 创建USD计价Lightning发票（自动订阅付款状态）
```
{baseDir}/scripts/check_invoice.js
```
— 检查发票付款状态（轮询方式）
```
{baseDir}/scripts/pay_invoice.js
```
— 支付BOLT-11发票（BTC或USD钱包）
```
{baseDir}/scripts/pay_lnaddress.js
```
— 向Lightning地址付款（BTC或USD钱包）
```
{baseDir}/scripts/pay_lnurl.js
```
— 向LNURL字符串付款（BTC或USD钱包）
```
{baseDir}/scripts/fee_probe.js
```
— 估算付款手续费（BTC或USD钱包）
```
{baseDir}/scripts/qr_invoice.js
```
— 生成发票二维码（终端显示+PNG文件）
```
{baseDir}/scripts/transactions.js
```
— 列出交易历史
```
{baseDir}/scripts/price.js
```
— 获取BTC/USD汇率
```
{baseDir}/scripts/account_info.js
```
— 显示账户信息及限额
```
{baseDir}/scripts/swap_quote.js
```
— 生成BTC<->USD兑换报价凭证（试运行）
```
{baseDir}/scripts/swap_execute.js
```
— 执行BTC<->USD钱包原生兑换（或生成试运行凭证）
```
{baseDir}/scripts/subscribe_invoice.js
```
— 订阅发票付款状态（独立脚本）
```
{baseDir}/scripts/subscribe_updates.js
```
— 订阅实时账户更新