# AGENTS.md — THORChain Swap

Guidance for AI agents interacting with the public THORChain Swap web interface.

## When To Use This Site

- A user wants to swap native L1 assets (BTC, ETH, stablecoins, …) without bridges, wrapped tokens, or accounts.
- A user needs a live cross-chain swap quote, pool depths, or THORChain network status — use the MCP server below (no API key).
- A user wants to swap without connecting a wallet — the memoless (instant) swap flow sends funds to a deposit address.

Not a fit for: fiat on/off-ramps, NFTs, derivatives, or custodial accounts.

## What This Site Does

THORChain Swap (https://swap.thorchain.org) is a public web interface for native cross-chain swaps powered by THORChain and Maya Protocol.
There are no user accounts. Users either connect their own wallet in the browser and sign transactions locally, or swap without connecting a wallet at all via memoless ("instant") swaps — sending funds directly to a deposit address.

## Architecture and Data Sources

The application consists of two components:

- **UI** — this site (https://swap.thorchain.org).
- **Backend API** — the THORChain/Maya Protocol swap aggregator, which the UI queries for swap quotes and routing:
  - 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 (see https://swap.thorchain.org/auth.md).
  - https://api.thorchain.org/memoless/api/v1 — memoless ("instant") swaps without a connected wallet. No API key required.

The UI additionally reads protocol metadata (pools, network parameters, balances, THORNames, inbound addresses) directly from public THORNode and Midgard APIs.

Agents without an aggregator key can use the memoless API or the public MCP server below, which serves quote, pool, and network data from THORNode with no authentication.

## Developer Portal

Full developer documentation (quickstart, API reference, MCP server, auth scopes, error format, sandbox) lives at:

- HTML: https://swap.thorchain.org/developers
- Markdown: https://swap.thorchain.org/developers.md

## MCP Server

A public, unauthenticated, rate-limited MCP server (streamable HTTP, stateless, JSON responses) is available at:

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

Tools (read-only):

- `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` links a `ui://thorchain-swap/swap-quote` view via `_meta.ui.resourceUri`, so hosts that support MCP Apps can render quotes as an interactive panel. Hosts without MCP Apps support get plain JSON.

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

## Public Pages

- Swap: https://swap.thorchain.org/
- 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/

## Public REST APIs

Documented in the OpenAPI description (https://swap.thorchain.org/.well-known/openapi.json) and API catalog (https://swap.thorchain.org/.well-known/api-catalog):

- 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 and rate limited per client (429 with Retry-After when exceeded), and both accept an `Idempotency-Key` header so retries never duplicate a submission. The API is versioned in the URL path (/api/v1/); unversioned /api/* paths remain as stable aliases.
These are the site's own support endpoints; swap quotes are not served under https://swap.thorchain.org/api — use the MCP server or the aggregator backend described above.

## Safety Rules

- Never request, store, or infer private keys or seed phrases.
- Never execute swaps on behalf of a user; only users sign transactions in their own wallets.
- Treat quotes, balances, and transaction state as time-sensitive; re-fetch before presenting.
- A quote's memo and inbound address expire; never reuse them after expiry.
- Confirm destination addresses with the user before they submit any transaction.

## More Discovery

- https://swap.thorchain.org/llms.txt
- https://swap.thorchain.org/auth.md
- https://swap.thorchain.org/.well-known/agent-skills/index.json
- https://swap.thorchain.org/.well-known/agent-card.json
- Source code (with AGENTS.md for coding agents): https://github.com/thorchain/swap.thorchain