# HiddenSwap MCP

Connect Claude, Cursor, VS Code and other AI assistants to [HiddenSwap](https://hiddenswap.com), a
crypto-to-crypto swap site with no account, no email and no KYC. The assistant can look up coins,
get live swap estimates (Monero, Zcash, Bitcoin, Ethereum, USDT and 1,000+ other coins and networks),
check whether a pair can be swapped, and follow an order by its ID.

The server is **read-only**. It never creates a swap, never asks for a wallet address, and needs
no API key or account. When someone wants to swap, it returns a link to the swap page on
hiddenswap.com, where the person starts the swap themselves.

- Remote endpoint (Streamable HTTP): `https://hiddenswap.com/mcp`
- Registry name: `com.hiddenswap/swap`
- More of our open-source work: [hiddenswap.com/open-source](https://hiddenswap.com/open-source)

## Tools

| Tool | What it does | Arguments |
|---|---|---|
| `search_coins` | Finds coin ids by ticker, name or network, for example "usdt tron" or "monero" | `query`, `side`, `limit` |
| `get_quote` | Estimates a swap: the amount received after all fees, the rate, the minimum, the payout fee and a swap link | `from`, `to`, `amount`, `rateType` (`float` or `fixed`) |
| `get_pair_info` | Checks whether two coins can be swapped and what each network needs (memos, fixed-rate support), without a live quote | `from`, `to`, `amount` |
| `get_order_status` | Shows the stage of an order: awaiting deposit, confirming, swapping, sending, complete, refunded or expired | `orderId` |

Estimates are not guaranteed: with a floating rate, the final amount is set when the network
confirms the deposit.

## Connect

Most clients connect to the remote endpoint directly. Nothing to install.

**Claude Code**

```sh
claude mcp add --transport http hiddenswap https://hiddenswap.com/mcp
```

**Claude Desktop and claude.ai**: Settings, then Connectors, then *Add custom connector*, with the URL
`https://hiddenswap.com/mcp`.

**Cursor** (`~/.cursor/mcp.json`)

```json
{ "mcpServers": { "hiddenswap": { "url": "https://hiddenswap.com/mcp" } } }
```

**VS Code** (`.vscode/mcp.json`)

```json
{ "servers": { "hiddenswap": { "type": "http", "url": "https://hiddenswap.com/mcp" } } }
```

**Clients that only run local (stdio) servers** can use the bridge in this repository, which passes
every message on to the remote endpoint:

```json
{ "mcpServers": { "hiddenswap": { "command": "npx", "args": ["-y", "github:hiddenswap/hiddenswap-mcp"] } } }
```

More examples are in [`examples/`](examples/).

**Docker**: `docker build -t hiddenswap-mcp .` then `docker run -i --rm hiddenswap-mcp` runs the same stdio bridge.

## Command line

The same package works as a small command-line tool (Node.js 18 or later):

```sh
npx -y github:hiddenswap/hiddenswap-mcp quote btc xmr 0.1
# 0.1 BTC -> about 13.75 XMR (floating rate, after fees)
# Minimum: 0.00015 BTC
# Swap: https://hiddenswap.com/exchange/btc-to-xmr?amount=0.1&rateType=float&ref=mcp#swap

npx -y github:hiddenswap/hiddenswap-mcp coins "usdt tron"
npx -y github:hiddenswap/hiddenswap-mcp pair zec btc
npx -y github:hiddenswap/hiddenswap-mcp order <order id>
```

Add `--fixed` to `quote` for a fixed-rate estimate, or `--json` for the raw result.

## Other ways in

- **A2A**: the same four skills as an A2A agent. Card at `https://hiddenswap.com/.well-known/agent-card.json`, endpoint `https://hiddenswap.com/a2a`.
- **WebMCP**: pages on hiddenswap.com register the tools in the browser for agents that support WebMCP.
- **llms.txt**: a plain-text summary of the site at `https://hiddenswap.com/llms.txt`.

## Limits

Requests are rate-limited per client, and live quotes have a per-minute budget. Answers from a
busy period can come from the most recent recorded quote, marked with `"source"` in the result.

## Development

```sh
npm test    # runs the bridge against a local stand-in server, no network needed
```

Set `HIDDENSWAP_MCP_URL` to point the bridge or the command-line tool at another endpoint.

## License

MIT. Made by [HiddenSwap](https://hiddenswap.com).