Home
API Reference

概述与鉴权

一、服务概述

Legend Gateway 提供完整、安全的 RESTful API，包含完整的 KYC 流程，支持法币与加密货币的兑换及账户管理。

二、环境与地址

环境基础 URL用途
沙箱环境https://sandboxapi.legendtrading.com用于集成测试与功能验证
生产环境https://api.legendtrading.com正式业务接口，处理真实交易与资金

重要提示：沙箱与生产环境完全隔离，请勿混用。请务必在完成充分测试后切换至生产环境。

三、认证与请求规范

1. Token 申请流程

所有 API 接口均为私有接口，调用需提供有效访问令牌。令牌的获取方式、以及随令牌生效的 IP 白名单配置方式，取决于环境：

环境Token 获取方式IP 白名单配置方式
沙箱环境在开发者工具（DevTools）自助生成在开发者工具（DevTools）自助配置
生产环境向 Legend 申请由 Legend 按申请配置

沙箱环境：在 DevTools 自助生成

  1. 打开 DevTools：https://otcsb.legendtrading.com/integration/login，用 Legend 提供的登录密码登录。
  2. 在左侧菜单进入系统设置。
  3. 在 REST API Token 区块点击**+生成新 Token**。
  4. 复制生成的 Token，在请求中作为 Authorization: Bearer YOUR_SANDBOX_TOKEN 使用。
  5. 仍在系统设置页，在 IP 白名单区块添加将要调用接口的服务器的出口 IP——点击**+添加此 IP 可直接加入当前浏览所用的 IP，或点击+添加 IP** 手动输入（IPv4，例如 12.34.56.78）。
  6. 仍在系统设置页，在 Webhook 配置区块填写 API_URL 并点击保存。地址必须以 / 结尾——Legend 会在此基础上追加 webhook 名称（如 trade-notify）。保存后缓存 TTL 最长可能延迟 60 秒生效。

