跨市场整合指南

本指南演示了如何构建一个协调 BigONE 现货和合约 API 行为的复杂交易应用程序。

我们使用标准的 期现套利 (Cash and Carry Arbitrage) 场景作为案例研究。这个场景非常适合学习，因为它需要：

数据同步: 从两个不同的市场系统获取并比较价格。
类型处理: 管理现货（字符串）与合约（数字）的严格数据要求差异。
类原子执行: 同时在两个不同的引擎上执行订单。

注意: 本指南侧重于 API 整合的 技术实现。不构成财务建议。

整合逻辑

要成功连接现货和合约市场，您的应用程序必须处理每个 API 的不同行为：

现货 API: 使用 字符串 保持精度。账户是独立的。
合约 API: 使用数字。需要“反向”计算逻辑。
协调: 您必须计算“基差”（价格差）以决定何时触发工作流。

第一课：准备工作 (数据与计算)

要正确执行此操作，您必须比较 现货价格 和 合约标记价格。

现货 API: GET https://api.big.one/api/v3/asset_pairs/{pair}/ticker
合约 API: GET https://api.big.one/api/contract/v2/instruments

获取数据

import requests

# 1. 获取现货价格 (BTC-USDT)
spot_res = requests.get("https://api.big.one/api/v3/asset_pairs/BTC-USDT/ticker")
spot_price = float(spot_res.json()['price'])

# 2. 获取合约数据 (BTCUSD - 反向永续)
contract_res = requests.get("https://api.big.one/api/contract/v2/instruments")
instruments = contract_res.json()
target_contract = next(i for i in instruments if i['symbol'] == 'BTCUSD')

mark_price = target_contract['markPrice']
funding_rate = target_contract['fundingRate']

print(f"Spot: ${spot_price}, Contract: ${mark_price}")
print(f"Current Funding Rate: {funding_rate * 100}%")

第二课：仓位大小 (数学计算)

关键: 这是大多数开发者容易出错的地方。您必须根据合约类型计算正确的空头头寸大小。

场景: BTCUSD (反向合约)

类型: 币本位 (反向)。
单位: 1 张合约 = 1 USD。
目标: 对冲 1 BTC。

公式:

合约数量 (张) = BTC 数量 × BTC 价格

示例:

您持有 0.5 BTC。
价格为 $50,000。
价值 = $25,000。
您必须做空 25,000 张合约。

代码实现

def calculate_hedge_size(btc_amount, price):
    # 对于反向 BTCUSD (1 张 = 1 USD)
    contract_size = int(btc_amount * price)
    return contract_size

# 示例
amount_to_hedge = 0.5 # BTC
execution_price = 50000

contracts_to_short = calculate_hedge_size(amount_to_hedge, execution_price)
print(f"对冲 {amount_to_hedge} BTC, 做空 {contracts_to_short} 张合约。")
# 输出: Short 25000 Contracts

第三课：执行 (对冲)

现在我们执行这两条腿。注意 API Payload 格式的差异。

步骤 1: 买入现货 (多头腿)

API: 现货 V3
数据类型: 字符串 (严格精度)。

# 现货 Payload (买入 0.5 BTC)
spot_payload = {
    "asset_pair_name": "BTC-USDT",
    "side": "BID",
    "type": "MARKET",
    "amount": "0.5" # 字符串!
}
# requests.post(..., json=spot_payload)

步骤 2: 做空合约 (空头腿)

API: 合约 V2
数据类型: 数字 (标准 JSON 数字)。
动作: 先将 BTC 划转到合约账户！

# 合约 Payload (做空 25,000 张)
contract_payload = {
    "symbol": "BTCUSD",
    "side": "SELL",     # 做空
    "type": "MARKET",
    "size": 25000,      # 整数/数字!
    "reduceOnly": False
}
# requests.post(..., json=contract_payload)

数据类型不匹配

注意，现货 API 要求 amount 为 字符串 ("0.5")，而合约 API 接受 size 为数字 (25000)。混淆这两者是错误的常见来源。

第四课：维护与风险

套利是低风险，并非零风险。

1. 强平风险

即使您进行了对冲，您的合约仓位也有强平价格。

反向合约: 如果价格上涨，您的空头仓位会亏损 BTC。
风险: 如果您的 BTC 保证金耗尽，您会在卖出现货 BTC 补仓之前被强平。
解决方案: 保持低杠杆（例如 1倍或 2倍）。套利不要使用 100倍杠杆。

