kaleido-mcp, and the RGB Lightning Node runs in Docker through KaleidoCLI. The only network calls go to your node, to the signet KaleidoSwap API, and to the Bitcoin and RGB services the node itself needs.
Everything here runs on signet, with test coins that have no value. Do not reuse a seed or a password from this tutorial anywhere else.
Prerequisites
No API key and no hosted LLM are needed.
1. Start a Signet RGB Lightning Node
Install KaleidoCLI with its install script. It is not on PyPI yet, sopip install will not find it:
mutinynet; it is the same signet that the KaleidoSwap signet API and the RGB faucet use. Write down the mnemonic that kaleido node init prints.
If port 3001 is already taken, kaleido setup picks the next free port. kaleido node list shows the URL; use it as RLN_NODE_URL in the steps below.
2. Fund the Node
RGB assets live on Bitcoin UTXOs, so the node needs a little signet BTC before it can receive anything.1
Get signet BTC
Print an on-chain address and send it coins from the public Mutinynet faucet. The faucet asks you to sign in with GitHub or to pay a small Lightning invoice:Signet blocks arrive about every 30 seconds. Check with
kaleido wallet balance.2
Create UTXOs for RGB
Split some of that BTC into UTXOs that can hold RGB allocations:
3
Get test RGB assets
Open the KaleidoSwap RGB faucet and sign in with GitHub. Copy the USDT or XAUT asset ID it lists, and create an RGB invoice for it:Paste the invoice in the faucet’s RGB on-chain tab. Each claim sends 100 USDT or 0.1 XAUT, up to 5 claims a day. Once the transfer confirms,
kaleido asset refresh followed by kaleido asset list shows the asset. The faucet’s Lightning tab needs a route to your node, so it only works after the next step.4
Buy a channel from the KaleidoSwap LSP
Swaps and Lightning payments need a channel. The KaleidoSwap LSP opens one to your node, optionally with USDT or XAUT on its side, and you pay a fee on-chain:
- Channel size: 50,000 to 1,000,000 sat, with up to 1,000 USDT or XAUT per channel. A 200,000 sat channel costs about 3,400 sat in fees.
- With an agent:
Buy a channel from the KaleidoSwap LSP preloaded with 10 USDTrunskaleidoswap_lsp_get_info,kaleidoswap_lsp_quote_asset_channelandkaleidoswap_lsp_create_asset_channel. Pay the fee to the address the order returns. - In KaleidoSwap Desktop: Channels → Order New Channel.
3. Run kaleido-mcp on Signet
KALEIDO_NETWORK=signet points kaleido-mcp at https://api.signet.kaleidoswap.com and Spark’s test network. Point RLN_NODE_URL at the node from step 1:
network: signet and waits on stdio. You do not need to keep it running by hand: the agent in the next step starts it as a child process. WDK_SEED is optional here, and plain npx does not install the Spark wallet package; without them the Spark tools stay off and the RGB, DEX, payment and market tools still work. See MCP Servers for every variable.
4. Wire a Local QVAC Model with KaleidoMind
Create a project and install the engine, the QVAC SDK, and the MCP client:@qvac/sdk >=0.20.0 and is tested with 0.21.0. Save this as agent.mjs:
agent.mjs
onConfirm callback, so nothing leaves the node until you type y.
This is a minimal host. The
@kaleidorg/mind README and the examples/node-minimal and examples/rgb-agent folders in the kaleido-mind repository go further, with skills, recipes, and a larger model. The example loads Qwen3.5 2B (about 1.3 GB), which handled every signet RGB wallet task in our tests. QWEN3_5_4B_MULTIMODAL_Q4_K_M (about 2.7 GB) is as accurate but about twice as slow; the 0.8B model loops on wallet actions. The token caps in the sample leave room for its reasoning before the answer.5. Prompts to Try
Go read-only first, then receive, then spend.
KaleidoMind may call the legacy
rln_* names for the same tools; kaleido-mcp serves both.
To try a send without a second wallet, ask a friend for an RGB invoice, or create one on a second node with kaleido node create.
Mock Mode: No Node, No Funds
To build the agent logic before the node is ready, or in CI, swap the MCP source for the stateful mock wallet in@kaleidorg/mind/testing. It is bound to the same tool contract, so the code that drives it later drives a real node:
mock.mjs
scriptedProvider() needs no model at all. Replace it with the QVAC provider from step 4 to test a real model against the mock wallet, then replace wallet.registry() with new ToolRegistry([kaleido]) to go live.
Troubleshooting
kaleido: command not found
kaleido: command not found
The installer puts
kaleido in a user script directory that may not be on your PATH yet. Open a new terminal, or follow the path the installer printed. See CLI Installation.The agent cannot reach the node
The agent cannot reach the node
Run
kaleido node info. If it fails, start the containers with kaleido node up and unlock with kaleido node unlock; the wallet locks again on every restart. Then check that RLN_NODE_URL matches the URL that kaleido node list marks as active.The faucet transfer never shows up
The faucet transfer never shows up
Run
kaleido asset refresh and wait for a confirmation. If the node has no free UTXOs, the invoice cannot be created or settled: run kaleido wallet create-utxos again after funding with BTC.The other side cannot pay my RGB invoice
The other side cannot pay my RGB invoice
The payer fetches the transfer data from an RGB proxy listed in the invoice. Create the invoice with
kaleido asset invoice, which adds the default proxy, or name the proxy in your prompt as in the table above.Quotes fail or point at mainnet
Quotes fail or point at mainnet
Confirm
kaleido-mcp logged network: signet. An explicit KALEIDOSWAP_API_URL or KALEIDO_API_URL in your environment overrides the preset.The swap never executes
The swap never executes
Check
wdk_list_channels: you need a usable channel with the maker that carries the asset you are buying or selling. Without one the quote works but settlement cannot.The model calls the wrong tool or invents arguments
The model calls the wrong tool or invents arguments
Small models are weak at open-ended planning. Phrase requests concretely, as in the prompts above, or load a larger QVAC model. KaleidoMind’s recipes handle the multi-step flows deterministically so the model only fills slots.
Ideas for Hackathon Projects
Voice wallet
QVAC also runs speech-to-text and text-to-speech locally.
createQvacVoice and runVoiceAssistant in @kaleidorg/mind/qvac give you a hands-free loop with a spoken confirmation before every spend.An agent that pays for APIs
Let the agent find a paid API with
search_paid_apis, then pay it per call over Lightning with the mpp_* and l402_* tools. No signups, no API keys.Autonomous swap bot
Watch prices with
l402_get_price and kaleidoswap_get_spreads, and rebalance between BTC and USDT with atomic swaps. Keep the confirmation gate on until the decisions look right.RGB issuance
Issue a ticket or loyalty token as a new RGB asset with
rln_issue_asset (it needs free colorable UTXOs), or from the CLI with kaleido asset issue nia.