> ## Documentation Index
> Fetch the complete documentation index at: https://docs.raydium.io/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API surface

> High-level overview of Raydium's eleven public HTTP services — what each one does, the conventions they share (response envelope, auth, rate limits, caching), and how to pick the right service for an integration.

<Info>
  **Endpoint-level docs live in the [API Reference](/api-reference) tab.** Every endpoint there has an interactive **Try it** panel powered by Mintlify's OpenAPI playground — fill in parameters in the browser and hit live mainnet (or devnet, where available) directly. This page is the **narrative companion**: what services exist, when to use which, and the conventions that span all of them. If you are looking for "what does `GET /pools/info/ids` accept", click through to API Reference; if you are looking for "which service should I integrate", read on.
</Info>

## The eleven services at a glance

Raydium runs eleven public HTTP services. Each is documented as its own group in the [API Reference](/api-reference) tab and has an OpenAPI spec backing the interactive playground.

| Service                                                            | Mainnet host                   | Devnet host                           | What it serves                                                                                                |
| ------------------------------------------------------------------ | ------------------------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| [API v3](/api-reference/api-v3/overview)                           | `api-v3.raydium.io`            | `api-v3-devnet.raydium.io`            | Canonical pool / mint / config / chain-info read API. The default front door for the UI and most integrators. |
| [Transaction API](/api-reference/route-api-v2/overview)            | `transaction-v1.raydium.io`    | `transaction-v1-devnet.raydium.io`    | Server-side swap transaction construction.                                                                    |
| [Perps API](/api-reference/perp-api-v1/overview)                   | `api-perp-v1.raydium.io`       | —                                     | Settings, asset metadata, RPC selection for the Raydium Perps front end.                                      |
| [LaunchLab Mint API](/api-reference/launch-mint-v1/overview)       | `launch-mint-v1.raydium.io`    | `launch-mint-v1-devnet.raydium.io`    | Token search, indexes, leaderboards, per-mint metadata.                                                       |
| [LaunchLab History API](/api-reference/launch-history-v1/overview) | `launch-history-v1.raydium.io` | `launch-history-v1-devnet.raydium.io` | Trade history and OHLC k-line aggregates for LaunchLab pools.                                                 |
| [LaunchLab Forum API](/api-reference/launch-forum-v1/overview)     | `launch-forum-v1.raydium.io`   | `launch-forum-v1-devnet.raydium.io`   | Comment threads and IPFS uploads on LaunchLab launches. **Wallet-signed.**                                    |
| [LaunchLab Auth API](/api-reference/launch-auth-v1/overview)       | `launch-auth-v1.raydium.io`    | `launch-auth-v1-devnet.raydium.io`    | Mints short-lived `ray-token` JWTs from a wallet-signed message. Required by Forum.                           |
| [Dynamic IPFS API](/api-reference/dynamic-ipfs-v1/overview)        | `dynamic-ipfs.raydium.io`      | `dynamic-ipfs-devnet.raydium.io`      | Image / metadata regeneration for dynamic NFTs (CLMM positions, etc.).                                        |
| [Owner API](/api-reference/owner-api-v1/overview)                  | `owner-v1.raydium.io`          | `owner-v1-devnet.raydium.io`          | Per-wallet positions, balances, claimable rewards.                                                            |
| [API v1 (legacy)](/api-reference/api-v1/overview)                  | `api.raydium.io`               | —                                     | Legacy `/v1` and `/v2` paths kept live for clients that have not migrated to API v3.                          |
| [Temp API](/api-reference/temp-api-v1/overview)                    | `temp-api-v1.raydium.io`       | `temp-api-v1-devnet.raydium.io`       | Holding pen for short-lived bespoke endpoints. **Surface can change without notice.**                         |

Versioning lives in the **hostname** for the v3 / v1 services — there is no further path-level versioning. Breaking changes ship as a new host with overlap; the team has publicly committed to at least 6 months of overlap on any v3 → v4 migration.

## Pick a service

| If you want to…                                                         | Use                                                            |
| ----------------------------------------------------------------------- | -------------------------------------------------------------- |
| Read pool metadata, prices, APRs, fee configs                           | **API v3**                                                     |
| Read mint metadata (name, symbol, logo, decimals, risk tags)            | **API v3** `/mint/list`, `/mint/price`                         |
| Build a swap / add-liquidity / remove-liquidity transaction server-side | **Transaction API**                                            |
| Show a wallet's positions (LP tokens, CLMM positions, farm stakes)      | **Owner API**                                                  |
| Search LaunchLab tokens, browse leaderboards, fetch per-mint metadata   | **LaunchLab Mint API**                                         |
| Render a k-line / candlestick chart for a LaunchLab pool                | **LaunchLab History API**                                      |
| Post or read comments on a LaunchLab launch                             | **LaunchLab Auth API** → `ray-token` → **LaunchLab Forum API** |
| Render a CLMM position NFT image                                        | **Dynamic IPFS API**                                           |
| Show futures market settings or asset lists for the Perps UI            | **Perps API**                                                  |
| Maintain compatibility with a v1/v2 path-prefixed client                | **API v1 (legacy)**                                            |

