客户端初始化
使用环境变量
不要把配置写进源码。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 组合。