bitkit-cli -- AI Agent Skill

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 or bk (identical alias)
Always use: --json flag on every invocation for parseable output.

JSON Envelope

All --json output uses a consistent envelope:

Success (stdout):
CODEBLOCK0

Error (stderr):
CODEBLOCK1

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

Quick Start

CODEBLOCK2

Daemon Mode

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

CODEBLOCK3

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

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

CODEBLOCK4

CODEBLOCK5

Arg	Default	Description
INLINECODE8	INLINECODE9	HTTP API port

INLINECODE10 is "started" or "already_running".

stop

Stop the running daemon.

CODEBLOCK6

CODEBLOCK7

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

status

Check daemon status.

CODEBLOCK8

CODEBLOCK9

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

Global Flags

Flag	Env Variable	Default	Description
INLINECODE18	--	off	Machine-readable JSON to stdout
INLINECODE19

BITKIT_DIR | ~/.bitkit/ | Wallet data directory | | --network <net> | BITKIT_NETWORK | mainnet | mainnet or regtest | | --listen <port> | BITKIT_LISTEN | off | P2P listen port on 0.0.0.0:<port> | | --password <pw> | BITKIT_PASSWORD | -- | Wallet password (for encrypted seeds) |

Command Reference

Wallet

init

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

CODEBLOCK10

CODEBLOCK11

Arg	Required	Description
INLINECODE33	one of	Store seed as plaintext (for agents)
INLINECODE34

one of | Encrypt seed with AES-256-GCM + Argon2id |

info

Show node status, channel counts, sync state.

CODEBLOCK12

CODEBLOCK13

balance

Show Lightning and on-chain balances in satoshis.

CODEBLOCK14

CODEBLOCK15

• - onchain_sats -- spendable on-chain balance
• INLINECODE38 -- all on-chain funds including reserved
• INLINECODE39 -- sats reserved for anchor channel fees
• INLINECODE40 -- funds sweeping from closed channels (not yet spendable)
• INLINECODE41 -- array of sweep entries with amount_sats, status, spending_txid, INLINECODE45

Arg	Description
INLINECODE46	Display in BTC instead of sats (human output only)

config

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

CODEBLOCK16

CODEBLOCK17

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.

CODEBLOCK18

Generate address:
CODEBLOCK19

Validate address (--validate):
CODEBLOCK20

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

Arg	Default	Description
INLINECODE59	INLINECODE60	Address type: legacy, nested-segwit, native-segwit, INLINECODE64
INLINECODE65

-- | Validate <addr> for the current network; no node start needed |
| --qr | off | Display address as QR code in terminal (human output only) |

send

Send bitcoin on-chain to an address.

CODEBLOCK21

CODEBLOCK22

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

Arg	Default	Description
INLINECODE75	required	Destination Bitcoin address
INLINECODE76

-- | Amount in satoshis (omit with --drain) |
| --drain | off | Send all spendable funds (mutually exclusive with --utxo) |
| --fee-rate <sat/vb> | auto | Fee rate in sat/vb |
| --utxo <txid:vout> | -- | Spend a specific UTXO (repeatable; incompatible with --drain) |

list-utxos

List all spendable UTXOs in the on-chain wallet.

CODEBLOCK23

CODEBLOCK24

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.

CODEBLOCK25

CODEBLOCK26

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

Arg	Default	Description
INLINECODE92	required	Destination Bitcoin address
INLINECODE93

required | Amount to send in satoshis |
| --fee-rate <sat/vb> | auto | Override fee rate in sat/vb |
| --utxo <txid:vout> | -- | 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.

CODEBLOCK27

CODEBLOCK28

Arg	Description
INLINECODE97	TXID of the unconfirmed transaction to replace
INLINECODE98

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

CODEBLOCK29

CODEBLOCK30

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

Arg	Default	Description
INLINECODE104	required	TXID of the parent transaction to accelerate
INLINECODE105

auto | Explicit fee rate for the child transaction |
| --urgent | off | Automatically 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.

CODEBLOCK31

CODEBLOCK32

Arg	Default	Description
INLINECODE108	INLINECODE109	Number of entries
INLINECODE110

all | Filter by direction |

Status values: complete, pending, failed
Type values: send, INLINECODE115

Lightning Payments

invoice

