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.

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 not self-service — contact the maintainers) 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.

  • 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.

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

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 and Scopes

Browsing, quoting, and the support APIs are anonymous today; there are no accounts, and users sign transactions in their own wallets (or use memoless swaps with no wallet connection). The aggregator quote API (https://api.thorchain.org/v1) is the exception: it requires an x-api-key header. The OAuth 2.0 model below defines least-privilege scopes for when self-service credential issuance is enabled:

  • read:public — Read public discovery documents, quotes, pools, and network data.
  • submit:feedback — Submit newsletter subscriptions and bug reports.

See the OAuth authorization server metadata 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