闪兑指南
本指南解释了 BigONE 闪兑服务使用的 请求报价 (RFQ) 工作流程。与现货交易（订单簿）不同，闪兑在短时间内提供保证价格，非常适合即时兑换。
准备工作
- 基础 URL:
https://api.big.one/sapi/v1/convert - 认证: 需要 Bearer Token (JWT)。
- 所需权限范围 (Scope):
convert assets(创建订单)
第一课：报价系统
闪兑的核心概念是 报价 (Quote)。您询问系统“我用 1000 USDT 可以换多少 BTC？”，系统会回复一个锁定几秒钟的价格。
端点: GET /viewer/quote
关键参数
from_asset: 您想要卖出的资产（例如："USDT"）。to_asset: 您想要买入的资产（例如："BTC"）。rfq_size: 涉及的数量。rfq_size_asset: 关键字段！告诉系统rfq_size指的是源资产还是目标资产。- 如果您想花费固定金额，请设置为
from_asset（例如：“精确花费 100 USDT”）。 - 如果您想获得固定金额，请设置为
to_asset（例如：“精确获得 0.1 BTC”）。
- 如果您想花费固定金额，请设置为
逻辑：“我想花费 1000 USDT”
import requests
import json
BASE_URL = "https://api.big.one/sapi/v1/convert"
headers = {"Authorization": "Bearer YOUR_JWT"}
params = {
"from_asset": "USDT",
"to_asset": "BTC",
"rfq_size": "1000",
"rfq_size_asset": "USDT" # 固定输入
}
response = requests.get(f"{BASE_URL}/viewer/quote", params=params, headers=headers)
quote = response.json()
print(f"报价 ID: {quote['quote_id']}")
print(f"价格: {quote['px']}")
print(f"有效期: {quote['ttl_ms']} 毫秒")
第二课：执行 (交易)
一旦您获得了有效的 quote_id，您必须通过创建交易来“接受”它。这必须在报价过期之前发生（ttl_ms 通常约为 10 秒）。
端点: POST /viewer/trade
账户选择
您可以使用 account_type 指定资金来源：
FUND: 使用资金账户（默认）。SPOT: 使用现货账户。
逻辑：接受报价
quote_id = quote['quote_id']
payload = {
"quote_id": quote_id,
"account_type": "FUND" # 从资金账户扣除 USDT
}
trade_response = requests.post(f"{BASE_URL}/viewer/trade", json=payload, headers=headers)
if trade_response.status_code == 200:
print("兑换成功！")
print(json.dumps(trade_response.json(), indent=2))
else:
print("兑换失败:", trade_response.json())
第三课：处理过期
在波动剧烈的市场中，或者由于网络延迟，您的报价可能会在交易请求到达服务器之前过期。
错误代码: 54047 (闪兑价格已过期)
健壮的工作流
- 获取报价。
- 立即发送交易请求。
- 检查响应：
- 如果 成功: 完成。
- 如果 错误 54047: 回到第一步（获取新报价）。
def robust_swap():
# 1. 获取报价
quote = requests.get(f"{BASE_URL}/viewer/quote", ...).json()
# 2. 尝试交易
res = requests.post(f"{BASE_URL}/viewer/trade", json={"quote_id": quote['quote_id']}, ...)
if res.status_code != 200:
error = res.json()
if error['code'] == 54047:
print("报价已过期，正在重试...")
return robust_swap() # 递归重试
else:
raise Exception(f"交易失败: {error['message']}")
return res.json()
完整示例
此脚本演示了一个健壮的“报价到交易”循环，可自动处理报价过期。
import requests
import time
import jwt
# --- 配置 ---
BASE_URL = "https://api.big.one/sapi/v1/convert"
API_KEY = "YOUR_KEY"
SECRET_KEY = "YOUR_SECRET"
def get_headers():
token = jwt.encode({
"sub": API_KEY,
"nonce": int(time.time() * 1000000),
"iat": int(time.time()),
"exp": int(time.time()) + 60
}, SECRET_KEY, algorithm="HS256")
return {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
def execute_swap(from_asset, to_asset, amount, max_retries=3):
attempt = 0
while attempt < max_retries:
attempt += 1
print(f"--- 兑换尝试 {attempt} ---")
# 1. 请求报价
print("1. 正在请求报价...")
quote_params = {
"from_asset": from_asset,
"to_asset": to_asset,
"rfq_size": str(amount),
"rfq_size_asset": from_asset # 卖出固定数量
}
# 注意: 报价端点 is GET
q_res = requests.get(f"{BASE_URL}/viewer/quote", params=quote_params, headers=get_headers())
if q_res.status_code != 200:
print("报价请求失败:", q_res.json())
return
quote = q_res.json()
quote_id = quote['quote_id']
price = quote['px']
print(f" 报价 ID: {quote_id}, 价格: {price}")
# 2. 执行交易
print("2. 正在执行交易...")
trade_payload = {
"quote_id": quote_id,
"account_type": "FUND"
}
# 注意: 交易端点 is POST
t_res = requests.post(f"{BASE_URL}/viewer/trade", json=trade_payload, headers=get_headers())
if t_res.status_code == 200:
trade = t_res.json()
print(" 成功！")
print(f" 交易 ID: {trade['id']}, 收到: {trade['to_sz']} {trade['to_asset']}")
return
else:
error = t_res.json()
code = error.get('code')
print(f" Error: {code} - {error.get('message')}")
# 54047 = 价格已过期
if code == 54047:
print(" >> 报价已过期。立即重试...")
continue # 回到第一步
else:
print(" >> 致命错误。停止。")
return
print("已达到最大重试次数。")
if __name__ == "__main__":
# 将 100 USDT 兑换为 BTC
execute_swap("USDT", "BTC", 100)
结论
闪兑 API 提供了一种精简、零滑点的替代方案，用于替代订单簿进行资产兑换。通过掌握 请求报价 (RFQ) 工作流程，您可以构建可靠支付或交易服务。
要点:
- 报价优先: 在交易之前，务必先获取锁定价格 (
quote_id)。 - 处理过期: 为
54047错误实现重试循环，以健壮地处理快速波动的市场。 - 方向控制: 使用
rfq_size_asset严格控制您花费或收到的确切数量。
下一步:
- 将闪兑集成到您的提现流程中，允许用户提现他们当前未持有的资产。
- 查阅 闪兑 API 参考 了解支持的资产完整列表。