Generate a BOLT 11 invoice to receive payment.

CODEBLOCK33

CODEBLOCK34

Arg	Default	Description
INLINECODE117	required	Amount in satoshis
INLINECODE118

"" | Invoice memo |
| --expiry <secs> | 3600 | Invoice expiry in seconds |
| --wait | off | Block until payment received |
| --timeout <secs> | 300 | Timeout when using --wait |
| --qr | off | Display invoice as QR code in terminal (human output only) |

Two-phase output with --wait: First prints the invoice envelope above, then blocks. When payment arrives, prints a second envelope to stdout:

CODEBLOCK35

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

pay

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

CODEBLOCK36

CODEBLOCK37

Arg	Default	Description
INLINECODE131	required	BOLT 11 invoice, LNURL, or Lightning Address
INLINECODE132

unlimited | Maximum routing fee in satoshis |
| --timeout <secs> | 60 | Payment timeout |

LNURL/Lightning Address support: pay accepts LNURL (lnurl1...) and resolves to a BOLT11 invoice. For LNURL-pay with variable amounts (where min_sendable != max_sendable), the CLI currently requires a fixed-amount LNURL. Lightning Address (user@domain.tld) requires a --amount flag which is not yet implemented — use a BOLT11 invoice instead.

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.

CODEBLOCK38

CODEBLOCK39

Arg	Default	Description
INLINECODE141	required	LNURL-withdraw bech32 string
INLINECODE142

max withdrawable | Amount in satoshis |

Channels

open-channel

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

CODEBLOCK40

CODEBLOCK41

Arg	Description
INLINECODE144	Peer in pubkey@host:port format
INLINECODE146

Channel capacity in satoshis |
| --push <sats> | Give the peer initial balance |

close-channel

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

CODEBLOCK42

CODEBLOCK43

Arg	Description
INLINECODE152	Channel ID (decimal, from list-channels)
INLINECODE154

Counterparty node public key |
| --force | Force close (use when peer is unresponsive) |

Status values: closing (cooperative), INLINECODE157

list-channels

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

CODEBLOCK44

CODEBLOCK45

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.

CODEBLOCK46

CODEBLOCK47

lsp estimate-fee

Estimate the cost of a channel order before creating it.

CODEBLOCK48

CODEBLOCK49

Arg	Default	Description
INLINECODE161	required	Inbound liquidity amount
INLINECODE162

6 | Channel expiry in weeks |
| --client-balance-sats <sats> | 0 | Outbound liquidity (your side) |

lsp create-order

Create a channel order. Returns payment details.

CODEBLOCK50

CODEBLOCK51

Arg	Default	Description
INLINECODE167	required	Inbound liquidity amount
INLINECODE168

6 | Channel expiry in weeks |
| --client-balance-sats <sats> | 0 | Your outbound balance |
| --zero-conf | off | Enable zero-conf channel |

After creating, pay to payment_address (on-chain) or payment_bolt11 (Lightning). Then poll get-order until state becomes Paid.

lsp get-order

Check the status of an order.

CODEBLOCK52

CODEBLOCK53

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

State enum values for lsp get-order:

Field	Values	Description
INLINECODE182	INLINECODE183, Open, Expired, INLINECODE186	Legacy order state
INLINECODE187

Created, Paid, Executed, Expired | Current order state (prefer this) |
| channel_state | Opening, Open, Closed | Channel lifecycle state |
| payment_state | Created, Paid, Refunded, RefundAvailable, Canceled | Payment lifecycle state |

Poll state2 for order progress: Created → Paid (after on-chain payment) → Executed (channel opened).

lsp open-channel

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

CODEBLOCK54

CODEBLOCK55

Messaging (Pubky Encrypted)

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

message whoami

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

CODEBLOCK56

CODEBLOCK57

message send

Send an encrypted message to a peer.

CODEBLOCK58

CODEBLOCK59

Arg	Description
INLINECODE212	Recipient's Pubky ID
INLINECODE213

Message content (plain text or JSON string) |

message read

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

CODEBLOCK60

CODEBLOCK61

Field	Description
INLINECODE215	Pubky ID of the message author
INLINECODE216

Message text (may contain JSON -- parse it) |
| timestamp | Unix timestamp in seconds |
| verified | true if cryptographic signature verified |

