Skip to main content
RGB Lightning DEX API 用于与 RGB 闪电服务提供商（RGB-LSP）交互，后者按请求提供流动性并支持交换功能。交换协议采用接单方-做市方模型：客户端为交易对请求实时报价，并基于报价发起交换。该 API 同时支持 RGB LSPS1（Lightning Service Provider Specification），用于管理通道和流动性服务。

​
核心特性

  • RGB LSPS1（Lightning Service Provider Specification）支持：流动性服务与交换功能。
  • 实时市场数据：基于 WebSocket 的请求/响应式报价推送（quote_request/quote_response）。
  • 交换协议：接单方-做市方模型，用于发起和执行交换。
  • 资产与交易对管理：完整的 API，用于获取支持的资产和交易对。
继续阅读快速开始。

​
两个子 API

KaleidoSwap API 分为两个彼此独立的服务： Maker API 可公开访问，负责全部交易和流动性操作。RLN API 是直接由你自己的 RGB Lightning Node 根路径提供的 REST API（例如 http://<node>:3001/nodeinfo），需要运行一个节点实例。

​
我该用哪个 API？

下方的 交互式 API 演练场 运行在 signet 环境（https://api.signet.kaleidoswap.com）。请用它来探索和测试。生产环境请在主网地址可用后改用主网 URL。

​
认证

当前状态：所有 Maker API 接口端点均支持匿名访问。Bearer API 密钥（Authorization: Bearer <token>）目前已被接受并记录归属 —— 密钥携带 quote:read（市场数据与报价）和 swap:execute（交换发起/执行）等作用域 —— 但强制校验正在逐步上线，因此不带密钥的请求仍会被正常处理。API 演练场已预先配置 bearer 认证。 即将上线：一旦开启强制校验，缺失或无效密钥的请求将收到 401 响应。集成方现在就应开始发送 API 密钥，以便提前就绪。

​
基础响应格式

所有 API 响应遵循统一的 JSON 结构。成功响应直接返回请求的数据，形式为 JSON 对象或数组。错误使用三种信封格式之一。 应用错误（参数无效、资源缺失、冲突、速率限制、服务器错误）返回结构化信封：
请求校验错误（schema 校验失败，HTTP 422）返回 FastAPI 的校验信封：
遗留错误：少数接口端点的部分 400 响应仍是一个裸的 detail 对象，不含 error_code 或 request_id —— 例如 /market/quote 上不受支持的路由，或 /market/pairs 上格式错误的 pair_ticker 过滤条件：
HTTP 状态码遵循标准约定： 完整的错误码列表见错误处理。

​
速率限制

速率限制适用于所有 API 接口端点。超出限制的请求会收到 429 Too Many Requests 响应。具体限制因接口端点和环境而异。构建集成时，请为重试实现指数退避，并尽可能在本地缓存静态数据（资产、交易对）。

​
使用 SDK

除了直接调用 REST API，你也可以使用官方 KaleidoSDK 库，它们对这些接口端点做了封装，提供类型安全和便捷方法：

TypeScript SDK

从 OpenAPI 规范自动生成的类型化客户端，提供 client.maker.* 和 client.rln.* 子客户端

Python SDK

同步 Python 客户端，使用 Pydantic 模型，采用相同的子客户端架构