# THORChain Developer Resources

THORChain developer resources for the swap interface — API docs, OpenAPI spec, auth docs, and MCP server — for THORChain Swap (https://swap.thorchain.ai), the public web interface for native cross-chain swaps powered by THORChain and Maya Protocol.

- HTML version: https://swap.thorchain.ai/developers
- Markdown version: https://swap.thorchain.ai/developers.md

## Named Developer Resources

Each topic has its own page, and each page has a markdown twin at the same URL plus `.md`:

- [THORChain Swap Quickstart](https://swap.thorchain.ai/developers/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](https://swap.thorchain.ai/developers/api) — 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](https://swap.thorchain.ai/developers/mcp) — 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](https://swap.thorchain.ai/developers/auth) — 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](https://swap.thorchain.ai/developers/sdks) — Official THORChain Swap client libraries for TypeScript, Python, and Go, generated from the published OpenAPI and MCP descriptions.
- [THORChain Swap Webhooks and events](https://swap.thorchain.ai/developers/webhooks) — 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` — swap quotes and routes across THORChain and Maya Protocol providers. Requires an `x-api-key` header; keys are free through the affiliate program at https://affiliate.thorchain.org (register, verify your email, key issued on approval).
  - `https://api.thorchain.org/memoless/api/v1` — 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:

```bash
curl -s https://swap.thorchain.ai/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):

- Endpoint: https://swap.thorchain.ai/mcp — JSON-RPC over POST; a plain GET returns the server card
- Server card: https://swap.thorchain.ai/.well-known/mcp/server-card.json (aliases: https://swap.thorchain.ai/.well-known/mcp.json, https://swap.thorchain.ai/mcp.json)
- Full reference: https://swap.thorchain.ai/developers/mcp

Read-only tools:

- `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 (`text/html;profile=mcp-app`), which MCP Apps-capable hosts render as an interactive quote view. The view is self-contained (no external scripts) and receives data via `ui/notifications/tool-result`.

The server never holds keys, signs, or submits transactions.

## SDKs

- **TypeScript / JavaScript** — `@tcswap/sdk` (npm): https://github.com/thorchain/TCSwap/tree/main/packages/sdk. 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): https://github.com/thorchain/swap.thorchain/tree/main/sdk/python. 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): https://github.com/thorchain/swap.thorchain/tree/main/sdk/go. 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: https://swap.thorchain.ai/developers/sdks

## REST API

Described by the OpenAPI 3.1 document at https://swap.thorchain.ai/.well-known/openapi.json (alias: https://swap.thorchain.ai/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, so network-failure retries never duplicate a subscription. 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 the 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 API key for `https://swap.thorchain.ai/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 at https://affiliate.thorchain.org after a short review. That same account sets affiliate/service fee splits, generates the embeddable widget, and reports earnings.

Details: https://swap.thorchain.ai/developers/auth and https://swap.thorchain.ai/auth.md

## Errors

Every non-2xx API response is JSON with a machine-readable `code`, human-readable `error`, and a resolution `hint`:

```json
{
  "error": "Invalid email",
  "code": "invalid_email",
  "hint": "Provide a valid email address in the \"email\" field.",
  "documentation": "https://swap.thorchain.ai/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:

- Stagenet THORNode API: https://stagenet-thornode.ninerealms.com
- Stagenet Midgard API: https://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: https://dev.thorchain.ai
- THORNode API: https://thornode.ninerealms.com/thorchain/doc
- Midgard API: https://midgard.ninerealms.com/v2/doc
- This interface's source code (with AGENTS.md instructions for AI coding agents): https://github.com/thorchain/swap.thorchain

## Discovery Resources

- [/llms.txt](https://swap.thorchain.ai/llms.txt) — index of agent resources
- [/.well-known/mcp.json](https://swap.thorchain.ai/.well-known/mcp.json) — MCP manifest alias (also /mcp.json and GET /mcp)
- [/llms-full.md](https://swap.thorchain.ai/llms-full.md) — complete single-file agent reference (also at /llms-full.txt)
- [/AGENTS.md](https://swap.thorchain.ai/AGENTS.md) — guidance for AI agents using this site
- [/developers.md](https://swap.thorchain.ai/developers.md) — this developer portal as markdown
- [/.well-known/openapi.json](https://swap.thorchain.ai/.well-known/openapi.json) — OpenAPI 3.1 description of the public REST API
- [/.well-known/api-catalog](https://swap.thorchain.ai/.well-known/api-catalog) — RFC 9727 API catalog (linkset)
- [/.well-known/mcp/server-card.json](https://swap.thorchain.ai/.well-known/mcp/server-card.json) — MCP server card
- [/.well-known/agent-card.json](https://swap.thorchain.ai/.well-known/agent-card.json) — A2A agent card
- [/.well-known/agent-skills/index.json](https://swap.thorchain.ai/.well-known/agent-skills/index.json) — published agent skills (navigation, quotes, pools, memoless swaps)
- [/index.md](https://swap.thorchain.ai/index.md) — homepage as markdown; append .md to any content page URL
- [/auth.md](https://swap.thorchain.ai/auth.md) — authentication model for agents
- [/pricing.md](https://swap.thorchain.ai/pricing.md) — pricing and per-swap fee model
- [/?mode=agent](https://swap.thorchain.ai/?mode=agent) — structured agent view of the homepage (JSON with Accept: application/json)
- [/sitemap.xml](https://swap.thorchain.ai/sitemap.xml) — sitemap
- [/robots.txt](https://swap.thorchain.ai/robots.txt) — crawl policy with AI Content-Signal

## Support

- Email: contact@thorchain.org