# THORChain Swap — Agent Library

The complete reference for AI agents using THORChain Swap (https://swap.thorchain.org), the public web interface for native cross-chain swaps powered by THORChain and Maya Protocol. Everything here is public; nothing requires authentication.

## What This Site Does

THORChain Swap swaps native layer-1 assets (BTC, ETH, stablecoins, and more) directly between chains — no bridges, no wrapped tokens, no order books, and no user accounts. Swaps settle in native assets on their own chains. Users either connect their own wallet and sign locally, or swap without connecting a wallet at all via memoless ("instant") swaps: they send funds to a deposit address and receive the swapped asset at their destination address.

## When To Use

- A user wants to swap native L1 assets without bridges, wrapped tokens, or custodial accounts.
- A user needs a live cross-chain swap quote, pool depths, or THORChain network status (use the MCP server; no API key).
- A user wants to swap without connecting a wallet (memoless flow).

Not a fit for: fiat on/off-ramps, NFTs, derivatives, or custodial account management. Never attempt to execute a swap on a user's behalf; users sign in their own wallets or send funds themselves.

## Architecture and Data Sources

Two components:

- **UI** — https://swap.thorchain.org
- **Backend API** — the THORChain/Maya swap aggregator: https://api.thorchain.org/v1 for quotes and routing (requires an `x-api-key` header — free, via the affiliate program at https://affiliate.thorchain.org, issued after review) and https://api.thorchain.org/memoless/api/v1 for memoless swaps (no key).

Protocol metadata (pools, network parameters, THORNames, balances, inbound addresses) comes from public THORNode and Midgard APIs. Keyless agent access to quotes, pools, and network data: the MCP server below.

## Deep Links (URL Scheme)

Hand users a prefilled swap URL:

```
https://swap.thorchain.org/sell-BTC-buy-ETH
https://swap.thorchain.org/sell-BTC.BTC-buy-ETH.USDC
```

The path pattern is `/sell-<asset>-buy-<asset>`. Native gas assets may use just the ticker; tokens use `CHAIN.TICKER` (the full identifier with the contract-address suffix is also accepted).

## Asset Notation and Amounts

- Assets use `CHAIN.SYMBOL` notation: `BTC.BTC`, `ETH.ETH`, `ETH.USDC-0XA0B86991C6218B36C1D19D4A2E9EB0CE3606EB48` (token contract appended after a hyphen, uppercase).
- Amounts use 1e8 base units regardless of the asset's native decimals: `100000000` = 1 BTC = 1 ETH = 1 RUNE. Core MCP amount inputs are integers; returned amount fields are generally strings.

## Quote Semantics

- Quotes are indicative and time-sensitive; re-fetch before presenting.
- Use core `prepare_swap` with a confirmed destination for executable deposit instructions. Any memo and inbound address expire at `expiry` (unix seconds); never reuse them after expiry.
- `expected_amount_out` is the estimate after fees; `fees` itemizes them; `fees.slippage_bps` is the price impact.
- `recommended_min_amount_in` is the smallest economically sensible input; below it, fees dominate.

## MCP Server

Use the canonical THORChain MCP server, registered as [`org.thorchain/thorchain-mcp`](https://registry.modelcontextprotocol.io/v0.1/servers/org.thorchain%2Fthorchain-mcp/versions/latest). It provides read-only THORChain data from THORNode and Midgard without authentication.

- Endpoint: https://mcp.thorchain.org/mcp (JSON-RPC over HTTP POST)
- Live core server card: https://mcp.thorchain.org/.well-known/mcp/server-card.json
- This site's live card mirror: https://swap.thorchain.org/.well-known/mcp/server-card.json (with THORChain branding)
- Core source and deployment: https://gitlab.com/thorchain/thorchain-mcp

Selected tools only; call `tools/list` for the complete current inventory and input schemas:

- `quote_swap` — Read indicative THORChain swap output, fees, slippage, and timing.
- `list_pools` — Read THORChain pools from Midgard with pagination.
- `get_network_summary` — Read node counts, APY, reserve, pooled RUNE, churn height, and vault migration state.

The core `quote_swap` input amount is an integer in 1e8 base units. Its schema accepts `from_asset`, `to_asset`, `amount`, and optional `destination`, `affiliate`, `affiliate_bps`. Core `list_pools` accepts `limit` and `offset`; `get_network_summary` takes no parameters. For executable instructions use `prepare_swap` with a confirmed destination; the user still signs and sends funds.

```bash
curl -N -sS https://mcp.thorchain.org/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-06-18' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "quote_swap",
      "arguments": {
        "from_asset": "BTC.BTC",
        "to_asset": "ETH.ETH",
        "amount": 100000000
      }
    }
  }'
```

Send both media types in `Accept` and parse SSE `data:` events as JSON-RPC. Read `result.structuredContent.data` for the payload and `_metadata` for its source and freshness. Illustrative response:

```text
event: message
data: {"jsonrpc":"2.0","id":1,"result":{"structuredContent":{"data":{"expected_amount_out":"123456"},"_metadata":{"source_used":"thornode","canonical":true}},"content":[{"type":"text","text":"{\"data\":{\"expected_amount_out\":\"123456\"},\"_metadata\":{\"source_used\":\"thornode\",\"canonical\":true}}"}]}}

```

The live core card and initialization response own the protocol revisions, tool inventory, capabilities, and limits. This site's old `/mcp` URL permanently redirects to the canonical endpoint without translating legacy tool names or parameters. Configure new clients with the canonical URL directly. The server never holds keys, signs, or submits transactions.

## REST API

Described by OpenAPI 3.1 at https://swap.thorchain.org/.well-known/openapi.json. Versioned in the URL path; `/api/v1/` is canonical and unversioned `/api/*` paths are stable aliases.

- `POST /api/v1/newsletter` — subscribe an email address to updates

It is unauthenticated, rate limited per client (429 with Retry-After), and accepts an `Idempotency-Key` header: a retry with the same key within one hour replays the original response (`Idempotency-Replayed: true`) instead of re-executing. Every non-2xx response is JSON with `error`, `code`, `hint`, and `documentation` fields. Swap quotes are NOT served under https://swap.thorchain.org/api — use the MCP server or the aggregator backend.

## Authentication

Browsing, quoting, and the support APIs are anonymous. Wallet connection and signing happen in user-controlled wallets in the browser; memoless swaps need no wallet.

This site runs no authorization server and issues no tokens, so there is no `/.well-known/oauth-protected-resource` or `/.well-known/oauth-authorization-server` to discover — an MCP client that probes for them finds nothing and connects directly. The aggregator API (https://api.thorchain.org/v1) is separate and takes an `x-api-key` issued free through the affiliate program at https://affiliate.thorchain.org. Details: https://swap.thorchain.org/auth.md.

## SDKs

- TypeScript / JavaScript — `@tcswap/sdk` (npm): https://github.com/thorchain/TCSwap/tree/main/packages/sdk
- Python — `thorchain-swap` (PyPI): https://github.com/thorchain/swap.thorchain/tree/main/sdk/python
- Go — `github.com/thorchain/swap.thorchain/sdk/go` (Go modules): https://github.com/thorchain/swap.thorchain/tree/main/sdk/go

Reference: https://swap.thorchain.org/developers/sdks

## Discovery Endpoints

- https://swap.thorchain.org/llms.txt — index of agent resources
- https://swap.thorchain.org/AGENTS.md — agent guidance and safety rules
- https://swap.thorchain.org/developers — developer portal (markdown: /developers.md)
- https://swap.thorchain.org/developers/quickstart — Quickstart
- https://swap.thorchain.org/developers/api — REST API reference
- https://swap.thorchain.org/developers/mcp — MCP server
- https://swap.thorchain.org/developers/auth — Authentication
- https://swap.thorchain.org/developers/sdks — SDKs
- https://swap.thorchain.org/developers/webhooks — Webhooks and events
- https://swap.thorchain.org/.well-known/openapi.json — OpenAPI 3.1 description
- https://swap.thorchain.org/.well-known/api-catalog — RFC 9727 API catalog
- https://swap.thorchain.org/.well-known/mcp/server-card.json — MCP server card
- https://swap.thorchain.org/.well-known/agent-card.json — A2A agent card
- https://swap.thorchain.org/.well-known/agent-skills/index.json — agent skills index
- https://swap.thorchain.org/auth.md — authentication model
- Source code (with AGENTS.md for coding agents): https://github.com/thorchain/swap.thorchain

## Other Interfaces

- Pool: https://pool.thorchain.org/
- Bond: https://bond.thorchain.org/
- Memo: https://memo.thorchain.org/
- TCY: https://tcy.thorchain.org/
- THORName: https://thorname.thorchain.org/

## Safety Rules

1. Never request, store, or infer private keys or seed phrases.
2. Never execute swaps on behalf of a user — only users sign transactions in their own wallets.
3. Treat quotes, balances, and transaction state as time-sensitive; re-fetch before presenting.
4. Never reuse a quote's `memo` or `inbound_address` after its `expiry`.
5. Confirm destination addresses with the user before they submit any transaction.

## Support

- Email: contact@thorchain.org
