概述与鉴权

一、服务概述

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

二、环境与地址

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

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

三、认证与请求规范

1. Token 申请流程

所有 API 接口均为私有接口，调用需提供有效访问令牌。请按以下流程申请：

邮件申请地址：[email protected]

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

邮件内容模板：

麻烦回答以下问题，用于配置测试环境和账号：

homepage_url: 官网地址
api_url: 回调地址
api_key: 用于鉴权（可选）
associated_email: 用于在Legend注册账户
联系人email: 用于接收凭据
Telegram 联系人: 用于接收解密密码
IPs: 添加白名单
logo下载地址: 600x200
Legend landing/用户入口页面URL: 
添加Legend服务器白名单IP

2. Token 有效期

Token 有效期为 1 年
失效前 Legend 会主动通知
v1 和 v2 接口通用

3. 标准请求头

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

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
Accept: application/json
User-Ip: 123.45.67.89

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

注意事项：

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

四、核心接口列表

KYC 相关

/kyc/individual/pi – 基本信息保存接口：注册和保存用户基本信息
/kyc/individual/qa – 问卷调查相关接口
/kyc/individual/file – 证件上传接口
/kyc/individual/idv – 活体检测（人脸识别）接口
/kyc/individual/submit – 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/v0.9-zh/reference/ip-v2 获取不支持交易的国家名单

3. 服务器IP未授权

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

七、代码示例

示例 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": {}
}

八、安全提醒

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

这个合并后的文档具有以下优点：

结构清晰：按逻辑顺序组织，从概述到具体实现
信息完整：涵盖了环境、认证、接口、限流、错误处理、示例等所有关键信息
避免重复：合并了两个文档中的相同内容
实用性高：提供了完整的代码示例和错误处理指导
安全突出：将安全提醒单独列出，强调重要性