API 文档
RateON Exchange API v1
本文档说明如何将 RateON 兑换服务集成到钱包、监控平台、应用程序或合作伙伴服务中。通过 API，您可以获取兑换方向、计算金额、创建订单并跟踪订单状态。
https://rateon.io/api/userapi/v1/{method}
兑换方向
创建订单
状态跟踪
Endpoint 格式
https://rateon.io/api/userapi/v1/{method}
Content type
请求体参数建议使用 application/x-www-form-urlencoded。
curl -X POST "https://rateon.io/api/userapi/v1/test"
-H "API-LOGIN: YOUR_API_LOGIN"
-H "API-KEY: YOUR_API_KEY"
-H "API-LANG: en_US"
| Header | 必填 | 说明 |
|---|---|---|
API-LOGIN | 是 | 为您的集成账户签发的 API login。 |
API-KEY | 是 | 为您的集成账户签发的私有 API key。 |
API-LANG | 否 | 强制指定响应语言。示例值：en_US、ru_RU。 |
加载货币和方向
调用 get_direction_currencies 和 get_directions，用于显示可用的兑换交易对。
获取方向详情
调用 get_direction，获取汇率、储备、限额、手续费和必填字段。
计算金额
在创建订单前立即调用 get_calc，计算当前的发送和接收金额。
创建并跟踪订单
调用 create_bid，然后使用 bid_info、get_exchanges 或 callbacks 跟踪状态。
1. 构建交易对选择
使用 get_direction_currencies 和 get_directions 获取货币、交易对和 direction_id。
2. 渲染动态字段
使用 get_direction 渲染必填字段 give_fields、get_fields 和 dir_fields。
3. 提交前计算
在创建订单前立即使用 get_calc 显示最新金额并检测可能的金额变化。
4. 创建订单并保存 ID
使用 create_bid 并保存返回的 id、hash、status 和支付操作数据。
5. 跟踪状态
使用 callback_url 接收 push 通知，然后通过 bid_info 或 get_exchanges 验证状态。
6. 遵守 API actions
仅当返回的 api_actions 明确允许 API 操作时，才调用 pay_bid 和 cancel_bid。
| 方法 | 用途 | 典型使用场景 |
|---|---|---|
test | 检查 API 访问权限。 | 首先使用它来验证 credentials 和 IP allowlist。 |
get_direction_currencies | 返回可用于兑换的货币。 | 构建货币选择器。 |
get_directions | 返回可用的兑换方向。 | 构建交易对列表并获取 direction_id。 |
get_direction | 返回某个方向的详细信息。 | 显示汇率、限额、储备和必填字段。 |
get_calc | 计算兑换金额。 | 在创建订单前显示当前金额。 |
create_bid | 创建兑换订单。 | 提交最终兑换请求。 |
bid_info | 返回一个通过 API 创建的订单的支付信息和状态。 | 通过 id 或 hash 查询。 |
get_exchanges | 返回当前 API key 创建的订单。 | 显示订单历史或同步状态。 |
pay_bid | 在允许时将订单标记为已支付。 | 仅当 api_actions.pay = api 时使用。 |
cancel_bid | 在允许时取消订单。 | 仅当 api_actions.cancel = api 时使用。 |
请求参数
无必填参数。
可选参数
currency_id_give、currency_id_get。
响应
返回发送端和接收端可用的货币。使用此方法构建货币选择器。
可选参数
currency_id_give、currency_id_get。
响应
每个方向包含 direction_id、发送/接收货币 ID、货币名称和 logo。
必填参数
direction_id — 兑换方向 ID。
响应字段
使用 reserve、course_give、course_get、min_give、max_give、min_get、max_get、give_fields、get_fields 和 dir_fields 等响应字段。
必填参数
direction_id、calc_amount、calc_action。
calc_action 值
1 发送金额，2 接收金额，3 含手续费的发送金额，4 含手续费的接收金额。
响应字段
使用 sum_give、sum_give_com、sum_get、sum_get_com、com_give、com_get、限额和 changed 标志。
主要参数
direction_id、calc_amount、calc_action、account1、account2、自定义字段 cf1–cf99。
可选参数
api_id、partner_id、callback_url。如果希望 RateON 在订单状态变化时通知您的服务器，请使用 callback_url。
响应字段
保存返回的 id 和 hash。使用 status、status_title、金额字段、支付说明和 api_actions。
参数
发送 id 或 hash。在收到 callback notifications 后，或用户打开订单页面时使用此方法。
可选筛选条件
start_time、end_time、ip、id、api_id、status_history、limit、offset。
api_actions.pay
如果值为 api，钱包可以调用 pay_bid。如果返回支付链接或支付说明，请展示给用户。
api_actions.cancel
如果值为 api，钱包可以调用 cancel_bid。否则，该订单可能无法取消。
api_actions。某些操作可能由 merchant modules 自动处理，或对特定订单不可用。Callbacks 应作为 server-to-server 通知使用，表示订单可能发生了变化。钱包在更新用户界面之前，应始终通过 API 验证最终状态。
启用 callbacks
调用 create_bid 时传递 callback_url。该 URL 必须可通过 HTTPS 访问，并能够接收来自 RateON 的 POST 请求。
接收 callback 数据
根据所选方向和订单字段，callback payload 可能包含 bid_id、account1、account2 以及自定义订单字段 cf1–cf99。
验证订单状态
收到 callback 后，使用订单 id 或 hash 调用 bid_info。如果需要同步多个订单，请使用 get_exchanges。
更新钱包界面
仅在通过 API 验证后更新订单页面。这样可以避免 callback 延迟、重复或重试时导致错误的状态变更。
bid_info 或 get_exchanges 确认。| 错误 | 可能原因 | 建议操作 |
|---|---|---|
Api disabled | Credentials 不正确或 API 访问已禁用。 | 检查 API-LOGIN、API-KEY、API 访问权限和 IP allowlist。 |
Empty response | 请求的数据未找到或参数不正确。 | 检查必填参数和 ID。 |
No bid exists | 请求的订单不存在。 | 检查订单 id 或 hash。 |
Method not supported | 所选 API 方法未为此 API key 启用。 | 申请所需方法的访问权限。 |
Direction not found | 请求的兑换方向无法通过 API 使用。 | 检查方向可用性和 API 权限。 |
FAQ
create_bid 前立即调用 get_calc，以计算最新的兑换金额。bid_info 查询单个订单，使用 get_exchanges 查询订单历史，或在创建订单时传递 callback_url。