首页 › 龙虾技能列表 › Bitkit Cli — Bitkit工具

Bitkit Cli — Bitkit工具

v0.2.0

[AI辅助] Bitcoin Lightning payment CLI for agents. Lowest LSP fees. Self-custody wallet with LNURL, typed exit codes, JSON envelope output, encrypted messaging, and d...

0· 519·0 当前·0 累计
by @ovitrif (Ovi Trif)·MIT-0
下载技能包
License
MIT-0
最后更新
2026/4/12
安全扫描
VirusTotal
可疑
查看报告
OpenClaw
安全
high confidence
The skill is internally coherent: it documents and requires the bitkit CLI, its runtime behavior and install mechanism match the documentation, and it does not request unrelated credentials or privileged platform access — but it exposes sensitive wallet functionality (seed, daemon API, webhooks) that you should treat carefully.
评估建议
This skill appears to be what it claims (a bitkit CLI wrapper) and the install script downloads releases from GitHub with checksum checks. Before installing or invoking it, consider the following: - Only install/run if you trust the upstream project and the agent invoking it. The skill creates an on-host, self-custodial Bitcoin wallet and daemon — that means private keys/seed phrases and an API password will be stored on-disk (default ~/.bitkit). Treat those as high-value secrets. - The SKILL....
详细分析 ▾
✓ 用途与能力
Name/description (Bitcoin Lightning CLI for agents) aligns with the files and runtime instructions. The skill only requires the 'bitkit' binary and the SKILL.md and README describe using that binary; there are no unrelated environment variables or credentials declared. The one minor metadata inconsistency: the registry metadata lists no homepage while SKILL.md includes a GitHub homepage URL, but this does not affect capability alignment.
ℹ 指令范围
SKILL.md instructs the agent to run `bitkit` commands (init, start, invoice, pay, etc.) and to use daemon mode and webhooks. Those instructions stay within the stated purpose, but they also create and manage sensitive local state: seed_phrase/seed.enc, an auto-generated daemon API password (api-password file), and config/webhook settings that can POST events off-host. The docs explicitly recommend `--no-password` for agent automation (i.e., storing seed plaintext) — this is a functional choice but a high-risk one if the host or agent is not fully trusted.
✓ 安装机制
install.sh downloads release archives from GitHub Releases (synonymdev/bitkit-cli) and verifies checksums via checksums.sha256 when a local verifier exists. This is a standard install pattern and uses a well-known release host. The script uses curl and extracts a tarball into /usr/local/bin or ~/.local/bin; it warns if checksum verification tools are missing. Note: piping remote scripts to sh is common but carries the usual risk; the script does perform checksum verification where possible.
ℹ 凭证需求
The skill declares no required environment variables or credentials — appropriate for a CLI wrapper. The documentation references reasonable env vars (BITKIT_DIR, BITKIT_NETWORK, BITKIT_PASSWORD, BITKIT_LISTEN). No unrelated secrets are requested. However the runtime behavior will create sensitive artifacts (wallet seed, API password file, config with webhook_url) which are proportionate to a self-custodial wallet but must be treated as high-value secrets.
✓ 持久化与权限
The skill does not request 'always: true' and uses the platform-default ability for autonomous invocation. It will write persistent wallet and daemon files under ~/.bitkit (or BITKIT_DIR) and may run a background daemon that exposes an HTTP API and websocket/events endpoint — this is expected for the functionality. There is no evidence it tries to modify other skills or system-wide agent settings beyond installing its own binary into standard locations.
安全有层次，运行前请审查代码。

License

MIT-0

可自由使用、修改和再分发，无需署名。

运行时依赖

无特殊依赖

版本

latestv0.2.02026/2/22

Add --qr flag for address and invoice commands, LNURL/Lightning Address support, webhooks, auto-liquidity, encrypted messaging

● 可疑

安装命令 点击复制

官方npx clawhub@latest install bitkit-cli
镜像加速npx clawhub@latest install bitkit-cli --registry https://cn.clawhub-mirror.com

技能文档

Bitcoin Lightning payment CLI for agents. Lowest LSP fees. Self-custody wallet with LNURL/Lightning Address support, typed exit codes, JSON envelope output, encrypted Pubky messaging, and daemon mode.

Install: curl -sSL https://raw.githubusercontent.com/synonymdev/bitkit-cli/main/install.sh | sh Binary names: bitkit 或 bk (identical alias) Always 使用: --json 标志 在...上 every invocation 对于 parseable 输出.

JSON Envelope

All --json output uses a consistent envelope:

成功 (stdout): 

{ "ok": true, "data": { ... } }

错误 (stderr): 

{ "ok": false, "error": "message", "code": 1 }

Parse with: jq -r '.data.field' for success data, check .ok first.

Quick 开始

# 1. Create wallet (no encryption for agent use)
bk init --no-password --json
# 2. Start daemon for instant command execution
bk start --json
# 3. Get on-chain address and fund it
ADDRESS=$(bk address --json | jq -r '.data.address')
# 4. Order inbound Lightning liquidity via LSP
ORDER=$(bk lsp create-order 500000 --json)
ORDER_ID=$(echo "$ORDER" | jq -r '.data.order_id')
# 5. Pay the order (on-chain to payment_address), then open channel
bk lsp open-channel "$ORDER_ID" --listen 9735 --json
# 6. Create an invoice and receive payment
bk invoice 5000 --description "agent service" --wait --listen 9735 --json
# 7. Pay someone else's invoice
bk pay lnbc50u1p... --json
# 8. Check balance and history
bk balance --json
bk history --json
# 9. Stop daemon when done
bk stop --json

