THORChain Swap REST API Reference

The public REST API of THORChain Swap (https://swap.thorchain.org). Described by an OpenAPI 3.1 document at https://swap.thorchain.org/openapi.json (canonical alias: https://swap.thorchain.org/.well-known/openapi.json), catalogued per RFC 9727 at https://swap.thorchain.org/.well-known/api-catalog.

These are the site's own support endpoints. Swap quotes are not served here — use the MCP server or the aggregator backend described in the developer portal.

Endpoints

POST /api/v1/newsletter — Subscribe an email address to THORChain Swap updates. (auth: none)
POST /api/v1/report-bug — Submit a bug report or feature request. (auth: none)
POST /oauth/register — Register an OAuth client (RFC 7591) for the higher MCP rate-limit tier. (auth: none)
POST /oauth/token — Exchange client credentials for a one-hour bearer token (scope mcp:read). (auth: client credentials)
GET /.well-known/status — Discovery endpoint status. (auth: none)

Example

curl -s https://swap.thorchain.org/api/v1/report-bug \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 5f1c1a2e-report-1' \
  -d '{"description":"Quote refresh spins forever on BTC to ETH","type":"bug","email":"[email protected]"}'

Idempotency

Both POST endpoints accept an Idempotency-Key header (any unique string, max 255 characters). A retry with the same key within one hour replays the original JSON response and marks it with Idempotency-Replayed: true instead of re-executing the operation. 429 and 5xx outcomes are not stored, so retrying after those can still succeed.

Errors

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

{
  "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 in seconds. Unknown /api/* paths return a JSON 404 with code not_found, never the HTML error page.

Versioning and deprecation

/api/v1/ is the canonical prefix; 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 the developer portal first.

Sandbox

Test against THORChain stagenet before touching mainnet funds:

Stagenet THORNode API: https://stagenet-thornode.ninerealms.com
Stagenet Midgard API: https://stagenet-midgard.ninerealms.com

This page as markdown: /developers/api.md