Bitcoin MCP Servers for Wallets, Swaps, and Paid APIs

KaleidoSwap exposes its wallet, DEX, and payment functionality to AI agents (Claude Desktop, KaleidoAgent, KaleidoMind-based hosts, or any other MCP client) through kaleido-mcp, the unified server recommended for new integrations. It supersedes the earlier standalone wallet servers; see the migration notes at the end of this page.

What you need

Operation	Prerequisite
Market reads and quotes	MCP client and Node.js; no seed or local node
RGB wallet and atomic RGB swaps	Reachable, unlocked RGB Lightning Node
Spark or Liquid wallet	Optional wallet package and its mnemonic
Submarine swaps	Optional swap SDK, Node.js 22+, and a configured funding wallet

The model calls tools through your MCP client. Starting the server in a terminal only waits for protocol requests; it does not open a chat.

Installation & Configuration

kaleido-mcp is published to npm, which is the quickest way to a first tool call. Start on signet:

KALEIDO_NETWORK=signet npx -y kaleido-mcp

This page documents kaleido-mcp 0.3.0 and later. 0.3.0 adds the KALEIDO_NETWORK preset and the kaleido_node_* lifecycle tools, and drops the order-based swap tools in favour of atomic swaps. If npx resolves an older cached version, run npx -y kaleido-mcp@latest once, or build from source.

From 0.3.1 the Spark and Liquid wallets are optional peer dependencies that plain npx -y kaleido-mcp does not install. With WDK_SEED or LIQUID_MNEMONIC set but the package missing, the server still starts and logs an install hint. To enable them:

npx -y -p kaleido-mcp -p @tetherto/wdk-wallet-spark -p @kaleidorg/wdk-wallet-liquid kaleido-mcp

In practice an MCP host runs this for you, point its config at the command (see Client Configuration below). For development, or to run a specific commit, build from source instead:

git clone https://github.com/kaleidoswap/kaleido-mcp
cd kaleido-mcp
npm install
npm run build

Either way, the server reads the same environment variables and speaks stdio by default:

# stdio (Claude Desktop, Claude Code, KaleidoAgent, ...)
KALEIDO_NETWORK=signet WDK_SEED="word1 word2 ..." node dist/index.js

# HTTP transport
PORT=3010 KALEIDO_NETWORK=signet WDK_SEED="word1 word2 ..." node dist/index.js

Network Preset

KALEIDO_NETWORK picks a set of defaults in one variable. It accepts signet (the default from 0.3.1) or mainnet:

Preset	KaleidoSwap API	Spark network
`signet`	`https://api.signet.kaleidoswap.com`	Spark’s test network (`REGTEST` in the Spark SDK)
`mainnet`	None: set `KALEIDOSWAP_API_URL` to your own maker endpoint	`MAINNET`

The KaleidoSwap API here is the maker API for swaps between RGB Lightning Nodes, which the kaleidoswap_* tools use through the Node SDK. It is not the /v2 maker API in the API Reference. The preset only fills in defaults. Any variable you set explicitly, such as KALEIDOSWAP_API_URL or SPARK_NETWORK, wins over it. There is no public mainnet KaleidoSwap API, so mainnet without KALEIDOSWAP_API_URL stops the server at startup, as does an unknown value. RLN_NODE_URL is not part of the preset: point it at your own node, which on signet is usually the one KaleidoCLI runs on http://localhost:3001.