Daemon Mode

By default each command cold-starts the LDK node (slow). Start a persistent daemon for instant execution:

bk start --json           # start daemon (default port 3457)
bk status --json          # check if running
bk balance --json         # instant -- proxied through daemon
bk stop --json            # stop daemon

When the daemon is running, all commands automatically proxy through its HTTP API. When stopped, commands fall back to per-command cold-start. No code changes needed.

开始

Start the background daemon. Idempotent -- returns current PID if already running.

bk start --json
bk start --port 8080 --json

{
  "ok": true,
  "data": {
    "status": "started",
    "pid": 12345,
    "port": 3457
  }
}
ArgDefaultDescription
--port 3457HTTP API port
status is "started" or "already_running".

停止

Stop the running daemon.

bk stop --json

{
  "ok": true,
  "data": {
    "status": "stopped",
    "pid": 12345
  }
}

Errors if no daemon is running (exit code 1).

status

Check daemon status.

bk status --json

{
  "ok": true,
  "data": {
    "running": true,
    "pid": 12345,
    "port": 3457,
    "started_at": "2026-02-19T10:00:00+00:00",
    "version": "0.1.0"
  }
}

When stopped: running is false, all other fields are null.

Global Flags

FlagEnv VariableDefaultDescription
--json--offMachine-readable JSON to stdout
--dir BITKIT_DIR~/.bitkit/Wallet data directory
--network BITKIT_NETWORKmainnetmainnet or regtest
--listen BITKIT_LISTENoffP2P listen port on 0.0.0.0:
--password BITKIT_PASSWORD--Wallet password (for encrypted seeds)

Command Reference

Wallet

init

Create a new wallet. Idempotent -- re-running prints existing wallet info.

bk init --no-password --json

{
  "ok": true,
  "data": {
    "node_id": "02abc123...",
    "seed_phrase": "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
    "wallet_dir": "/root/.bitkit",
    "network": "mainnet",
    "pubky_id": "8pinxrz9tuxfz3qo5gkhdebuhtq6mrimh3matdncsrsno7kg45mo"
  }
}
ArgRequiredDescription
--no-passwordone ofStore seed as plaintext (for agents)
--password one ofEncrypt seed with AES-256-GCM + Argon2id

info

Show node status, channel counts, sync state.

bk info --json

{
  "ok": true,
  "data": {
    "node_id": "02abc123...",
    "network": "mainnet",
    "channels_active": 1,
    "channels_pending": 0,
    "block_height": 880000,
    "synced": true,
    "wallet_dir": "/root/.bitkit"
  }
}

balance

Show Lightning and on-chain balances in satoshis.

bk balance --json

{
  "ok": true,
  "data": {
    "lightning_sats": 450000,
    "onchain_sats": 50000,
    "total_sats": 500000,
    "total_onchain_sats": 55000,
    "anchor_reserve_sats": 5000,
    "pending_sweep_sats": 0,
    "pending_sweeps": []
  }
}
  • onchain_sats -- spendable 在...上-chain balance
  • total_onchain_sats -- 所有 在...上-chain funds 包括 reserved
  • anchor_reserve_sats -- sats reserved 对于 anchor channel fees
  • pending_sweep_sats -- funds sweeping 从 closed channels (不 尚未 spendable)
  • pending_sweeps -- 数组 的 sweep entries 带有 amount_sats, status, spending_txid, confirmation_height
ArgDescription
--btcDisplay in BTC instead of sats (human output only)

配置

Show resolved configuration with source tracking. Does not start the node.

bk config --json

{
  "ok": true,
  "data": {
    "network": { "value": "mainnet", "source": "default" },
    "wallet_dir": { "value": "/root/.bitkit", "source": "default" },
    "chain_source": { "value": "esplora", "source": "file" },
    "esplora_url": { "value": "https://blockstream.info/api", "source": "file" },
    "electrum_url": { "value": "", "source": "file" },
    "rgs_url": { "value": "https://rapidsync.lightningdevkit.org/snapshot", "source": "file" },
    "blocktank_url": { "value": "https://api1.blocktank.to/api", "source": "file" },
    "listen_port": { "value": "off", "source": "default" }
  }
}

Each entry has value (resolved value) and source (cli, env, file, or default).

address

Get a new on-chain receive address. Generates a fresh address each call. Optionally validate an existing address.

bk address --json
bk address --type taproot --json
bk address --validate bc1q... --json

Generate address: 

{
  "ok": true,
  "data": { "address": "bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4", "address_type": "native-segwit" }
}

Validate address (--validate): 

{
  "ok": true,
  "data": { "address": "bc1q...", "valid": true, "network": "mainnet", "reason": null }
}

On invalid address: valid is false and reason explains why.

ArgDefaultDescription
--type native-segwitAddress type: legacy, nested-segwit, native-segwit, taproot
--validate --Validate for the current network; no node start needed
--qroffDisplay address as QR code in terminal (human output only)

发送

