Skip to main content
This is the path from an installed tool to a verified swap. It goes read-only first, then quoting, then execution, because every step after the first one moves real value.

​
Before You Start

If you have not installed anything yet, start with Installation.

​
Pick a Surface

​
First Run: MCP Servers

1

Add the gateway to your host

Drop the kaleido-mcp block into your MCP host’s config, pointing KALEIDOSWAP_API_URL at a test environment and SPARK_NETWORK at REGTEST. The full JSON is on the MCP Servers page.
2

Restart the host

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

Call a read-only tool

Start with something that cannot move funds. Ask for market data, which needs no seed and no node:
That exercises l402_get_price and l402_get_sentiment. If it answers, the connection works.
4

Check the wallet is wired

Now confirm the wallet tools resolve:
This calls spark_get_balance and spark_get_address. An error here is a seed or network problem, not a connection problem.
5

Quote before you trade

Ask for a price without placing 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.
6

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 shows each call in order.

​
First Run: KaleidoAgent

1

Keep dry run enabled

portfolio.dry_run defaults to true in agent.config.json. Leave it there. The agent will reason, decide, and report a trade without submitting it.
2

Start the agent

Open http://localhost:5173 for the dashboard.
3

Trigger a loop by hand

Rather than waiting on the schedule, ask the status API to run one:
Then read GET /status to see the decision, the balances it saw, and the token cost.
4

Review the risk limits

Confirm max_swap_usd, min_btc_reserve_sats, and stop_loss_btc_sats match what you are willing to lose on a test network. These are checked before any swap is submitted.
5

Only then disable dry run

Set portfolio.dry_run to false when the dry-run decisions have looked correct across several runs.

​
What Confirmation Looks Like

The two agent surfaces gate spending differently, and it is worth knowing which one you are relying on.
A generic MCP host is the least protected path. 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.