Env var	Required	Description
`KALEIDO_NETWORK`	No	`signet` (default) or `mainnet`. Sets the defaults in Network Preset
`WDK_SEED`	Yes, for Spark tools	BIP-39 mnemonic for the Spark wallet. Also needs the optional `@tetherto/wdk-wallet-spark` package. The server still boots without either, the Spark tools are just disabled
`LIQUID_MNEMONIC`	Yes, for Liquid tools	BIP-39 mnemonic for the Liquid wallet. Also needs the optional `@kaleidorg/wdk-wallet-liquid` package
`SPARK_NETWORK`	No	Overrides the preset’s Spark network: `MAINNET`, or `REGTEST` for Spark’s test network
`SPARK_SCAN_API_KEY`	No	SparkScan API key
`SPARK_USDT_TOKEN`	No	Default Spark token identifier
`RLN_NODE_URL`	No	RLN daemon URL, default `http://localhost:3001`
`KALEIDOSWAP_API_URL`	With `mainnet`	KaleidoSwap maker API URL, overriding the preset. Required on `mainnet`, which has no public endpoint. `KALEIDO_API_URL` is accepted as well
`KALEIDO_BIN`	No	Path to the `kaleido` binary, for the node lifecycle tools
`KALEIDO_NODE_URL`	No	Node URL passed as `--node-url` to the node lifecycle tools
`KALEIDO_API_URL`	No	API URL passed as `--api-url` to the node lifecycle tools, and a fallback for `KALEIDOSWAP_API_URL`
`KALEIDO_ENV_NAME`	No	Default environment name for the node lifecycle tools
`PORT`	No	Enable Streamable HTTP transport instead of stdio
`MCP_AUTH_TOKEN`	No	Bearer token for HTTP mode

Runtime Compatibility

Check the installed package versions when diagnosing an integration. QVAC-backed Mind hosts require @qvac/sdk >=0.20.0. The kaleidoswap_submarine_* tools also need the optional @kaleidorg/swap-sdk package and Node.js 22 or newer. A tool appearing in the catalog does not guarantee that its wallet, node or optional dependency is configured. A successful /health response only confirms that the HTTP process is running. The generated MCP reference lists the current schemas. Use the reference at your installed release tag when building a version-pinned integration.

Legacy Aliases

Some tools are still reachable under older names (rln_* for wdk_*, generic get_* for the l402_get_* market tools) for backward compatibility with earlier integrations. New integrations should use the canonical wdk_* / l402_* names.

Tool Surface by Domain

All tools below are served by kaleido-mcp over a single connection. The 🔒 icon marks spend-moving tools in these docs; kaleido-mcp does not encode a confirmation flag, so whether a call is confirmed before executing is the MCP host’s behavior. The exception is the WDK built-in sendTransaction and transfer, which request an MCP-elicitation confirmation themselves before broadcasting.

Spark L2 wallet (spark_*)

WDK built-in tools (via @tetherto/wdk-mcp-toolkit, scoped to the spark chain): getAddress, getBalance, getMaxSpendableBtc, sendTransaction, transfer, getTokenBalance, quoteSendTransaction, quoteTransfer, getFeeRates, sign, verify.Custom Spark tools, on top of the built-ins:

Tool	Purpose
`spark_get_balance`	Spark L2 wallet balance in satoshis (fee-free transfers)
`spark_get_address`	Spark L2 address for receiving sats or tokens
`spark_get_token_balance`	Balance of a Spark token (e.g. USDT) by token identifier
`spark_get_deposit_address`	Bitcoin L1 address to bridge BTC into the Spark L2 wallet
`spark_create_lightning_invoice`	BOLT11 invoice to receive BTC into Spark via Lightning
`spark_pay_lightning_invoice` 🔒	Pay a BOLT11 invoice from the Spark wallet
`spark_quote_lightning_payment`	Estimate the Lightning routing fee before paying
`spark_send_sats` 🔒	Send satoshis to another Spark L2 address (fee-free)
`spark_transfer_token` 🔒	Transfer a Spark token (e.g. USDT) to another address (fee-free)
`spark_quote_withdraw`	Fee quote for a cooperative-exit withdrawal to Bitcoin L1
`spark_withdraw` 🔒	Withdraw BTC from Spark L2 to a Bitcoin L1 address
`spark_get_transfers`	Recent Spark L2 transfer history
`spark_create_sats_invoice`	Spark invoice (`spark1...`) to receive BTC sats
`spark_create_tokens_invoice`	Spark invoice (`spark1...`) to receive tokens
`spark_pay_spark_invoice` 🔒	Pay one or more Spark invoices
`spark_get_spark_invoices`	Query status of one or more Spark invoices
`spark_mpp_pay` 🔒	Pay an MPP Lightning challenge from the Spark wallet