Send bitcoin on-chain to an address.

bk send bc1q... 50000 --json
bk send bc1q... 50000 --fee-rate 5 --json
bk send bc1q... --drain --json
bk send bc1q... 50000 --utxo : --json

{
  "ok": true,
  "data": {
    "txid": "abc123...",
    "address": "bc1q...",
    "amount_sats": 50000,
    "drain": false,
    "fee_rate_sat_per_vb": 5,
    "utxos_used": ["abc123...:0"]
  }
}

When --drain is used, amount_sats is null. When no --fee-rate is set, fee_rate_sat_per_vb is null.

ArgDefaultDescription
requiredDestination Bitcoin address
--Amount in satoshis (omit with --drain)
--drainoffSend all spendable funds (mutually exclusive with --utxo)
--fee-rate autoFee rate in sat/vb
--utxo --Spend a specific UTXO (repeatable; incompatible with --drain)

列表-utxos

List all spendable UTXOs in the on-chain wallet.

bk list-utxos --json

{
  "ok": true,
  "data": {
    "utxos": [
      {
        "txid": "abc123...",
        "vout": 0,
        "value_sats": 1000000,
        "outpoint": "abc123...:0"
      }
    ],
    "total_sats": 1000000,
    "count": 1
  }
}

Use outpoint values (e.g. abc123...:0) as --utxo arguments for send and estimate-fee.

estimate-fee

Preview the fee for an on-chain send without broadcasting.

bk estimate-fee bc1q... 50000 --json
bk estimate-fee bc1q... 50000 --fee-rate 5 --json

{
  "ok": true,
  "data": {
    "fee_sats": 250,
    "address": "bc1q...",
    "amount_sats": 50000,
    "fee_rate_sat_per_vb": 5
  }
}

fee_rate_sat_per_vb is null when not specified (node chooses automatically).

ArgDefaultDescription
requiredDestination Bitcoin address
requiredAmount to send in satoshis
--fee-rate autoOverride fee rate in sat/vb
--utxo --Restrict coin selection to specific UTXOs

bump-fee

Replace an unconfirmed transaction with a higher-fee version (RBF). The original transaction must be in the mempool and RBF-enabled.

bk bump-fee   --json

{
  "ok": true,
  "data": {
    "original_txid": "abc123...",
    "new_txid": "def456...",
    "fee_rate_sat_per_vb": 20
  }
}
ArgDescription
TXID of the unconfirmed transaction to replace
New fee rate in sat/vb (must be higher than the original)
On failure (invalid txid, not in mempool, RBF not signalled): exits with code 1.

cpfp

Accelerate a stuck transaction by spending one of its outputs at a higher fee rate (Child-Pays-For-Parent).

bk cpfp  --json
bk cpfp  --fee-rate 30 --json
bk cpfp  --urgent --json

{
  "ok": true,
  "data": {
    "parent_txid": "abc123...",
    "child_txid": "def456...",
    "fee_rate_sat_per_vb": 30,
    "urgent": false
  }
}

fee_rate_sat_per_vb is null when neither --fee-rate nor --urgent is set.

ArgDefaultDescription
requiredTXID of the parent transaction to accelerate
--fee-rate autoExplicit fee rate for the child transaction
--urgentoffAutomatically compute a high fee rate to confirm next block
On failure (invalid txid, no spendable output found): exits with code 1.

history

List recent transactions, newest first.

bk history --limit 5 --type send --json

{
  "ok": true,
  "data": [
    {
      "type": "send",
      "amount_sat": 5000,
      "fee_sat": 3,
      "status": "complete",
      "timestamp": "2026-02-15 12:00:00",
      "description": "coffee"
    }
  ]
}
ArgDefaultDescription
--limit 20Number of entries
--type recv>allFilter by direction
Status values: complete, 待处理, 失败 类型 values: 发送, recv

Lightning Payments

invoice

Generate a BOLT 11 invoice to receive payment.

bk invoice 5000 --description "agent service" --json

{
  "ok": true,
  "data": {
    "bolt11": "lnbc50u1p...",
    "payment_hash": "a1b2c3d4e5f6...",
    "amount_sat": 5000,
    "description": "agent service",
    "expires_at": "2026-02-15T14:30:00+00:00"
  }
}
ArgDefaultDescription
requiredAmount in satoshis
--description ""Invoice memo
--expiry 3600Invoice expiry in seconds
--waitoffBlock until payment received
--timeout 300Timeout when using --wait
--qroffDisplay invoice as QR code in terminal (human output only)
Two-phase 输出 带有 --wait: 第一个 prints invoice envelope 上面, 然后 blocks. 当...时 payment arrives, prints 第二个 envelope 到 stdout:

{
  "ok": true,
  "data": {
    "status": "received",
    "amount_sat": 5000,
    "payment_hash": "a1b2c3d4e5f6..."
  }
}

If timeout expires, exits with code 2 (network error). Always use --listen with --wait so the payer can connect.

pay

Pay a BOLT 11 invoice, LNURL, or Lightning Address. Polls until success, failure, or timeout.

bk pay lnbc50u1p... --json
bk pay lnurl1dp68gurn... --json