2. 资金费率反转

如果资金费率变为负值，空头需要向多头支付费用。您将开始亏损。
动作: 监控 fundingRate。如果持续为负，平掉双边仓位（卖出现货，买入平仓合约）。

3. 再平衡

随着价格变化，由于反向合约与线性现货资产的非线性特性，您的对冲比率可能会略有漂移（虽然 1倍对冲通常很稳定）。
定期重新计算 价值 = 数量 * 价格 并调整合约数量。

完整示例

此脚本计算正确的对冲比率并执行 期现套利 交易（做多现货 + 做空合约）。

import requests
import time
import jwt

# --- 配置 ---
SPOT_BASE = "https://api.big.one/api/v3"
CONTRACT_BASE = "https://api.big.one/api/contract/v2"
API_KEY = "YOUR_KEY"
SECRET_KEY = "YOUR_SECRET"

# 目标: 对冲 0.01 BTC
TARGET_BTC = 0.01
SPOT_PAIR = "BTC-USDT"
CONTRACT_SYM = "BTCUSD"

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 run_arbitrage():
    print("--- 开始套利执行 ---")

    # 1. 获取价格
    print("1. 获取市场数据...")
    spot_ticker = requests.get(f"{SPOT_BASE}/asset_pairs/{SPOT_PAIR}/ticker").json()
    spot_price = float(spot_ticker['price'])
    
    contract_inst = requests.get(f"{CONTRACT_BASE}/instruments").json()
    contract = next(i for i in contract_inst if i['symbol'] == CONTRACT_SYM)
    mark_price = contract['markPrice']
    
    basis = (mark_price - spot_price) / spot_price
    print(f"   现货: {spot_price}, 标记: {mark_price}, 基差: {basis*100:.2f}%")
    
    # 2. 计算数量
    # 现货: 字符串, 精确数量
    spot_qty_str = f"{TARGET_BTC:.6f}"
    
    # 合约 (反向): 数量 = BTC * 价格
    # 对冲价值 = 0.01 BTC * $50000 = $500 = 500 张
    contract_qty_int = int(TARGET_BTC * mark_price)
    
    print(f"2. 计算:")
    print(f"   现货腿: 买入 {spot_qty_str} BTC")
    print(f"   合约腿: 做空 {contract_qty_int} 张合约")
    
    # 3. 执行 (类同时)
    print("3. 执行中...")
    
    # 腿 A: 买入现货
    spot_payload = {
        "asset_pair_name": SPOT_PAIR,
        "side": "BID",
        "type": "MARKET",
        "amount": spot_qty_str # 字符串!
    }
    spot_res = requests.post(f"{SPOT_BASE}/viewer/orders", json=spot_payload, headers=get_headers())
    print(f"   现货订单: {spot_res.status_code}")
    
    # 腿 B: 做空合约
    contract_payload = {
        "symbol": CONTRACT_SYM,
        "side": "SELL",    # 做空
        "type": "MARKET",
        "size": contract_qty_int, # 整数!
        "reduceOnly": False
    }
    cont_res = requests.post(f"{CONTRACT_BASE}/orders", json=contract_payload, headers=get_headers())
    print(f"   合约订单: {cont_res.status_code}")
    
    # 在生产环境中，检查部分成交并进行调整！

if __name__ == "__main__":
    run_arbitrage()

结论

期现套利 策略是从加密市场赚取收益的经典低风险方法。成功取决于精确的执行和对 反向合约 机制的理解。

要点:

数学很重要: 对于反向合约（如 BTCUSD），持仓数量 = BTC 数量 * 价格。
API 差异: 记住现货 API 期望字符串，而合约 API 期望数字。
监控: 关注 资金费率。如果长期为负，该策略可能会失去盈利能力。

下一步:

自动化“再平衡”逻辑，随着资产价格变化调整您的对冲。
探索使用 正向合约 (USDT 本位) 进行期现套利，计算更简单 (1 BTC = 1 Contract)。

整合逻辑​

第一课：准备工作 (数据与计算)​

获取数据​

第二课：仓位大小 (数学计算)​

场景: BTCUSD (反向合约)​

代码实现​

第三课：执行 (对冲)​

步骤 1: 买入现货 (多头腿)​

步骤 2: 做空合约 (空头腿)​

第四课：维护与风险​

1. 强平风险​

2. 资金费率反转​

3. 再平衡​

完整示例​

结论​