REST API 表面

Raydium 11 个公开 HTTP 服务的高层概览——各服务的用途、它们共享的约定（响应信封、认证、速率限制、缓存），以及如何为集成选择正确的服务。

本页内容由 AI 自动翻译，所有内容以英文版本为准。

查看英文版 →

端点级文档位于 API Reference 选项卡。 每个端点都有一个由 Mintlify 的 OpenAPI 游乐场驱动的交互式 Try it 面板——在浏览器中填入参数并直接命中实时主网（或 devnet，如果可用）。本页是叙述性伴读：存在哪些服务、何时使用哪个，以及贯穿所有服务的约定。如果你在寻找「GET /pools/info/ids 接受什么」，请点击 API Reference；如果你在寻找「我应该集成哪个服务」，继续阅读。

​

一览十一个服务

Raydium 运行十一个公开 HTTP 服务。每个服务都在 API Reference 选项卡中作为自己的组进行记录，并由支持交互式游乐场的 OpenAPI 规范提供支持。

服务	主网主机	测试网主机	提供内容
API v3	api-v3.raydium.io	api-v3-devnet.raydium.io	规范的流动性池 / 代币 / 配置 / 链信息读取 API。UI 和大多数集成者的默认入口。
Transaction API	transaction-v1.raydium.io	transaction-v1-devnet.raydium.io	服务端交换交易构造。
Perps API	api-perp-v1.raydium.io	—	Raydium Perps 前端的设置、资产元数据、RPC 选择。
LaunchLab Mint API	launch-mint-v1.raydium.io	launch-mint-v1-devnet.raydium.io	代币搜索、索引、排行榜、每个代币的元数据。
LaunchLab History API	launch-history-v1.raydium.io	launch-history-v1-devnet.raydium.io	LaunchLab 流动性池的交易历史和 OHLC K 线聚合。
LaunchLab Forum API	launch-forum-v1.raydium.io	launch-forum-v1-devnet.raydium.io	LaunchLab 发行的评论线程和 IPFS 上传。需要钱包签名。
LaunchLab Auth API	launch-auth-v1.raydium.io	launch-auth-v1-devnet.raydium.io	从钱包签名消息生成短期 ray-token JWT。Forum 必需。
Dynamic IPFS API	dynamic-ipfs.raydium.io	dynamic-ipfs-devnet.raydium.io	动态 NFT（CLMM 仓位等）的图像 / 元数据再生。
Owner API	owner-v1.raydium.io	owner-v1-devnet.raydium.io	每钱包仓位、余额、可领取奖励。
API v1（遗留）	api.raydium.io	—	为未迁移到 API v3 的客户端保留的遗留 /v1 和 /v2 路径。
Temp API	temp-api-v1.raydium.io	temp-api-v1-devnet.raydium.io	短期定制端点的暂存区。表面可能在无通知的情况下更改。

版本化存在于 v3 / v1 服务的主机名中——没有进一步的路径级版本化。重大变化以新主机形式发布并有重叠；团队已公开承诺任何 v3 → v4 迁移至少有 6 个月的重叠。

​

选择服务

如果你想要…	使用
读取流动性池元数据、价格、APR、费用配置	API v3
读取代币元数据（名称、符号、标志、小数、风险标签）	API v3 /mint/list、/mint/price
服务端构造交换 / 增加流动性 / 移除流动性交易	Transaction API
显示钱包的仓位（LP 代币、CLMM 仓位、农场质押）	Owner API
搜索 LaunchLab 代币、浏览排行榜、获取每个代币的元数据	LaunchLab Mint API
为 LaunchLab 流动性池渲染 K 线 / 蜡烛图	LaunchLab History API
在 LaunchLab 发行上发布或读取评论	LaunchLab Auth API → ray-token → LaunchLab Forum API
渲染 CLMM 仓位 NFT 图像	Dynamic IPFS API
显示 Perps UI 的期货市场设置或资产列表	Perps API
维护与 v1/v2 路径前缀客户端的兼容性	API v1（遗留）

​

跨服务约定

​

响应信封

除了 IPFS 之外，每个服务都返回相同的 JSON 信封：

{
  "id":      "uuid-v4-per-request",
  "success": true,
  "data":    { ... }
}

失败时：

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