{
  "ok": true,
  "data": {
    "status": "success",
    "amount_sat": 5000,
    "fee_sat": 3,
    "payment_hash": "a1b2c3d4e5f6...",
    "preimage": "1a2b3c4d5e6f..."
  }
}
ArgDefaultDescription
requiredBOLT 11 invoice, LNURL, or Lightning Address
--max-fee unlimitedMaximum routing fee in satoshis
--timeout 60Payment timeout
LNURL/Lightning Address support: pay accepts LNURL (lnurl1...) 和 resolves 到 BOLT11 invoice. 对于 LNURL-pay 带有 变量 amounts (在哪里 min_sendable != max_sendable), CLI currently requires fixed-amount LNURL. Lightning Address (用户@domain.tld) requires --amount 标志 哪个 不 尚未 implemented — 使用 BOLT11 invoice 代替.

On failure: exits with code 1 ("Payment failed"). On timeout: exits with code 2.

withdraw

Withdraw from an LNURL-withdraw endpoint. Creates an invoice and submits it to the LNURL service.

bk withdraw lnurl1dp68gurn... --json
bk withdraw lnurl1dp68gurn... --amount 10000 --json

{
  "ok": true,
  "data": {
    "status": "submitted",
    "amount_sat": 10000,
    "bolt11": "lnbc100u1p..."
  }
}
ArgDefaultDescription
requiredLNURL-withdraw bech32 string
--amount max withdrawableAmount in satoshis

Channels

打开-channel

Open a Lightning channel to a peer. Requires on-chain funds.

bk open-channel 02ab...@127.0.0.1:9735 100000 --json

{
  "ok": true,
  "data": {
    "channel_id": "12345678901234567890",
    "peer": "02ab...",
    "amount_sats": 100000
  }
}
ArgDescription
Peer in pubkey@host:port format
Channel capacity in satoshis
--push Give the peer initial balance

关闭-channel

Close a Lightning channel. Get channel_id and peer from list-channels.

bk close-channel 12345678901234567890 02ab... --json

{
  "ok": true,
  "data": {
    "channel_id": "12345678901234567890",
    "status": "closing"
  }
}
ArgDescription
Channel ID (decimal, from list-channels)
Counterparty node public key
--forceForce close (use when peer is unresponsive)
Status values: closing (cooperative), force_closing

列表-channels

List all Lightning channels with capacity, balances, and status.

bk list-channels --json

{
  "ok": true,
  "data": [
    {
      "channel_id": "12345678901234567890",
      "peer": "02ab...",
      "capacity_sats": 500000,
      "local_balance_msat": 250000000,
      "remote_balance_msat": 250000000,
      "is_usable": true,
      "is_channel_ready": true,
      "is_outbound": false
    }
  ]
}

Note: balances are in millisatoshis. Divide by 1000 for satoshis.

LSP (Blocktank Liquidity)

Use the Blocktank LSP to get inbound Lightning liquidity without manually finding peers.

lsp info

Get LSP service info: available nodes, channel limits, fee rates.

bk lsp info --json

{
  "ok": true,
  "data": {
    "nodes": [
      {
        "alias": "blocktank-lsp",
        "pubkey": "02abc...",
        "connection_strings": ["02abc...@1.2.3.4:9735"]
      }
    ],
    "min_channel_size_sats": 20000,
    "max_channel_size_sats": 5000000,
    "min_expiry_weeks": 2,
    "max_expiry_weeks": 52,
    "network": "Mainnet",
    "fee_rates_fast": 10,
    "fee_rates_mid": 5,
    "fee_rates_slow": 1
  }
}

lsp estimate-fee

Estimate the cost of a channel order before creating it.

bk lsp estimate-fee 500000 --json

{
  "ok": true,
  "data": {
    "fee_sats": 500,
    "network_fee_sats": 300,
    "service_fee_sats": 200
  }
}
ArgDefaultDescription
requiredInbound liquidity amount
--expiry 6Channel expiry in weeks
--client-balance-sats 0Outbound liquidity (your side)

lsp 创建-order

Create a channel order. Returns payment details.

bk lsp create-order 500000 --json

{
  "ok": true,
  "data": {
    "order_id": "ord-abc123...",
    "state": "Created",
    "fee_sats": 500,
    "lsp_balance_sats": 500000,
    "client_balance_sats": 0,
    "payment_address": "bc1q...",
    "payment_bolt11": "lnbc...",
    "order_expires_at": "2026-03-01T00:00:00Z"
  }
}
ArgDefaultDescription
requiredInbound liquidity amount
--expiry 6Channel expiry in weeks
--client-balance-sats 0Your outbound balance
--zero-confoffEnable zero-conf channel
After creating, pay to payment_address (on-chain) or payment_bolt11 (Lightning). Then poll get-order until state becomes Paid.

lsp 获取-order

Check the status of an order.

bk lsp get-order ord-abc123 --json

{
  "ok": true,
  "data": {
    "order_id": "ord-abc123...",
    "state": "Open",
    "state2": "Paid",
    "fee_sats": 500,
    "lsp_balance_sats": 500000,
    "client_balance_sats": 0,
    "channel_expiry_weeks": 6,
    "channel_state": "Opening",
    "funding_tx": "abc123def...",
    "payment_state": "Paid",
    "order_expires_at": "2026-03-01T00:00:00Z",
    "created_at": "2026-02-17T00:00:00Z"
  }
}

channel_state and funding_tx are null until the channel is being opened.