message listen

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

CODEBLOCK62

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

CODEBLOCK63

Arg	Default	Description
INLINECODE221	required	Peer's Pubky ID
INLINECODE222

3 | Poll interval |
| --timeout <secs> | 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:<password>). Password is auto-generated on first bk start and stored in <wallet_dir>/api-password.

Endpoints:

Method	Path	Description
GET	INLINECODE232	Health check (no auth)
GET

/balance | Wallet balance |
| GET | /info | Node info |
| GET | /history?limit=20&type=send | Payment history |
| GET | /channels | List channels |
| GET | /utxos | List UTXOs |
| POST | /address | Generate receive address |
| POST | /send | Send on-chain |
| POST | /invoice | Create Lightning invoice |
| POST | /pay | Pay Lightning invoice |
| POST | /estimate-fee | Estimate on-chain fee |
| POST | /bump-fee | RBF fee bump |
| POST | /cpfp | CPFP acceleration |
| POST | /channels/open | Open channel |
| POST | /channels/close | Close channel |
| GET | /events | WebSocket event stream |

All responses use the same JSON envelope as CLI --json output: {"ok": true, "data": {...}}.

POST Request Body Schemas:

INLINECODE250:

{ "address_type": "native-segwit" }

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

INLINECODE256:

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

INLINECODE263:

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

fee_rate and utxos are optional.

INLINECODE266:

{ "txid": "abc123...", "fee_rate": 20 }

Both fields required.

INLINECODE267:

{ "txid": "abc123...", "fee_rate": 30, "urgent": false }

txid is required. fee_rate and urgent are optional (mutually exclusive).

INLINECODE271:

{ "amount_sats": 5000, "description": "agent service", "expiry": 3600 }

amount_sats is required. description and expiry are optional.

INLINECODE275:

{ "bolt11": "lnbc50u1p...", "max_fee": 100, "timeout": 60 }

bolt11 is required. max_fee and timeout are optional.

INLINECODE279:

{ "peer": "02ab...@127.0.0.1:9735", "amount_sats": 100000, "push_sats": 0 }

peer and amount_sats are required. push_sats is optional.

INLINECODE283:

{ "channel_id": "12345678901234567890", "peer": "02ab...", "force": false }

channel_id and peer are required. force is optional (default false).

Webhooks

Configure in ~/.bitkit/<network>/config.toml:

CODEBLOCK73

Events and Payloads:

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

payment_received — Lightning payment received:
CODEBLOCK74

payment_sent — Outbound Lightning payment succeeded:
CODEBLOCK75

payment_failed — Outbound Lightning payment failed:

{
  "event": "payment_failed",
  "data": { "payment_hash": "abc...", "reason": "RouteNotFound" },
  "timestamp": 1708444800000
}

payment_hash and reason are nullable (may be null).

channel_ready — Channel fully open and 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=<hex> header (HMAC-SHA256 of body using webhook_secret).

Retry: 3 attempts with 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.

CODEBLOCK79

Frame format: Each event is a JSON text frame with the same structure as webhook payloads:

CODEBLOCK80

Behavior:

• - Server sends a WebSocket Ping every 10 seconds as a keepalive
• If the client falls behind, the server sends a warning frame: INLINECODE306
• Connection closes when: client sends a Close frame, any WebSocket error occurs, or the daemon shuts down
• No client-to-server messages are expected (receive-only stream)

Configuration Reference

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

CODEBLOCK81

Field	Type	Default	Description
INLINECODE310	string	INLINECODE311	Bitcoin network
INLINECODE312

