# 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](https://swap.thorchain.org/openapi.json) (canonical alias: [https://swap.thorchain.org/.well-known/openapi.json](https://swap.thorchain.org/.well-known/openapi.json)), catalogued per RFC 9727 at [https://swap.thorchain.org/.well-known/api-catalog](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](https://swap.thorchain.org/developers/mcp) or the aggregator backend described in the [developer portal](https://swap.thorchain.org/developers).

## 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

```bash
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":"you@example.com"}'
```

## 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:

```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 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

## Related

- [OpenAPI description](https://swap.thorchain.org/openapi.json)
- [Authentication](https://swap.thorchain.org/developers/auth)
- [Webhooks and event polling](https://swap.thorchain.org/developers/webhooks)
- [SDKs](https://swap.thorchain.org/developers/sdks)