State enum values 对于 lsp 获取-order:

FieldValuesDescription
stateCreated, Open, Expired, ClosedLegacy order state
state2Created, Paid, Executed, ExpiredCurrent order state (prefer this)
channel_stateOpening, Open, ClosedChannel lifecycle state
payment_stateCreated, Paid, Refunded, RefundAvailable, CanceledPayment lifecycle state
Poll state2 for order progress: Created → Paid (after on-chain payment) → Executed (channel opened).

lsp 打开-channel

Tell Blocktank to open a channel to your node. The order must be in Paid state. Requires --listen so Blocktank can connect.

bk lsp open-channel ord-abc123 --listen 9735 --json

{
  "ok": true,
  "data": {
    "order_id": "ord-abc123...",
    "state": "Open",
    "channel_state": "Opening",
    "funding_tx": "abc123def..."
  }
}

Messaging (Pubky Encrypted)

End-to-end encrypted messaging via the Pubky network. Identity is created during init.

消息 whoami

Print your Pubky messaging ID. Does not require network access.

bk message whoami --json

{
  "ok": true,
  "data": {
    "pubky_id": "8pinxrz9tuxfz3qo5gkhdebuhtq6mrimh3matdncsrsno7kg45mo"
  }
}

消息 发送

Send an encrypted message to a peer.

bk message send 8pin...xyz '{"type":"invoice","bolt11":"lnbc...","amount_sats":5000,"description":"service"}' --json

{
  "ok": true,
  "data": {
    "message_id": "abc-123-def",
    "recipient": "8pin...xyz"
  }
}
ArgDescription
Recipient's Pubky ID
Message content (plain text or JSON string)

消息 读取

Read the full conversation with a peer, sorted by timestamp.

bk message read 8pin...xyz --json

{
  "ok": true,
  "data": {
    "messages": [
      {
        "sender": "8pin...abc",
        "content": "{\"type\":\"invoice\",\"bolt11\":\"lnbc...\",\"amount_sats\":5000,\"description\":\"service\"}",
        "timestamp": 1708000000,
        "verified": true
      }
    ]
  }
}
FieldDescription
senderPubky ID of the message author
contentMessage text (may contain JSON -- parse it)
timestampUnix timestamp in seconds
verifiedtrue if cryptographic signature verified

消息 listen

Poll for new messages from a peer. Streams one envelope per line to stdout as messages arrive.

bk message listen 8pin...xyz --interval 3 --timeout 120 --json

Each new message is printed as a single-line envelope:

{"ok":true,"data":{"sender":"8pin...abc","content":"hello","timestamp":1708000001,"verified":true}}
ArgDefaultDescription
requiredPeer's Pubky ID
--interval 3Poll interval
--timeout 0 (forever)Stop after this many seconds
Status messages go to stderr. Only message JSON goes to stdout.

Agent Integration

Daemon HTTP API

When the daemon is running (bk start), all commands proxy through an HTTP API on localhost:3457 (configurable via --port). The API uses HTTP Basic Auth with auto-generated credentials.

Authentication: HTTP Basic Auth (bitkit:<密码>). 密码 auto-generated 在...上 第一个 bk 开始 和 stored 在...中 /api-密码.

Endpoints:

MethodPathDescription
GET/healthHealth check (no auth)
GET/balanceWallet balance
GET/infoNode info
GET/history?limit=20&type=sendPayment history
GET/channelsList channels
GET/utxosList UTXOs
POST/addressGenerate receive address
POST/sendSend on-chain
POST/invoiceCreate Lightning invoice
POST/payPay Lightning invoice
POST/estimate-feeEstimate on-chain fee
POST/bump-feeRBF fee bump
POST/cpfpCPFP acceleration
POST/channels/openOpen channel
POST/channels/closeClose channel
GET/eventsWebSocket event stream
All responses use the same JSON envelope as CLI --json output: {"ok": true, "data": {...}}.

POST 请求 Body Schemas:

POST /address: 

{ "address_type": "native-segwit" }
address_type is optional. Values: legacy, nested-segwit, native-segwit, taproot.

POST /send: 

{ "address": "bc1q...", "amount_sats": 50000, "drain": false, "fee_rate": 5, "utxos": ["txid:0"] }
amount_sats is required unless drain is true. fee_rate, drain, utxos are optional.

POST /estimate-fee: 

{ "address": "bc1q...", "amount_sats": 50000, "fee_rate": 5, "utxos": ["txid:0"] }
fee_rate and utxos are optional.

POST /bump-fee: 

{ "txid": "abc123...", "fee_rate": 20 }
Both fields required.

POST /cpfp: 

{ "txid": "abc123...", "fee_rate": 30, "urgent": false }
txid is required. fee_rate and urgent are optional (mutually exclusive).

POST /invoice: 

{ "amount_sats": 5000, "description": "agent service", "expiry": 3600 }
amount_sats is required. description and expiry are optional.

POST /pay: 

{ "bolt11": "lnbc50u1p...", "max_fee": 100, "timeout": 60 }
bolt11 is required. max_fee and timeout are optional.

POST /channels/open: 

{ "peer": "02ab...@127.0.0.1:9735", "amount_sats": 100000, "push_sats": 0 }
peer and amount_sats are required. push_sats is optional.