In kaleido-mcp, configure WDK_SEED and install the optional @tetherto/wdk-wallet-spark package. SPARK_NETWORK, SPARK_SCAN_API_KEY, and SPARK_USDT_TOKEN are optional.

RLN, RGB Lightning Node (wdk_, alias rln_)

Tool	Purpose
`wdk_get_node_info`	Node identity: pubkey, channel count, Lightning balance, peers
`wdk_get_balances`	BTC on-chain (vanilla and colored UTXOs) and Lightning balance
`wdk_get_asset_balance`	Balance of a specific RGB asset (USDT, XAUT) by `asset_id`
`wdk_list_assets`	All RGB assets held by the node (NIA, UDA, CFA schemas)
`wdk_get_address`	On-chain BTC address for receiving deposits
`wdk_create_rgb_invoice`	Create an RGB invoice to receive an RGB asset
`wdk_create_ln_invoice`	Create a BOLT11 invoice to receive BTC via Lightning
`wdk_pay_invoice` 🔒	Pay a BOLT11 Lightning invoice
`wdk_send_btc` 🔒	Send BTC on-chain
`wdk_send_asset` 🔒	Send an RGB asset (USDT/XAUT) on-chain
`wdk_list_channels`	All Lightning channels: capacity, balance, usability, RGB allocation
`wdk_connect_peer`	Connect to a Lightning peer (`pubkey@host:port`), required before an LSPS1 channel purchase
`wdk_open_channel` 🔒	Open a Lightning channel, optionally with RGB asset allocation
`wdk_close_channel` 🔒	Close a Lightning channel (`force=true` only for unresponsive peers)
`wdk_get_channel_id`	Resolve a `temporary_channel_id` to the permanent `channel_id`
`wdk_list_payments`	Recent Lightning payments, sent and received
`wdk_refresh_transfers`	Sync pending RGB asset transfers, call after a KaleidoSwap order fills
`wdk_atomic_taker` 🔒	Step 2 of an atomic HTLC swap, whitelist the incoming HTLC
`wdk_list_swaps`	List all atomic swaps on the node, maker and taker sides
`wdk_get_swap`	Atomic swap status by `payment_hash`
`wdk_mpp_pay` 🔒	Pay an MPP Lightning challenge from the RLN wallet

Requires a running RGB Lightning Node reachable at RLN_NODE_URL, default http://localhost:3001.

KaleidoSwap DEX (kaleidoswap_*)

Tool	Purpose
`kaleidoswap_get_assets`	Tradeable assets: ticker, name, precision, RGB protocol ID
`kaleidoswap_get_pairs`	Tradeable pairs with available layer routes
`kaleidoswap_get_quote`	Price quote for a swap, returns output amount, price, fee, `rfq_id`
`kaleidoswap_get_spreads`	Quotes across every route for a pair, to compare or find arbitrage
`kaleidoswap_atomic_init`	Step 1 of an atomic swap, returns `swapstring` and `payment_hash`
`kaleidoswap_atomic_execute` 🔒	Step 3, confirm execution after `wdk_atomic_taker` whitelists the HTLC
`kaleidoswap_atomic_status`	Poll atomic swap status by `payment_hash`
`kaleidoswap_lsp_get_info`	LSP peer connection info and channel capacity limits
`kaleidoswap_lsp_estimate_fees`	Estimate LSPS1 channel opening fees before committing
`kaleidoswap_lsp_create_order` 🔒	Request a new Lightning channel (LSPS1), returns a BOLT11 invoice
`kaleidoswap_lsp_get_order`	Poll LSPS1 channel order status
`kaleidoswap_lsp_quote_asset_channel`	Quote a new channel pre-loaded with an RGB asset (USDT, XAUT)
`kaleidoswap_lsp_create_asset_channel` 🔒	Order a new asset-preloaded channel from the LSP

