THORChain Swap API Authentication

How agents authenticate — and mostly do not have to — against THORChain Swap (https://swap.thorchain.org).

Which credential do I need?

Reading quotes, pools, or network state — nothing. Call https://swap.thorchain.org/mcp anonymously.
The same, at a higher rate limit — a client-credentials token from this site. Instant, no approval; see below.
Building a swap flow on the aggregator, earning affiliate fees, or embedding the widget — an x-api-key for https://api.thorchain.org/v1, issued free through the affiliate program at https://affiliate.thorchain.org after a short review. That is a different system with a different backend; nothing on this page issues or replaces that key.

Anonymous by default

There are no user accounts on this site. Browsing, the public MCP server, and the public REST endpoints are all anonymous and rate limited per client. Wallet connection and transaction signing happen in the user's own wallet; memoless ("instant") swaps need no wallet at all. Nothing on this site can move funds, so nothing on it needs a credential.

Optional client credentials

An agent that wants its own rate-limit budget — instead of sharing an IP bucket with every other caller behind the same egress — can register a client and exchange it for a bearer token. Registration is open: no email, no approval, no key handling.

1. Register (RFC 7591 dynamic client registration):

curl -s https://swap.thorchain.org/oauth/register \
  -H 'Content-Type: application/json' \
  -d '{"client_name":"my-agent","grant_types":["client_credentials"]}'

2. Exchange the credentials for a token (RFC 6749 client credentials):

curl -s https://swap.thorchain.org/oauth/token \
  -d 'grant_type=client_credentials' \
  -d 'client_id=<client_id>' \
  -d 'client_secret=<client_secret>' \
  -d 'scope=mcp:read'

3. Call the MCP server with it:

curl -s https://swap.thorchain.org/mcp \
  -H "Authorization: Bearer <access_token>" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Tokens are bearer tokens, scoped mcp:read, valid for one hour. They unlock exactly one thing: the higher rate-limit tier (600 requests per 10 minutes instead of 60). Requests without a token keep working. A token that is present but invalid or expired is rejected with 401 and a WWW-Authenticate header pointing at the protected-resource metadata.

Discovery metadata

Protected resource (RFC 9728): https://swap.thorchain.org/.well-known/oauth-protected-resource and https://swap.thorchain.org/.well-known/oauth-protected-resource/mcp
Authorization server (RFC 8414): https://swap.thorchain.org/.well-known/oauth-authorization-server
Agent auth block: https://swap.thorchain.org/auth.md

Partner API keys (the affiliate program)

The swap aggregator that powers this interface — https://api.thorchain.org/v1, quotes and routing across every supported provider — is x-api-key gated. Keys are free:

Register at https://affiliate.thorchain.org with your name, email, website, and Telegram, and verify the email.
The account is reviewed; the API key is issued once it is approved.
The same dashboard configures affiliate and service fee splits per provider, generates the embeddable swap widget, and reports earnings.

Use that key with `@tcswap/sdk`, which takes it as the uSwap API key. The memoless API and this site's MCP server need no key at all.

What is not offered

No authorization code flow, refresh tokens, or user login on this site — there are no user accounts here to log into.
No credential issued here grants the ability to move funds or sign on a user's behalf.
The tokens issued at /oauth/token are not aggregator API keys and cannot be used against https://api.thorchain.org/v1.

This page as markdown: /developers/auth.md