POST /channels/close: 

{ "channel_id": "12345678901234567890", "peer": "02ab...", "force": false }
channel_id and peer are required. force is optional (default false).

Webhooks

Configure in ~/.bitkit//config.toml:

webhook_url = "https://your-agent.example.com/webhook"
webhook_secret = "your-hmac-secret"

Events 和 Payloads:

Each webhook POST body contains event, data, and timestamp (Unix ms):

payment_received — Lightning payment received: 

{
  "event": "payment_received",
  "data": { "payment_hash": "abc...", "amount_sat": 1000 },
  "timestamp": 1708444800000
}

payment_sent — Outbound Lightning payment succeeded: 

{
  "event": "payment_sent",
  "data": { "payment_hash": "abc...", "amount_sat": 5000, "fee_sat": 3 },
  "timestamp": 1708444800000
}

payment_failed — Outbound Lightning payment 失败: 

{
  "event": "payment_failed",
  "data": { "payment_hash": "abc...", "reason": "RouteNotFound" },
  "timestamp": 1708444800000
}
payment_hash and reason are nullable (may be null).

channel_ready — Channel fully 打开 和 usable: 

{
  "event": "channel_ready",
  "data": { "channel_id": "4242...", "counterparty_node_id": "02ab..." },
  "timestamp": 1708444800000
}
counterparty_node_id is nullable.

channel_closed — Channel closed: 

{
  "event": "channel_closed",
  "data": { "channel_id": "4242...", "counterparty_node_id": "02ab...", "reason": "CooperativeClosure" },
  "timestamp": 1708444800000
}
counterparty_node_id and reason are nullable.

Signature: X-Bitkit-Signature: hmac-sha256= 页头 (HMAC-SHA256 的 body 使用 webhook_secret).

重试: 3 attempts 带有 exponential backoff (1s, 4s, 16s).

WebSocket Events

Connect to ws://localhost:3457/events with Basic Auth. Receives the same events as webhooks in real-time as JSON text frames.

# Example with websocat
websocat ws://localhost:3457/events -H "Authorization: Basic $(echo -n 'bitkit:PASSWORD' | base64)"

Frame 格式: 每个 事件 JSON text frame 带有 相同 structure 作为 webhook payloads:

{"event":"payment_received","data":{"payment_hash":"abc...","amount_sat":1000},"timestamp":1708444800000}

Behavior:

  • Server sends WebSocket Ping every 10 seconds 作为 keepalive
  • 如果 client falls 后面, server sends warning frame: {"warning":"missed 3 events"}
  • 连接 closes 当...时: client sends 关闭 frame, 任何 WebSocket 错误 occurs, 或 daemon shuts down
  • 否 client-到-server messages expected (接收-仅 stream)

Configuration Reference

Config file: ~/.bitkit//config.toml (created by bk init). All fields are under [node]:

[node]
network = "mainnet"                    # "mainnet" or "regtest"
chain_source = "esplora"               # "esplora" or "electrum"
esplora_url = "https://blockstream.info/api"
electrum_url = ""                      # used when chain_source = "electrum"
rgs_url = "https://rapidsync.lightningdevkit.org/snapshot"
blocktank_url = "https://api1.blocktank.to/api"
webhook_url = ""                       # POST target for events
webhook_secret = ""                    # HMAC-SHA256 signing key
auto_liquidity = false                 # enable background inbound capacity monitor
auto_liquidity_threshold_sats = 100000 # order channel when inbound < this
auto_liquidity_channel_size_sats = 500000  # channel size to order
FieldTypeDefaultDescription
networkstring"mainnet"Bitcoin network
chain_sourcestring"esplora"Chain sync backend: esplora or electrum
esplora_urlstring"https://blockstream.info/api"Esplora API URL
electrum_urlstring""Electrum server URL (regtest: tcp://127.0.0.1:60001)
rgs_urlstring(LDK default)Rapid Gossip Sync URL for Lightning routing graph
blocktank_urlstring"https://api1.blocktank.to/api"Blocktank LSP API URL
webhook_urlstring""Webhook POST target (empty = disabled)
webhook_secretstring""HMAC-SHA256 key for X-Bitkit-Signature header
auto_liquidityboolfalseEnable background inbound capacity monitor
auto_liquidity_threshold_satsu64100000Order channel when inbound capacity drops below this
auto_liquidity_channel_size_satsu64500000Size of auto-ordered channels

Auto-Liquidity

When auto_liquidity = true in config.toml, the daemon monitors inbound channel capacity every 5 minutes. If total inbound capacity drops below auto_liquidity_threshold_sats, it automatically creates a Blocktank channel order for auto_liquidity_channel_size_sats.

Important: auto-created order 仍然 requires 在...上-chain payment 到 payment_address 从 order. daemon 做 不 pay automatically — agent 或 human 必须 fund order.

Workflow:

  • Enable 在...中 配置: auto_liquidity = 真
  • 开始 daemon: bk 开始 --json
  • Monitor 对于 channel_ready events 通过 webhook 或 WebSocket
  • 当...时 Blocktank order created, check bk lsp 获取-order 对于 payment_address
  • Pay order 在...上-chain, 然后 channel opens automatically

API 密码

The daemon HTTP API uses HTTP Basic Auth. The password is auto-generated on first bk start.

Location: /api-密码 (e.g., ~/.bitkit/api-密码) 格式: 32 random bytes encoded 作为 64 hex characters Permissions: File mode 0600 (owner 读取/写入 仅)

# Read the password
cat ~/.bitkit/api-password
# Use with curl
curl -u "bitkit:$(cat ~/.bitkit/api-password)" http://localhost:3457/balance
# Use with WebSocket
websocat ws://localhost:3457/events -H "Authorization: Basic $(echo -n "bitkit:$(cat ~/.bitkit/api-password)" | base64)"

The password persists across daemon restarts. Delete the file to force regeneration on next bk start.

错误 Handling

Exit Codes

CodeNameCommon CausesRecovery
0Success----
1User errorBad input, missing wallet, invalid invoice, expired invoiceFix input and retry
2Network errorConnection failed, sync timeout, payment timeoutRetry after delay
3Insufficient fundsNot enough on-chain or Lightning balanceFund wallet or open channel

错误 Envelope

When --json is used and an error occurs, a structured error envelope is written to stderr:

{
  "ok": false,
  "error": "Invalid invoice: ...",
  "code": 1
}

Bash Pattern

OUTPUT=$(bk pay "$BOLT11" --json 2>/dev/null)
EXIT_CODE=$?
case $EXIT_CODE in
  0) echo "Success: $(echo "$OUTPUT" | jq -r '.data.payment_hash')" ;;
  1) echo "Bad input -- check the invoice" >&2; exit 1 ;;
  2) echo "Network issue -- retrying..." >&2; sleep 5; bk pay "$BOLT11" --json ;;
  3) echo "Insufficient funds" >&2; exit 3 ;;
