THORChain SwapOpen the swap interface

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 — The THORChain Swap MCP server: streamable HTTP endpoint, server card, tool parameter schemas for get_swap_quote, list_pools and get_network_status, MCP Apps support, and rate limits.
  • 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 — Official THORChain Swap client libraries for TypeScript, Python, and Go, generated from the published OpenAPI and MCP descriptions.
  • 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/v1 for swap quotes and routes (requires an x-api-key header; keys are free through the affiliate program, issued after review) and https://api.thorchain.org/memoless/api/v1 for 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 quote, pool, and network data from THORNode.

Quickstart

No API key or registration is required. Fetch a BTC → ETH swap quote through the public MCP server:

curl -s https://swap.thorchain.org/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_swap_quote",
      "arguments": {
        "from_asset": "BTC.BTC",
        "to_asset": "ETH.ETH",
        "amount": "100000000"
      }
    }
  }'

Amounts are strings in 1e8 base units (100000000 = 1 BTC). Pass a destination address to receive a usable transaction memo. Quotes, memos, and inbound addresses expire; always re-fetch before use.

MCP Server

A public, unauthenticated, rate-limited MCP server (streamable HTTP, stateless, JSON responses) is available at https://swap.thorchain.org/mcp. Its server card is published at /.well-known/mcp/server-card.json. Aliases: /.well-known/mcp.json, /mcp.json, and a plain GET /mcp. The full reference lives at /developers/mcp.

  • get_swap_quote — Fetch a THORChain swap quote for an asset pair (amounts in 1e8 base units).
  • list_pools — List liquidity pools with status, depths, and USD asset price.
  • get_network_status — Current THORChain network parameters.

The server supports MCP Apps (io.modelcontextprotocol/ui): get_swap_quote declares _meta.ui.resourceUri pointing at the ui://thorchain-swap/swap-quote resource, which MCP Apps-capable hosts render as an interactive quote view.

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, covering the keyless public surfaces of this site — no API key, token, or sign-in. 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, covering the keyless public surfaces of this site, and importable as a Go module directly from the repository path.

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)
  • POST /api/v1/report-bug — Submit a bug report or feature request. (auth: none)
  • GET /.well-known/status — Discovery endpoint status. (auth: none)

Idempotency: both POST endpoints accept 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://swap.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

Test integrations against THORChain stagenet before touching mainnet funds:

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:

Discovery Resources

Support