注意：此处添加的 IP 只对使用你的 REST Token 调用 /app/* 接口的请求生效。可用 Webhook 配置 → 发送测试 验证你的回调地址是否可达。

生产环境：向 Legend 申请

生产环境没有 DevTools，不存在自助入口。请通过 Legend 对接人申请：

邮件申请地址：[email protected]

邮件标题：【您的交易所名称 Token申请】

请在申请中说明将要发起请求的服务器 IP，完整的生产环境申请清单见上线前的准备。

2. Token 有效期

  • Token 有效期为 1 年
  • v1 和 v2 接口通用
  • 沙箱 Token 自行管理：到期前在 DevTools（系统设置 → REST API Token → +生成新 Token）重新生成
  • 生产 Token 失效前，Legend 会主动通知

3. 标准请求头

所有 API 请求必须在 HTTP 头部中包含有效的 Bearer Token 进行身份认证。

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
Accept: application/json
User-Ip: 123.45.67.89
请求头值必填说明
AuthorizationBearer {YOUR_API_TOKEN}是您的 API 访问令牌
Content-Typeapplication/jsonPOST必填请求体内容类型
Acceptapplication/json是期望的响应内容类型
User-Ip用户真实公网IP是用于风控审计的终端用户真实 IP 地址

注意事项：

  • User-Ip 必须提供真实的终端用户公网IP地址，不可使用服务器IP或内网IP
  • 所有 API 请求必须包含这四个请求头参数（GET 请求可不含 Content-Type）

四、核心接口列表

KYC 相关
入金 (On-Ramp)
  • /app/rfqbyfiat – 法币询价：根据法币金额获取可购买的加密货币数量及报价
  • /app/depositmethods – 充值方式：获取支持的银行转账或信用卡支付方式
  • /app/depositaccount – 充值账户：获取平台收款银行账户信息
  • /app/orderbyfiat – 法币下单：使用法币金额创建加密货币购买订单
出金 (Off-Ramp)
  • /app/rfq – 加密货币询价：根据加密货币数量获取可兑换的法币金额及报价
  • /app/offrampquote – 出金报价：获取加密货币卖出的详细报价（含费用明细）
  • /app/offrampsell – 出金卖出：提交加密货币卖出订单
  • /app/withdraw – 银行提现：发起法币提现到银行账户的请求
查询与管理
  • /app/pairs – 交易对列表：获取平台支持的所有交易对及其交易限额、精度等信息
  • /app/balance – 用户余额：查询用户在平台上的各资产余额
  • /app/tradehistory – 交易历史：获取用户的交易记录列表
  • /app/fees – 费率查询：获取当前的阶梯费率表

五、速率限制 (Rate Limits)

为保障系统稳定性，API 设有调用频率限制。频率基于单个 API_TOKEN 统计。

接口类别限制规则建议
询价接口600 次 / 分钟避免在客户端循环频繁调用，必要时可缓存报价
交易接口600 次 / 分钟适用于用户主动发起的买卖操作
查询接口600 次 / 分钟适用于余额、历史等数据查询

提示：若请求超限，将收到 HTTP 429 Too Many Requests 响应。请合理设计调用逻辑，或在需要更高限额时联系客户经理。

六、错误处理

常见错误响应

1. Token 失效

v1 接口返回：

{ "message": "Unauthenticated."}

v2 接口返回：

{
  "request_id": "21c1bec06e1086924127c6e22e42c49e",
  "status": "error",
  "code": "101003",
  "message": "Unauthenticated",
  "errors": [
    { "message": "Unauthenticated." }
  ],
  "metadata": {}
}

2. IP 地域限制

{
  "request_id": "3cca1262df14f53f7798f3901d5539c4",
  "status": "error",
  "code": "101100",
  "message": "Due to compliance reasons, we are unable to offer services to users from this region.",
  "errors": [],
  "metadata": {
    "ip": "117.104.227.243",
    "country": "Afghanistan"
  }
}

提示：可通过接口 https://ex.legendtrading.com/reference/ip-v2 获取不支持交易的国家名单

3. 服务器IP未授权

{
  "error": 401,
  "message": "Access restricted."
}

注意：调用方服务器的 IP 不在白名单内。沙箱环境下，请在 DevTools 的系统设置 → IP 白名单中自行添加；生产环境下，请联系 Legend 加白。

七、代码示例

示例 1: GET 请求（获取国家列表）

curl -s \
  -H "Authorization: Bearer 您的Token" \
  -H "Accept: application/json" \
  -H "User-Ip: 12.34.56.78" \
  "https://sandboxapi.legendtrading.com/v2/app/countries"

成功响应示例：

{
  "request_id": "0578ac927c446fedd16a32e2846028a9",
  "status": "success",
  "code": "100000",
  "message": "success",
  "data": [
    { "country_iso2_code": "AF" }
  ],
  "metadata": {}
}

示例 2: POST 请求（KYC个人认证）

curl -X POST \
  -H "Authorization: Bearer 您的Token" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "User-Ip: 12.34.56.78" \
  -d '{
    "uid": "sandbox_test_uid1",
    "email": "[email protected]",
    "first_name": "Testname",
    "last_name": "Testlastname",
    "birthdate": "1990-01-01",
    "country_iso2_code": "US",
    "state": "California",
    "city": "San Francisco",
    "address": "123 Main St,California",
    "zipcode": "94102",
    "citizenship_iso2_codes": ["US"],
    "place_of_birth": "US",
    "ssn": "123456789"
  }' \
  "https://sandboxapi.legendtrading.com/v2/app/kyc/individual/pi"

成功响应示例：

{
  "request_id": "7eacd1af7897465be4ac87570a8bde2a",
  "status": "success",
  "code": "100000",
  "message": "success",
  "data": [],
  "metadata": {}
}

八、安全提醒

  1. Token 保密：请妥善保管您的 API Token，切勿在公共代码库或非安全环境中暴露
  2. IP 白名单：确保请求均来自已授权的服务器 IP——沙箱环境由你自行在 DevTools 维护该名单，生产环境由 Legend 按申请维护
  3. 超时设置：建议设置合理的请求超时时间（如 8-15 秒）
  4. 错误处理：实现完整的异常处理机制，确保系统稳定性
  5. 环境隔离：沙箱环境仅用于测试，不涉及真实资金和用户数据

Updated 16 days ago

Updated 16 days ago