esac

Important: Errors 打印 到 stderr (作为 JSON envelope 当...时 --json used). 成功 输出 prints 到 stdout. Always capture them separately.

Multi-Wallet Pattern

Run multiple independent agent wallets by using separate data directories.

export BITKIT_DIR="/tmp/agent-${SESSION_ID}"
bk init --no-password --json
bk address --json
# ... each agent operates independently

Or use the --dir flag:

bk --dir /tmp/agent-alice init --no-password --json
bk --dir /tmp/agent-bob init --no-password --json

Each directory gets its own seed, node identity, Pubky ID, and channel state. Agents sharing a machine can run concurrently with different --dir values.

输入框 Validation Reference

FormatPatternExample
Node pubkey66-char hex (compressed secp256k1)02abc123...
Peer addresspubkey@host:port02abc...@127.0.0.1:9735
Transaction ID64-char hex4a5e1e4baab89f3a...
Outpointtxid:vout (decimal vout)4a5e1e4b...:0
Channel IDDecimal u12812345678901234567890
Bitcoin addressNetwork-validated bech32/base58bc1q..., bcrt1q...
BOLT11 invoicelnbc... or lnbcrt... prefixlnbc50u1p...
LNURLBech32 with lnurl HRPlnurl1dp68gurn...
Lightning Addressuser@domain.tldagent@pay.bitkit.to
Pubky ID52-char z-base-328pinxrz9tux...45mo
Fee ratePositive integer (sat/vb)5
AmountNon-negative integer (satoshis)50000
All validation errors exit with code 1 and include a descriptive error message.

Messaging Workflow

Agent 消息 Protocol

Agents communicate structured data by sending JSON strings as message content. The convention uses a type field to distinguish message kinds:

Invoice 请求:

{
  "type": "invoice",
  "bolt11": "lnbc50u1p...",
  "amount_sats": 5000,
  "description": "data analysis service"
}

Payment confirmation:

{
  "type": "payment_confirmation",
  "payment_hash": "a1b2c3d4e5f6...",
  "amount_sats": 5000
}

Workflow: Discover, 消息, Pay

# 1. Get your own Pubky ID to share with other agents
MY_ID=$(bk message whoami --json | jq -r '.data.pubky_id')
# 2. Send a message to another agent
bk message send "$PEER_PUBKY" "Hello, I need data analysis" --json
# 3. Listen for their reply (they'll send an invoice)
bk message listen "$PEER_PUBKY" --timeout 120 --json | while IFS= read -r MSG; do
  TYPE=$(echo "$MSG" | jq -r '.data.content' | jq -r '.type // empty' 2>/dev/null)
  if [ "$TYPE" = "invoice" ]; then
    BOLT11=$(echo "$MSG" | jq -r '.data.content' | jq -r '.bolt11')
    echo "Received invoice: $BOLT11"
    break
  fi
done
# 4. Pay the invoice
bk pay "$BOLT11" --json

End-到-End: Pay 另一个 Agent

Complete flow where Agent A requests a service, Agent B invoices for it, Agent A pays, and Agent B confirms.

Agent B (服务 provider)

