RGB
Sync, contracts, consignments, and RGB payments (on-chain and Lightning).
RGB commands live under rgb .... This page is a map + a few “how do I copy the right value” examples.
If you want the full end-to-end flows (both directions, L1/L2), start with ./transfers.
Sync (do this when something looks stale)
rgbldk rgb syncContracts: list assets and copy IDs
rgbldk --no-truncate rgb contracts lsFrom the table, copy:
asset_id(hex)contract_id(starts withcontract:)
Contracts: balance
rgbldk rgb contracts balance <CONTRACT_ID>Contracts: check if a contract is known
If you have a contract_id string and want to verify the node recognizes it:
rgbldk rgb contracts known <CONTRACT_ID>This command prints:
contract_id=...
known=true|falseIf known=false, the CLI exits with a non-zero status (useful for scripts).
On-chain (RGB L1): invoice → send → receive
Receiver creates an invoice:
rgbldk --output json --pretty rgb onchain invoice-create --contract-id <CONTRACT_ID> --amount 10Optional sanity-check before sending:
rgbldk rgb onchain invoice-decode '<INVOICE>'Sender sends (copy consignment_key from the response):
rgbldk --output json --pretty rgb onchain send \
--invoice '<INVOICE>' \
--sats-for-fee-and-outputs 10000 \
--fee-rate-sats-per-vb 1.0Sender downloads a file:
rgbldk rgb consignments download --key <CONSIGNMENT_KEY> --out ./consignment.zip --format zipFor file uploads, derive the receiver-side payment_id as sha256(invoice_string) and pass it on receive:
rgbldk rgb onchain receive \
--file ./consignment.zip \
--format zip \
--payment-id <PAYMENT_ID_HEX>If both sides can see the same daemon-side consignment cache, you can skip the file download/upload hop and use:
rgbldk rgb onchain receive <CONSIGNMENT_KEY> --invoice '<INVOICE>'To inspect RGB L1 payment history:
rgbldk rgb onchain payments
rgbldk rgb onchain payments --contract-id <CONTRACT_ID>Lightning (RGB L2): invoice → pay
Receiver creates an invoice:
rgbldk --output json --pretty rgb ln invoice create \
--asset-id <ASSET_ID_HEX> \
--asset-amount 3 \
--desc "demo" \
--btc-carrier-amount-msat 4000000Create an RGB LN invoice for a specific payment hash (advanced)
If your application already has a payment_hash it needs to use:
rgbldk --output json --pretty rgb ln invoice create-for-hash \
--asset-id <ASSET_ID_HEX> \
--asset-amount 3 \
--payment-hash <PAYMENT_HASH_HEX> \
--desc "demo" \
--btc-carrier-amount-msat 4000000Optional decode (sanity-check what you are about to pay):
rgbldk rgb ln invoice decode <INVOICE>Sender pays (copy payment_id):
rgbldk --output json --pretty rgb ln pay --invoice '<INVOICE>'
rgbldk pay wait <PAYMENT_ID> --timeout-secs 60Consignments (download by key)
If you have a consignment_key and need the file again:
rgbldk rgb consignments download --key <CONSIGNMENT_KEY> --out ./consignment.zip --format zipError output
When an RGB command fails, the CLI prints the server's structured fields instead of only the top-level error code. Expect output like:
HTTP 400: RgbErr
message=RGB wallet operation failed: ...
detail={"rgb_code":"WalletOperation","wallet_code":"...","reason":"..."}
hint=...
checks=[...]For RGB failures, detail.reason is usually the most actionable field.