# THORChain Swap — Agent Library

The complete reference for AI agents using THORChain Swap (https://swap.thorchain.org), the public web interface for native cross-chain swaps powered by THORChain and Maya Protocol. Everything here is public; nothing requires authentication.

## What This Site Does

THORChain Swap swaps native layer-1 assets (BTC, ETH, stablecoins, and more) directly between chains — no bridges, no wrapped tokens, no order books, and no user accounts. Swaps settle in native assets on their own chains. Users either connect their own wallet and sign locally, or swap without connecting a wallet at all via memoless ("instant") swaps: they send funds to a deposit address and receive the swapped asset at their destination address.

## When To Use

- A user wants to swap native L1 assets without bridges, wrapped tokens, or custodial accounts.
- A user needs a live cross-chain swap quote, pool depths, or THORChain network status (use the MCP server; no API key).
- A user wants to swap without connecting a wallet (memoless flow).

Not a fit for: fiat on/off-ramps, NFTs, derivatives, or custodial account management. Never attempt to execute a swap on a user's behalf; users sign in their own wallets or send funds themselves.

## Architecture and Data Sources

Two components:

- **UI** — https://swap.thorchain.org
- **Backend API** — the THORChain/Maya swap aggregator: https://api.thorchain.org/v1 for quotes and routing (requires an `x-api-key` header; keys are not self-service) and https://api.thorchain.org/memoless/api/v1 for memoless swaps (no key).

Protocol metadata (pools, network parameters, THORNames, balances, inbound addresses) comes from public THORNode and Midgard APIs. Keyless agent access to quotes, pools, and network data: the MCP server below.

## Deep Links (URL Scheme)

Hand users a prefilled swap URL:

```
https://swap.thorchain.org/sell-BTC-buy-ETH
https://swap.thorchain.org/sell-BTC.BTC-buy-ETH.USDC
```

The path pattern is `/sell-<asset>-buy-<asset>`. Native gas assets may use just the ticker; tokens use `CHAIN.TICKER` (the full identifier with the contract-address suffix is also accepted).

## Asset Notation and Amounts

- Assets use `CHAIN.SYMBOL` notation: `BTC.BTC`, `ETH.ETH`, `ETH.USDC-0XA0B86991C6218B36C1D19D4A2E9EB0CE3606EB48` (token contract appended after a hyphen, uppercase).
- Amounts across THORChain APIs are strings in 1e8 base units regardless of the asset's native decimals: `"100000000"` = 1 BTC = 1 ETH = 1 RUNE.

## Quote Semantics

- Quotes are indicative and time-sensitive; re-fetch before presenting.
- A quote with a `destination` address includes a usable `memo` and `inbound_address`. Both expire at `expiry` (unix seconds) — never reuse them after expiry.
- `expected_amount_out` is the estimate after fees; `fees` itemizes them; `slippage_bps` is the price impact.
- `recommended_min_amount_in` is the smallest economically sensible input; below it, fees dominate.
- Streaming swaps (`streaming_interval` blocks between sub-swaps) trade speed for better pricing on large amounts.

## MCP Server

Public, unauthenticated, rate-limited MCP server (streamable HTTP, stateless, JSON responses, POST only):

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

Read-only tools:

- `get_swap_quote` — swap quote for an asset pair (1e8 base units; optional `destination`, `streaming_interval`)
- `list_pools` — liquidity pools with status, depths, and USD asset price
- `get_network_status` — current THORChain network parameters

Example:

```bash
curl -s https://swap.thorchain.org/mcp \
  -H 'Content-Type: 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"}}}'
```

The server supports MCP Apps (io.modelcontextprotocol/ui): `get_swap_quote` links the `ui://thorchain-swap/swap-quote` view via `_meta.ui.resourceUri`; hosts without MCP Apps get plain JSON. The server never holds keys, signs, or submits transactions.

## REST API

Described by OpenAPI 3.1 at https://swap.thorchain.org/.well-known/openapi.json. Versioned in the URL path; `/api/v1/` is canonical and unversioned `/api/*` paths are stable aliases.

- `POST /api/v1/newsletter` — subscribe an email address to updates
- `POST /api/v1/report-bug` — submit a bug report or feature request

Both are unauthenticated, rate limited per client (429 with Retry-After), and accept an `Idempotency-Key` header: a retry with the same key within one hour replays the original response (`Idempotency-Replayed: true`) instead of re-executing. Every non-2xx response is JSON with `error`, `code`, `hint`, and `documentation` fields. Swap quotes are NOT served under https://swap.thorchain.org/api — use the MCP server or the aggregator backend.

## Authentication

Browsing, quoting, and the support APIs are anonymous. Wallet connection and signing happen in user-controlled wallets in the browser; memoless swaps need no wallet. OAuth scopes (`read:public`, `submit:feedback`) are declared for future self-service issuance — see https://swap.thorchain.org/auth.md.

## Discovery Endpoints

- https://swap.thorchain.org/llms.txt — index of agent resources
- https://swap.thorchain.org/AGENTS.md — agent guidance and safety rules
- https://swap.thorchain.org/developers — developer portal (markdown: /developers.md)
- https://swap.thorchain.org/.well-known/openapi.json — OpenAPI 3.1 description
- https://swap.thorchain.org/.well-known/api-catalog — RFC 9727 API catalog
- https://swap.thorchain.org/.well-known/mcp-server-card — MCP server card
- https://swap.thorchain.org/.well-known/agent-card.json — A2A agent card
- https://swap.thorchain.org/.well-known/agent-skills/index.json — agent skills index
- https://swap.thorchain.org/auth.md — authentication model
- Source code (with AGENTS.md for coding agents): https://github.com/thorchain/swap.thorchain

## Other Interfaces

- Pool: https://pool.thorchain.org/
- Bond: https://bond.thorchain.org/
- Memo: https://memo.thorchain.org/
- TCY: https://tcy.thorchain.org/
- THORName: https://thorname.thorchain.org/

## Safety Rules

1. Never request, store, or infer private keys or seed phrases.
2. Never execute swaps on behalf of a user — only users sign transactions in their own wallets.
3. Treat quotes, balances, and transaction state as time-sensitive; re-fetch before presenting.
4. Never reuse a quote's `memo` or `inbound_address` after its `expiry`.
5. Confirm destination addresses with the user before they submit any transaction.

## Support

- Email: contact@thorchain.org
- Bug reports: `POST /api/v1/report-bug`