Skip to main content

客户端初始化

使用环境变量

不要把配置写进源码。SDK 不会自动加载环境变量 —— 请自行读取后传给 create()。 约定的变量名以及两种语言的完整示例见安装。

使用单例客户端

只创建一个客户端实例,并在整个应用中复用:

错误处理

始终处理错误

把 SDK 调用包在 try/catch 中,并针对具体错误类型分别处理。下面给出的是最起码值得区分的几类;完整版本见故障排查。

检查是否可重试

不要盲目重试。每个错误都提供 isRetryable() / is_retryable(),其中已经编码了哪些失败在第二次尝试时可能成功 —— 请使用它,而不要自己去匹配状态码。 完整的异常层级结构、按状态码划分的可重试性表格,以及现成的指数退避封装,见故障排查。

异步模式

TypeScript:并行请求

对互不依赖的请求使用 Promise.all:
当你希望拿到部分结果时,使用 Promise.allSettled:

Python:串行执行并从错误中恢复

金额处理

调用 API 时一律使用原始单位

API 只接受原始(最小单位)金额,不接受展示金额。构造报价请求前用 parseRawAmount / parse_raw_amount 转换,展示给用户前再用 toDisplayAmount / to_display_amount 转换回来。 这两个函数的说明见工具函数。

多资产应用请使用 PrecisionHandler

一旦涉及多种资产,每次调用都手工传入精度正是舍入错误的来源。PrecisionHandler 会从资产元数据中读取精度,让你按资产 ID 转换。 如何创建以及完整方法列表见工具函数。

节点操作

只有在创建客户端时提供了节点 URL,client.rln 才可用,因此每次节点调用前都要用 hasNode() / has_node() 做检查。在 Python 中,未配置节点 URL 时访问 client.rln 会抛出 NodeNotConfiguredError。 两种语言的检查写法见快速上手。

WebSocket

用完后取消订阅

streamQuotes / streamQuotesByTicker 会返回一个取消订阅函数。一旦不再需要报价就立刻调用它 —— 组件卸载时、页面跳转时,或用户关闭该交易对时。不调用会造成内存泄漏,并让无人读取的报价流量持续占用连接。 这一条以及其他流式订阅的注意事项见 WebSocket。

处理重连

WSClient 会自行以指数退避重连,因此你这边要做的是把状态呈现给用户:收到 disconnected 时显示「正在重连」提示,收到 connected 时重新请求报价,并把 maxReconnectExceeded 当作硬性错误而非短暂抖动来处理。 事件列表与重连配置见 WebSocket。

安全

切勿在客户端代码中暴露 API 密钥

API 密钥只应在服务端使用。浏览器应用请通过你自己的后端代理 API 调用。

校验用户输入

发送到 API 之前,务必校验金额和地址:
订单规模限额位于每个资产的 endpoints 列表中(按层给出的 TradingLimits);pair.routes 只告诉你存在哪些 from_layer -> to_layer 组合。

性能

缓存静态数据

资产和交易对很少变化。缓存它们以减少 API 调用: