THORChain Developer Resources
THORChain developer resources for the swap interface — API docs, OpenAPI spec, auth docs, and MCP server — for THORChain Swap, the public web interface for native cross-chain swaps powered by THORChain and Maya Protocol. Everything on this page is also available as markdown at /developers.md.
Named Developer Resources
Each topic has its own page, and every page has a markdown twin at the same URL plus .md:
- THORChain Swap Quickstart — Fetch your first THORChain Swap quote in one request: MCP endpoint, asset notation, 1e8 base units, and prefilled swap links. No API key required.
- THORChain Swap REST API reference — Reference for the THORChain Swap public REST API: endpoints, OpenAPI 3.1 description, JSON error format, Idempotency-Key support, rate limits, versioning, and sandbox.
- THORChain Swap MCP server — Connect THORChain Swap integrations to the canonical THORChain MCP server: registry identity, Streamable HTTP and SSE, quote_swap, list_pools, get_network_summary, and live schemas.
- THORChain Swap Authentication — How authentication works on THORChain Swap: the MCP server and support APIs need no key, token, or OAuth, and free aggregator API keys come from the affiliate program.
- THORChain Swap SDKs — THORChain Swap client libraries for TypeScript, Python, and Go: swap-building SDKs, core MCP protocol data, and public REST support endpoints.
- THORChain Swap Webhooks and events — THORChain Swap emits no webhooks. How to track swap and protocol state instead: THORNode transaction status, Midgard actions, inbound addresses, and MCP polling.
Architecture
THORChain Swap consists of two components:
- UI — this web app. Users connect their own wallet and sign transactions locally, or swap without connecting a wallet via memoless (“instant”) swaps.
- Backend API — the THORChain/Maya Protocol swap aggregator:
https://api.thorchain.org/v1for swap quotes and routes (requires anx-api-keyheader; keys are free through the affiliate program, issued after review) andhttps://api.thorchain.org/memoless/api/v1for memoless (instant) swaps (no API key required).
The UI also reads protocol metadata (pools, network parameters, THORNames, balances, inbound addresses) directly from public THORNode and Midgard APIs. The keyless path for agents is the MCP server below, which serves THORChain data from THORNode and Midgard.
Quickstart
No API key or registration is required. Fetch a BTC → ETH swap quote through the public MCP server:
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
}
}
}'Core MCP input amounts are integers in 1e8 base units (100000000 = 1 BTC). Parse the SSE JSON-RPC event and read result.structuredContent.data for the quote. Use prepare_swap with a confirmed destination for executable deposit instructions. Quotes, memos, and inbound addresses expire; always re-fetch before use.
MCP Server
Use the canonical THORChain MCP server at https://mcp.thorchain.org/mcp, published as org.thorchain/thorchain-mcp. No authentication is required. It speaks Streamable HTTP; send JSON-RPC over POST with Accept: application/json, text/event-stream and parse SSE data: events.
The live core server card owns the current tool inventory, version, protocol revisions, and capabilities. This site's server-card mirror serves that live card with THORChain branding. The full integration reference lives at /developers/mcp.
Selected read-only tools; call tools/list for the complete live inventory and current 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.
Illustrative SSE response; read structuredContent.data for the payload and _metadata for its source:
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}}"}]}}
This site's legacy /mcp URL permanently redirects to the canonical endpoint. It does not translate former tool names or parameters. Configure new clients with the canonical URL directly; core protocol behavior and rate limits belong to the core deployment.
The server never holds keys, signs, or submits transactions.
SDKs
- TypeScript / JavaScript —
@tcswap/sdk(npm): source. Published on npm. The full swap SDK — quotes and routing across THORChain and Maya, wallet connection, and transaction building — and the SDK this interface is itself built on. - Python —
thorchain-swap(PyPI): source. Source published in this repository. Read-only quote, pool, and network-summary helpers call the canonical THORChain MCP server at https://mcp.thorchain.org/mcp; support requests use this site's REST API. No API key, token, or sign-in. Supports JSON and SSE responses. Install directly from git — `pip install "git+https://github.com/thorchain/swap.thorchain#subdirectory=sdk/python"` — until the PyPI release is cut. - Go —
github.com/thorchain/swap.thorchain/sdk/go(Go modules): source. Source published in this repository and importable directly as a Go module. Read-only quote, pool, and network-summary helpers call the canonical THORChain MCP server at https://mcp.thorchain.org/mcp; support requests use this site's REST API. Supports JSON and SSE responses.
Full reference: /developers/sdks.
REST API
The public REST API is described by an OpenAPI 3.1 document at /.well-known/openapi.json (alias: /openapi.json).
POST /api/v1/newsletter— Subscribe an email address to THORChain Swap updates. (auth:none)GET /.well-known/status— Discovery endpoint status. (auth:none)
Idempotency: the POST endpoint accepts an Idempotency-Key header (any unique string, max 255 chars). A retry with the same key within one hour replays the original JSON response — marked with an Idempotency-Replayed: true response header — instead of re-executing the operation. 429 and 5xx outcomes are not stored, so retrying after them can succeed.
Versioning and deprecation: the API is versioned in the URL path — /api/v1/ is the canonical prefix, and unversioned /api/* paths are stable aliases of the newest major version. Breaking changes ship as a new /api/vN prefix with at least six months of overlap; endpoints scheduled for removal signal it with Deprecation and Sunset response headers and are announced on this page before retirement.
Authentication
Browsing, quoting, the public MCP server, and the support APIs are anonymous; there are no accounts, and users sign transactions in their own wallets (or use memoless swaps with no wallet connection).
This site runs no authorization server and issues no tokens — there is no /.well-known/oauth-protected-resource and no /.well-known/oauth-authorization-server to discover, so an MCP client that probes for authorization metadata finds none and connects directly. If a connector UI asks for an OAuth client ID or an API key for https://mcp.thorchain.org/mcp, leave it blank.
The aggregator quote API (https://api.thorchain.org/v1) is a different system: it takes an x-api-key, issued free through the affiliate program after a short review. That account also sets affiliate and service fee splits, generates the embeddable widget, and reports earnings.
See /developers/auth and auth.md.
Errors
Every non-2xx API response is JSON with a machine-readable code, a human-readable error, and a resolution hint:
{
"error": "Invalid email",
"code": "invalid_email",
"hint": "Provide a valid email address in the \"email\" field.",
"documentation": "https://swap.thorchain.org/developers"
}Rate limits return 429 with a Retry-After header (seconds). Unknown /api/* paths return a JSON 404 with code not_found.
Sandbox
The hosted core MCP endpoint uses mainnet. Test stagenet integrations with dedicated stagenet APIs or a separately configured core server:
- Stagenet THORNode API: stagenet-thornode.ninerealms.com
- Stagenet Midgard API: stagenet-midgard.ninerealms.com
THORChain Protocol Resources
This site is an interface to the THORChain protocol. Protocol-level development (memos, inbound addresses, quote endpoints, node operation) is documented at:
- THORChain developer docs (dev.thorchain.org)
- THORNode API reference
- Midgard API reference
- This interface's source code (with AGENTS.md instructions for AI coding agents)
Discovery Resources
- /llms.txt — index of agent resources
- /.well-known/mcp.json — live core MCP server-card mirror (also /mcp.json)
- https://registry.modelcontextprotocol.io/v0.1/servers/org.thorchain%2Fthorchain-mcp/versions/latest — official registry entry: org.thorchain/thorchain-mcp
- /llms-full.md — complete single-file agent reference (also at /llms-full.txt)
- /AGENTS.md — guidance for AI agents using this site
- /developers.md — this developer portal as markdown
- /.well-known/openapi.json — OpenAPI 3.1 description of the public REST API
- /.well-known/api-catalog — RFC 9727 API catalog (linkset)
- /.well-known/mcp/server-card.json — live core MCP server-card mirror with THORChain branding
- /.well-known/agent-card.json — A2A agent card
- /.well-known/agent-skills/index.json — published agent skills (navigation, quotes, pools, memoless swaps)
- /index.md — homepage as markdown; append .md to any content page URL
- /auth.md — authentication model for agents
- /pricing.md — pricing and per-swap fee model
- /?mode=agent — structured agent view of the homepage (JSON with Accept: application/json)
- /sitemap.xml — sitemap
- /robots.txt — crawl policy with AI Content-Signal
Support
- Email: [email protected]