# 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.org), the public web interface for native cross-chain swaps powered by THORChain and Maya Protocol.

- HTML version: https://swap.thorchain.org/developers
- Markdown version: https://swap.thorchain.org/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` — swap quotes and routes across THORChain and Maya Protocol providers. Requires an `x-api-key` header; keys are not self-service (contact the maintainers).
  - `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.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):

- Endpoint: https://swap.thorchain.org/mcp
- Server card: https://swap.thorchain.org/.well-known/mcp-server-card

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.

## REST API

Described by the OpenAPI 3.1 document at https://swap.thorchain.org/.well-known/openapi.json (alias: https://swap.thorchain.org/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, so network-failure retries never duplicate a subscription or report. 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 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.

- Authorization server metadata: https://swap.thorchain.org/.well-known/oauth-authorization-server
- Details: https://swap.thorchain.org/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.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:

- 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.org
- 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.org/llms.txt) — index of agent resources
- [/llms-full.md](https://swap.thorchain.org/llms-full.md) — complete single-file agent reference (also at /llms-full.txt)
- [/AGENTS.md](https://swap.thorchain.org/AGENTS.md) — guidance for AI agents using this site
- [/developers.md](https://swap.thorchain.org/developers.md) — this developer portal as markdown
- [/.well-known/openapi.json](https://swap.thorchain.org/.well-known/openapi.json) — OpenAPI 3.1 description of the public REST API
- [/.well-known/api-catalog](https://swap.thorchain.org/.well-known/api-catalog) — RFC 9727 API catalog (linkset)
- [/.well-known/mcp-server-card](https://swap.thorchain.org/.well-known/mcp-server-card) — MCP server card
- [/.well-known/agent-card.json](https://swap.thorchain.org/.well-known/agent-card.json) — A2A agent card
- [/.well-known/agent-skills/index.json](https://swap.thorchain.org/.well-known/agent-skills/index.json) — published agent skills
- [/.well-known/oauth-authorization-server](https://swap.thorchain.org/.well-known/oauth-authorization-server) — OAuth 2.0 authorization server metadata
- [/auth.md](https://swap.thorchain.org/auth.md) — authentication model for agents
- [/sitemap.xml](https://swap.thorchain.org/sitemap.xml) — sitemap
- [/robots.txt](https://swap.thorchain.org/robots.txt) — crawl policy with AI Content-Signal

## Support

- Email: contact@thorchain.org
- Discord: https://discord.gg/thorchaincommunity
- Bug reports and feature requests: `POST /api/report-bug`