Configured with KALEIDO_NETWORK, or KALEIDOSWAP_API_URL for a custom endpoint. Swaps are atomic only: the order-based tools (kaleidoswap_place_order, kaleidoswap_get_order_status and the rest) were removed in 0.3.0. The underlying maker endpoints are described with the Node SDK.

MPP / L402 payments (mpp_, l402_)

Tool	Purpose
`mpp_request_challenge`	Probe an MPP-protected URL, parse an HTTP 402 into invoice + `challenge_id`
`mpp_submit_credential`	Submit a payment credential (after `wdk_mpp_pay` / `spark_mpp_pay`) to access the resource
`mpp_parse_challenge_header`	Parse a raw `WWW-Authenticate` header without an HTTP request
`l402_request_challenge`	Legacy L402 challenge for a premium endpoint, BOLT11 invoice plus macaroon
`l402_fetch_resource`	Fetch an L402-gated resource after paying the invoice
`search_paid_apis`	Search the 402index.io directory for payment-gated APIs (L402/MPP/x402), with pricing in sats and health status

Market data (l402_get_, alias get_)

WDK built-in pricing tools (Bitfinex): getCurrentPrice, getHistoricalPrice.

Tool	Purpose
`l402_get_price`	Spot price and 24h stats for one asset
`l402_get_market_data`	Batch prices for several assets in one call
`l402_get_ohlcv`	OHLCV candles with period change percentage
`l402_get_sentiment`	Fear and Greed index, 0 to 100, with a trading signal

Uses free public APIs (CoinGecko, alternative.me) with no configuration required. The free CoinGecko tier is rate limited, so avoid calling price tools more than once every 30 seconds.

Node lifecycle (kaleido_node_*)

Shells out to a local kaleido binary, so an agent can bring a node up and unlock it rather than requiring one to already be running. See Node Environments for the CLI-native equivalent of these operations.

Tool	Purpose
`kaleido_node_list`	List all kaleido node environments and their node URLs
`kaleido_node_up`	Start Docker containers for a named environment
`kaleido_node_stop`	Stop running containers, data preserved
`kaleido_node_down`	Stop and remove containers and networks, volumes preserved
`kaleido_node_ps`	Docker container status for a named environment
`kaleido_node_status`	RLN node health check
`kaleido_node_info`	Detailed node and network info from the active RLN node
`kaleido_node_use`	Set the active node URL in kaleido config
`kaleido_node_init`	Initialise the RLN wallet for the first time
`kaleido_node_unlock`	Unlock the RLN wallet after a restart
`kaleido_node_lock`	Lock the RLN wallet

Client Configuration

Add the unified server to your MCP client. Start with market reads and add wallet packages only when you need them.

The starter configuration below needs no mnemonic. If you later add wallet seeds, keep that configuration private and out of version control.

{
  "mcpServers": {
    "kaleido": {
      "command": "npx",
      "args": ["-y", "kaleido-mcp"],
      "env": {
        "KALEIDO_NETWORK": "signet",
        "RLN_NODE_URL": "http://localhost:3001"
      }
    }
  }
}

claude mcp add kaleido \
  --env KALEIDO_NETWORK=signet \
  --env RLN_NODE_URL=http://localhost:3001 \
  -- npx -y kaleido-mcp

On Claude Desktop the file is claude_desktop_config.json (Settings > Developer > Edit Config). WDK_SEED and the @tetherto/wdk-wallet-spark package are optional: leave them out and the Spark tools are disabled while the RGB node, DEX, payment and market tools keep working. REGTEST is the name the Spark SDK gives its hosted test network.

First Run

Start with market reads, then wallet reads, then a quote. Reading balances and requesting a quote do not move funds; payment and execution tools do.

Add the gateway to your host

Drop the kaleido-mcp block into your MCP host’s config with KALEIDO_NETWORK set to signet. The full JSON is in Client Configuration above.

Restart the host