某些服务另外包括 error.code 整数（API v3 使用它在次要版本之间的稳定错误标识符）。有关确切形状，请参见每个服务的概览页面。

​

认证

有两种模式：

• 无认证 —除 Forum 外的每个服务。通过 HTTPS 匿名访问它们。
• 钱包签名握手 — LaunchLab Forum API 必需。使用你的钱包签署形式为 time:<unix-seconds> 的 Solana ed25519 消息，将签名 + 钱包地址发送到 LaunchLab Auth API /request-token，获取 JWT，并在后续 forum 调用中将其作为 ray-token 请求头传递。

Mintlify 游乐场在发送 forum 请求前在认证面板中接受 ray-token；该值仅保存在你的浏览器中。

​

速率限制

所有主机都位于 Cloudflare 后面，每个源 IP 有渐进式速率限制。为集成者发布的指导：

超过发布限制的突发返回 HTTP 429 和 Retry-After 头。需要更高限制的聚合器或机器人应该联系 Raydium 团队，而不是直接敲打公共主机——针对程序 ID 运行自己的索引器也是读密集型工作负载的选项。

​

缓存和一致性

• 大多数 API v3 读端点在边缘缓存 5–60 秒；具体的 TTL 在每个端点的 API Reference 页面上注明。
• 缓存由索引器在观察到的接触程序事件时失效。
• 在大型重组或拥塞期间，API 的视图和链上状态之间可能有 1–2 slot 的差异。SDK 和直接 RPC 读取总是更及时的——如果客户端即将签署交易，通过 RPC 重新获取相关账户，永远不要盲目信任 API 值。

​

错误格式

错误以 HTTP 4xx/5xx 形式返回，使用相同的信封（success: false，填充的 msg）。API v3 另外包括稳定的 error.code：

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

error.code 在次要 API 版本中是稳定的；在客户端逻辑中将其视为主要信号，msg 作为用户可读的表面。

​

Mint 对参数约定

许多 API v3 端点接受 mint1=…&mint2=… 并要求 mint1 < mint2（升序公钥字节顺序）。这样 API 可以返回相同的规范流动性池，无论调用者的首选参数顺序如何。在构造 URL 前在客户端排序两个 mint——端点级文档在 API Reference 中重复此约束（如适用）。

​

推荐的客户端模式

1. 一次补充，懒惰刷新。 在应用加载时拉取 GET /main/info 和 GET /mint/list（均在 API v3 上），并以 1 小时 TTL 本地缓存。两者都是大量边缘缓存的，很少改变。
2. 在端点允许的地方进行批量操作。 GET /pools/info/ids?ids=… 接受逗号分隔列表——在一个请求中获取十个流动性池，而不是十个请求。
3. 避免热路径价格获取。 GET /mint/price 对 UI 渲染很好；永远不要在机器人中循环它。对于交易机器人，运行索引器或直接订阅 RPC programSubscribe 事件。
4. 镜像或代理以获得高吞吐量。 超过发布速率限制上限的任何内容都应从你自己的缓存层提供，而不是直接离开公共主机。对 transaction-v1 有持续 >120 req/min 的聚合器应该运行自己的报价 / 路由引擎。
5. 在签署前重新获取。 API 响应可能有 5–60 秒陈旧。为了在签署时获得实际正确的流动性池快照，通过 SDK 或直接 RPC getMultipleAccounts 调用重新读取相关账户。将 API 值视为查询提示，而不是结算源。
6. 使用 Transaction API 进行低摩擦集成。 如果你不想在客户端捆绑 SDK（移动原生、受限环境中的机器人），Transaction API 将为用户签署返回 base64 编码的版本化交易。它返回的 swapResponse 嵌入报价——将其视为对约 30 秒有效。

​

接下来去哪里

• 端点参考（交互式） — API Reference。每个服务都有自己的组；点击任何端点查看参数、响应形状、代码示例和 Try-it 面板。
• TypeScript SDK — sdk-api/typescript-sdk。SDK 在内部为几个路径消费 API v3；对于交易构造，它总是从 RPC 重新获取状态，永远不会盲目信任 API。
• Trade API 集成 — integration-guides/aggregator。将 Raydium 流动性连接到多 DEX 聚合器的模式。
• AI 友好文档 — sdk-api/ai-integration。需要调用这些 API 的 AI 编码代理的指针。