string | "esplora" | Chain sync backend: esplora or electrum |
| esplora_url | string | "https://blockstream.info/api" | Esplora API URL |
| electrum_url | string | "" | Electrum server URL (regtest: tcp://127.0.0.1:60001) |
| rgs_url | string | (LDK default) | Rapid Gossip Sync URL for Lightning routing graph |
| blocktank_url | string | "https://api1.blocktank.to/api" | Blocktank LSP API URL |
| webhook_url | string | "" | Webhook POST target (empty = disabled) |
| webhook_secret | string | "" | HMAC-SHA256 key for X-Bitkit-Signature header |
| auto_liquidity | bool | false | Enable background inbound capacity monitor |
| auto_liquidity_threshold_sats | u64 | 100000 | Order channel when inbound capacity drops below this |
| auto_liquidity_channel_size_sats | u64 | 500000 | Size 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: The auto-created order still requires on-chain payment to payment_address from the order. The daemon does not pay automatically — an agent or human must fund the order.

Workflow:

1. 1. Enable in config: INLINECODE340
2. Start daemon: INLINECODE341
3. Monitor for channel_ready events via webhook or WebSocket
4. When a Blocktank order is created, check bk lsp get-order <id> for the INLINECODE344
5. Pay the order on-chain, then the channel opens automatically

API Password

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

Location: <wallet_dir>/api-password (e.g., ~/.bitkit/api-password)
Format: 32 random bytes encoded as 64 hex characters
Permissions: File mode 0600 (owner read/write only)

CODEBLOCK82

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

Error Handling

Exit Codes

Code	Name	Common Causes	Recovery
0	Success	--	--
1

User error | Bad input, missing wallet, invalid invoice, expired invoice | Fix input and retry | | 2 | Network error | Connection failed, sync timeout, payment timeout | Retry after delay | | 3 | Insufficient funds | Not enough on-chain or Lightning balance | Fund wallet or open channel |

Error Envelope

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

CODEBLOCK83

Bash Pattern

CODEBLOCK84

Important: Errors print to stderr (as JSON envelope when --json is used). Success output prints to stdout. Always capture them separately.

Multi-Wallet Pattern

Run multiple independent agent wallets by using separate data directories.

CODEBLOCK85

Or use the --dir flag:

CODEBLOCK86

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

Input Validation Reference

Format	Pattern	Example
Node pubkey	66-char hex (compressed secp256k1)	INLINECODE354
Peer address

pubkey@host:port | 02abc...@127.0.0.1:9735 | | Transaction ID | 64-char hex | 4a5e1e4baab89f3a... | | Outpoint | txid:vout (decimal vout) | 4a5e1e4b...:0 | | Channel ID | Decimal u128 | 12345678901234567890 | | Bitcoin address | Network-validated bech32/base58 | bc1q..., bcrt1q... | | BOLT11 invoice | lnbc... or lnbcrt... prefix | lnbc50u1p... | | LNURL | Bech32 with lnurl HRP | lnurl1dp68gurn... | | Lightning Address | user@domain.tld | agent@pay.bitkit.to | | Pubky ID | 52-char z-base-32 | 8pinxrz9tux...45mo | | Fee rate | Positive integer (sat/vb) | 5 | | Amount | Non-negative integer (satoshis) | 50000 |

All validation errors exit with code 1 and include a descriptive error message.

Messaging Workflow

Agent Message Protocol

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

Invoice request:

CODEBLOCK87

Payment confirmation:

CODEBLOCK88

Workflow: Discover, Message, Pay

CODEBLOCK89

End-to-End: Pay Another Agent

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

Agent B (service provider)

CODEBLOCK90

Agent A (client)

CODEBLOCK91

Security & Privacy

Trust model: Fully self-custodial. The BIP39 seed never leaves the local machine. No telemetry, analytics, or tracking of any kind.

External endpoints contacted:

Endpoint	Purpose	Data Sent	Configurable
Esplora server	Chain sync (mainnet)	Transaction queries	Yes (esplora_url)
Electrum server

Chain sync (regtest) | Transaction queries | Yes (electrum_url) |
| RGS server | Lightning gossip sync | None (download only) | Yes (rgs_url) |
| Blocktank API | LSP channel orders | Node ID, order params | Yes (blocktank_url) |
| LNURL service | Pay/withdraw resolution | Amount, callback URL | User-initiated only |
| Pubky DHT | Encrypted messaging | E2E encrypted payloads | Built-in |
| Webhook URL | Event notifications | Payment/channel events | Yes (webhook_url) |

Seed storage: Custom binary format with magic bytes (BKIT), version byte, and encrypted (AES-256-GCM + Argon2id KDF) or plaintext flag. File: ~/.bitkit/<network>/seed.enc.

API password: Auto-generated 32-byte random hex, stored with 0600 permissions. Only used for local daemon HTTP API access.

LSP Workflow: Fresh Wallet to Lightning-Ready

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

CODEBLOCK92

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