## Cross-cutting conventions

### Response envelope

Every service except IPFS returns the same JSON envelope:

```json theme={null}
{
  "id":      "uuid-v4-per-request",
  "success": true,
  "data":    { ... }
}
```

On failure:

```json theme={null}
{
  "id":      "uuid-v4-per-request",
  "success": false,
  "msg":     "human-readable error string",
  "data":    null
}
```

Some services additionally include an `error.code` integer (API v3 uses this for stable error identifiers across minor versions). See each service's overview page for the exact shape.

### Authentication

Two patterns appear:

* **No auth** — every service except Forum. Hit them anonymously over HTTPS.
* **Wallet-signed handshake** — required by **LaunchLab Forum API**. Sign a Solana ed25519 message of the form `time:<unix-seconds>` with your wallet, send the signature + wallet address to **LaunchLab Auth API** `/request-token`, receive a JWT back, and pass it as the `ray-token` request header on subsequent forum calls.

The Mintlify playground accepts `ray-token` in the auth panel before sending forum requests; the value is held in your browser only.

### Rate limits

All hosts sit behind Cloudflare with progressive rate limiting per source IP. Published guidance for integrators:

Bursts above the published limits return `HTTP 429` with a `Retry-After` header. Aggregators or bots that need higher limits should contact the Raydium team rather than hammering the public hosts — running your own indexer against the on-chain program IDs is also an option for read-heavy workloads.

### Caching and consistency

* Most API v3 read endpoints are cached at the edge for 5–60 seconds; specific TTLs are noted on each endpoint's API Reference page.
* The cache is invalidated by the indexer on program-touching events it observes.
* During large reorgs or congestion, there can be a 1–2 slot divergence between the API's view and on-chain state. **The SDK and direct RPC reads are always more current** — if a client is about to sign a transaction, re-fetch the relevant accounts via RPC, never trust an API value blind.

### Error format

Errors come back as HTTP 4xx/5xx with the same envelope (`success: false`, populated `msg`). API v3 additionally includes a stable `error.code`:

```json theme={null}
{
  "id":      "uuid-v4-per-request",
  "success": false,
  "msg":     "Pool not found",
  "error":   { "code": 40401, "message": "Pool not found" }
}
```

The `error.code` is stable across minor API versions; treat it as the primary signal in client logic and `msg` as the human-readable surface.

### Mint-pair argument convention

Many API v3 endpoints accept `mint1=…&mint2=…` and require `mint1 < mint2` (ascending pubkey byte order). This is so the API can return the same canonical pool regardless of caller's preferred argument order. Sort the two mints client-side before building the URL — endpoint-level docs in [API Reference](/api-reference) repeat this constraint where it applies.

## Recommended client patterns

1. **Hydrate once, refresh lazily.** Pull `GET /main/info` and `GET /mint/list` (both on API v3) at app load and cache locally with a 1-hour TTL. Both are heavily edge-cached and rarely change.
2. **Bulk where the endpoint allows it.** `GET /pools/info/ids?ids=…` accepts a comma-separated list — fetch ten pools in one request, not ten requests.
3. **Avoid hot-path price fetches.** `GET /mint/price` is fine for UI rendering; never loop it in a bot. For trading bots, run an indexer or subscribe to RPC `programSubscribe` events directly.
4. **Mirror or proxy for high throughput.** Anything over the published rate-limit ceiling should be served from your own cache layer, not directly off the public hosts. Aggregators with sustained `>120 req/min` against `transaction-v1` should be running their own quote / route engine.
5. **Re-fetch right before signing.** API responses can be 5–60s stale. For an actually-correct pool snapshot at sign time, re-read the relevant accounts via the SDK or a direct RPC `getMultipleAccounts` call. Treat API values as a lookup hint, not a settlement source.
6. **Use the Transaction API for low-friction integration.** If you do not want to bundle the SDK in your client (mobile native, bot in a constrained environment), the Transaction API will return a base64-encoded versioned transaction for the user to sign. The `swapResponse` it returns embeds a quote — treat it as valid for \~30 seconds.

## Where to go next

* **Endpoint reference (interactive)** — [API Reference](/api-reference). Every service has its own group; click any endpoint for parameters, response shape, code samples, and a Try-it panel.
* **TypeScript SDK** — [`sdk-api/typescript-sdk`](/sdk-api/typescript-sdk). The SDK consumes API v3 internally for several paths; for transaction building it always re-fetches state from RPC, never trusts the API blind.
* **Trade API integration** — [`integration-guides/aggregator`](/integration-guides/aggregator). Patterns for wiring Raydium liquidity into a multi-DEX aggregator.
* **AI-friendly docs** — [`sdk-api/ai-integration`](/sdk-api/ai-integration). Pointers for AI coding agents that need to call these APIs.