#!/usr/bin/env bash
set -euo pipefail
export BITKIT_DIR=/tmp/agent-b
# Initialize and share identity
bk init --no-password --json >/dev/null
MY_ID=$(bk message whoami --json | jq -r '.data.pubky_id')
echo "Agent B Pubky ID: $MY_ID"
# Listen for requests from Agent A
bk message listen "$AGENT_A_PUBKY" --timeout 300 --json | while IFS= read -r MSG; do
  CONTENT=$(echo "$MSG" | jq -r '.data.content')
  # Create invoice for the requested service
  INVOICE_JSON=$(bk invoice 5000 --description "data analysis" --json)
  BOLT11=$(echo "$INVOICE_JSON" | jq -r '.data.bolt11')
  # Send invoice to Agent A
  PAYLOAD=$(jq -n --arg b "$BOLT11" '{type:"invoice",bolt11:$b,amount_sats:5000,description:"data analysis"}')
  bk message send "$AGENT_A_PUBKY" "$PAYLOAD" --json
  # Wait for payment
  RECEIVED=$(bk invoice 5000 --description "data analysis" --wait --listen 9735 --json | tail -1)
  HASH=$(echo "$RECEIVED" | jq -r '.data.payment_hash')
  # Confirm payment
  CONFIRM=$(jq -n --arg h "$HASH" '{type:"payment_confirmation",payment_hash:$h,amount_sats:5000}')
  bk message send "$AGENT_A_PUBKY" "$CONFIRM" --json
  break
done

Agent (client)

#!/usr/bin/env bash
set -euo pipefail
export BITKIT_DIR=/tmp/agent-a
# Initialize
bk init --no-password --json >/dev/null
MY_ID=$(bk message whoami --json | jq -r '.data.pubky_id')
# Request service from Agent B
bk message send "$AGENT_B_PUBKY" "Please analyze dataset X" --json
# Wait for invoice
BOLT11=""
bk message listen "$AGENT_B_PUBKY" --timeout 120 --json | while IFS= read -r MSG; do
  TYPE=$(echo "$MSG" | jq -r '.data.content' | jq -r '.type // empty' 2>/dev/null)
  if [ "$TYPE" = "invoice" ]; then
    BOLT11=$(echo "$MSG" | jq -r '.data.content' | jq -r '.bolt11')
    break
  fi
done
# Pay the invoice
PAY_RESULT=$(bk pay "$BOLT11" --json)
echo "Payment status: $(echo "$PAY_RESULT" | jq -r '.data.status')"
echo "Fee paid: $(echo "$PAY_RESULT" | jq -r '.data.fee_sat') sats"
# Wait for confirmation
bk message listen "$AGENT_B_PUBKY" --timeout 60 --json | while IFS= read -r MSG; do
  TYPE=$(echo "$MSG" | jq -r '.data.content' | jq -r '.type // empty' 2>/dev/null)
  if [ "$TYPE" = "payment_confirmation" ]; then
    echo "Payment confirmed by Agent B"
    break
  fi
done

Security & Privacy

Trust 模型: Fully self-custodial. BIP39 seed never leaves local machine. 否 telemetry, analytics, 或 tracking 的 任何 kind.

External endpoints contacted:

EndpointPurposeData SentConfigurable
Esplora serverChain sync (mainnet)Transaction queriesYes (esplora_url)
Electrum serverChain sync (regtest)Transaction queriesYes (electrum_url)
RGS serverLightning gossip syncNone (download only)Yes (rgs_url)
Blocktank APILSP channel ordersNode ID, order paramsYes (blocktank_url)
LNURL servicePay/withdraw resolutionAmount, callback URLUser-initiated only
Pubky DHTEncrypted messagingE2E encrypted payloadsBuilt-in
Webhook URLEvent notificationsPayment/channel eventsYes (webhook_url)
Seed storage: Custom binary 格式 带有 magic bytes (BKIT), version byte, 和 encrypted (AES-256-GCM + Argon2id KDF) 或 plaintext 标志. File: ~/.bitkit//seed.enc.

API 密码: Auto-generated 32-byte random hex, stored 带有 0600 permissions. 仅 used 对于 local daemon HTTP API access.

LSP Workflow: Fresh Wallet 到 Lightning-就绪

From a brand new wallet to being able to send and receive Lightning payments:

# 1. Create wallet
bk init --no-password --json
# 2. Get on-chain address
ADDRESS=$(bk address --json | jq -r '.data.address')
echo "Fund this address: $ADDRESS"
# 3. (Fund the address externally, wait for confirmation)
# 4. Estimate channel fees
bk lsp estimate-fee 500000 --json
# 5. Create channel order
ORDER_ID=$(bk lsp create-order 500000 --json | jq -r '.data.order_id')
# 6. Pay the order on-chain (the payment_address from create-order)
# ... or wait for on-chain funding to cover it
# 7. Poll until order is paid
while true; do
  STATE=$(bk lsp get-order "$ORDER_ID" --json | jq -r '.data.state2')
  [ "$STATE" = "Paid" ] && break
  sleep 10
done
# 8. Open the channel
bk lsp open-channel "$ORDER_ID" --listen 9735 --json
# 9. Verify channel is active
bk list-channels --json | jq '.data[0].is_usable'
# Now ready to send and receive Lightning payments

Tags

bitcoin, lightning, payment, invoice, self-custody, wallet, CLI, agent, LNURL, lightning-address, BOLT11, LSP, lowest-fees, daemon, webhooks, websocket, encrypted-messaging, on-chain, channels, liquidity

数据来源：ClawHub ↗ · 中文优化：龙虾技能库
OpenClaw 技能定制 / 插件定制 / 私有工作流定制

免费技能或插件可能存在安全风险，如需更匹配、更安全的方案，建议联系付费定制

了解定制服务