MCP hosts read their config at startup. A running client will not pick up a new server until you restart it.

Call a read-only tool

Start with something that cannot move funds. Ask for market data, which needs no seed and no node:

What is the current Bitcoin price and the Fear and Greed index?

That exercises l402_get_price and l402_get_sentiment. Check that the client reports successful tool calls; a model-generated answer alone does not verify the connection.

Check the wallet is wired

After enabling the optional Spark package and seed, confirm the wallet tools resolve:

Show me my Spark balance and my Spark address.

This calls spark_get_balance and spark_get_address. If discovery succeeded but this call fails, check the optional wallet package, seed, network and the tool error.

Quote before you trade

Ask for a price without placing anything:

Quote 100000 sats of BTC into USDT. Do not execute anything.

kaleidoswap_get_quote returns an rfq_id, raw amounts, the fee, and an expiry. Read the raw amounts carefully: they are in the asset’s smallest unit, not display units.

Execute only once the quote looks right

An atomic swap needs the DEX tools and the wallet tools together, and the node must hold the asset in a channel. The cross-server sequence below shows each call in order.

A generic MCP host is the least protected path. kaleido-mcp does not encode a confirmation flag, so if your client auto-approves tool calls, an LLM can spend from the configured wallet without asking you. Use a test network seed until you know how your client handles approvals.

Atomic Swap Flow

An atomic swap needs the DEX tools and the wallet tools together. kaleido-mcp speaks to the maker via its kaleidoswap_* tools and drives the taker node via its wdk_* tools. Nothing is custodied at any step, and the HTLC settles on Lightning.

kaleidoswap_get_quote        → rfq_id + raw amounts
kaleidoswap_atomic_init      → swapstring + payment_hash
wdk_atomic_taker             → whitelist the HTLC on the node
wdk_get_node_info            → taker_pubkey
kaleidoswap_atomic_execute   → trigger HTLC settlement
kaleidoswap_atomic_status    → poll until Succeeded

Every step above runs through the same kaleido-mcp connection, since both prefixes are available at once.

Paid API Access

The Machine Payments Protocol flow lets an agent buy access to a gated resource without an API key or a signup, paying the invoice over Lightning.

mpp_request_challenge(url)          → challenge { invoice, challenge_id }
wdk_mpp_pay(invoice, challenge_id)  → payment credential
mpp_submit_credential(url, cred)    → { ok, data, receipt }

Retired Servers

These names are migration references, not additional servers to install:

Older entry point	Current path
`wdk-wallet-mcp`	`wdk_*` in `kaleido-mcp`
`wdk-wallet-spark-mcp`	`spark_*` plus the optional Spark package; use `WDK_SEED` instead of `WDK_SPARK_SEED`
`wdk-wallet-liquid-mcp`	`liquid_*` plus the optional Liquid package
`kaleidoswap-mcp`	`kaleidoswap_*`; use atomic swaps instead of the removed REST order flow
`l402-gateway-mcp`	`mpp_` / `l402_`
`kaleido-node-mcp`	`kaleido_node_` for lifecycle operations; `wdk_` for the wallet

Keep existing rln_* aliases where required by your host. For new raw MCP integrations prefer canonical names and check the generated schemas for your installed version before migrating arguments.

Introduction

Tools

Reference

Bitcoin MCP Servers for Wallets, Swaps, and Paid APIs

What you need

Installation & Configuration

Network Preset

Runtime Compatibility

Legacy Aliases

Tool Surface by Domain

Client Configuration

First Run

Atomic Swap Flow

Paid API Access

Retired Servers

​What you need

​Installation & Configuration

​Network Preset

​Runtime Compatibility

​Legacy Aliases

​Tool Surface by Domain

​Client Configuration

​First Run

​Atomic Swap Flow

​Paid API Access

​Retired Servers

What you need

Installation & Configuration

Network Preset

Runtime Compatibility

Legacy Aliases

Tool Surface by Domain

Client Configuration

First Run

Atomic Swap Flow

Paid API Access

Retired Servers