合约指南

本指南解释了 BigONE 合约 API 的核心逻辑。与现货交易不同，合约交易涉及杠杆、保证金模式 和仓位等复杂概念。

准备工作

基础 URL: https://api.big.one/api/contract/v2
认证: 需要 Bearer Token (JWT)。
数据类型: 与现货 API 不同，合约 API 中的大多数数字字段（如 price, size, leverage）是 JSON Numbers（整数或浮点数），而不是字符串。

第一课：保证金模式与杠杆

在开仓之前，您必须定义如何使用保证金。这是针对每个合约品种（例如：BTCUSD）单独配置的。

端点: PUT /positions/{symbol}/margin

概念

isCross (Boolean):
- true (全仓模式): 使用您的整个账户余额来避免强平。风险共担。
- false (逐仓模式): 风险限制在该仓位分配的特定保证金内。
leverage (Number): 乘数（例如：10, 100）。
margin (Number): 仅在逐仓模式下用于增加/减少保证金。如果只更改杠杆，请设置为 0。

逻辑：设置 20倍全仓杠杆

您通常在开始策略之前执行一次此操作。

import requests
import json

BASE_URL = "https://api.big.one/api/contract/v2"
headers = {"Authorization": "Bearer YOUR_JWT", "Content-Type": "application/json"}

# 设置 BTCUSD 为全仓模式，20倍杠杆
payload = {
    "isCross": True,
    "leverage": 20,
    "margin": 0
}

response = requests.put(f"{BASE_URL}/positions/BTCUSD/margin", json=payload, headers=headers)
print("杠杆已设置:", response.json()['leverage'])

第二课：下单

合约订单具有现货交易中不存在的特定字段。

端点: POST /orders

关键参数

symbol: 例如：BTCUSD。
size (Integer): 合约张数。
- 反向合约 (BTCUSD): 1 张合约 = 1 USD。
- 正向合约 (BTCUSDT): 1 张合约 = 基础资产的合约乘数单位。请查看合约规格。
reduceOnly (Boolean):
- true: 此订单确保您是在平仓。如果订单数量超过您的持仓量，系统会自动调整大小或取消它。始终用于止盈/止损。

示例：开多 (买入)

我们想在 $50,000 开 100 张合约的多头仓位。

payload = {
    "symbol": "BTCUSD",
    "side": "BUY",      # 做多
    "type": "LIMIT",
    "price": 50000,     # 数字!
    "size": 100,        # 数字! (对于 BTCUSD，100 张 = $100 价值)
    "reduceOnly": False
}

response = requests.post(f"{BASE_URL}/orders", json=payload, headers=headers)
order = response.json()
print(f"订单 {order['id']} 状态: {order['status']}")

第三课：平仓

要平仓，您只需下一个 相反方向 的订单。

"只减仓" (Reduce-Only) 规则

为了防止意外反转您的仓位（例如：卖出过多导致从做多变成做空），请始终设置 reduceOnly: true。

逻辑：平掉所有多头

检查当前持仓数量。
使用 reduceOnly: true 下卖单。

# 1. 获取持仓
accounts = requests.get(f"{BASE_URL}/accounts", headers=headers).json()
# 在嵌套结构中找到 BTCUSD 仓位
# (为了清晰起见简化代码 - 实际解析取决于响应结构)
# 假设我们找到: position_size = 100

# 2. 平仓
close_payload = {
    "symbol": "BTCUSD",
    "side": "SELL",     # 与多头相反
    "type": "MARKET",   # 立即平仓
    "size": 100,
    "reduceOnly": True  # 安全标志
}

requests.post(f"{BASE_URL}/orders", json=close_payload, headers=headers)

第四课：仓位数据

监控您的 PnL（盈亏）和强平价格至关重要。

端点: GET /accounts

这返回一个包含 cash（余额）和 positions（仓位）的复杂结构。

positions 中的关键字段:

unrealizedPnl: 基于当前标记价格的浮动盈亏。
liquidatePrice: 您的仓位将被强制平仓的价格。
marginRate: 如果此值接近 100%，您将面临强平风险。
entryPrice: 您的平均开仓成本。

// 仓位对象示例
{
  "symbol": "BTCUSD",
  "size": 100,
  "entryPrice": 50000,
  "markPrice": 51000,
  "unrealizedPnl": 0.000039, // BTC 数量
  "liquidatePrice": 42000,
  "leverage": 20
}

完整示例

此脚本演示了正确的顺序：设置杠杆 -> 开仓 -> 设置止损。

import requests
import time
import jwt

# --- 配置 ---
BASE_URL = "https://api.big.one/api/contract/v2"
API_KEY = "YOUR_KEY"
SECRET_KEY = "YOUR_SECRET"
SYMBOL = "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_contract_bot():
    print(f"--- Contract Bot: {SYMBOL} ---")

    # 1. 设置杠杆 (关键步骤)
    print("1. 设置杠杆 (5x 全仓)...")
    lev_payload = {"isCross": True, "leverage": 5, "margin": 0}
    requests.put(f"{BASE_URL}/positions/{SYMBOL}/margin", json=lev_payload, headers=get_headers())
    
    # 2. 市价开多 (开仓)
    print("2. 开多头仓位...")
    # 注意: 合约 API 使用数字，不是字符串
    open_payload = {
        "symbol": SYMBOL,
        "side": "BUY",      # 做多
        "type": "MARKET",
        "size": 100,        # 100 张合约
        "reduceOnly": False
    }
    res = requests.post(f"{BASE_URL}/orders", json=open_payload, headers=get_headers())
    
    if res.status_code != 200:
        print("开仓失败:", res.json())
        return
        
    order = res.json()
    print(f"   开仓订单 {order['id']} 状态: {order['status']}")
    
    # 等待成交逻辑... 演示中假设已成交
    time.sleep(1)

    # 3. 获取仓位详情
    print("3. 检查仓位...")
    acct = requests.get(f"{BASE_URL}/accounts", headers=get_headers()).json()
    # 查找仓位 (简化解析)
    position = None
    for a in acct:
        for p in a.get('positions', []):
            if p['symbol'] == SYMBOL:
                position = p
                break
    
    if position and position['size'] > 0:
        entry_price = position['entryPrice']
        print(f"   多头持仓: {position['size']}, 入场价: {entry_price}")
        
        # 4. 设置止损 (只减仓)
        # 在入场价下方 2% 止损
        stop_price = int(entry_price * 0.98) 
        print(f"4. 在 {stop_price} 设置止损...")
        
        sl_payload = {
            "symbol": SYMBOL,
            "side": "SELL",     # 与多头相反
            "type": "LIMIT",    # 或 STOP/MARKET，视需求而定
            "price": stop_price,
            "size": position['size'], # 平掉全部仓位
            "reduceOnly": True  # 安全: 确保我们不会反手开空
        }
        sl_res = requests.post(f"{BASE_URL}/orders", json=sl_payload, headers=get_headers())
        print(f"   止损单已下: {sl_res.json().get('id')}")

if __name__ == "__main__":
    run_contract_bot()

结论

合约交易为杠杆和对冲提供了强大的工具，但也需要严格注意细节。与现货 API 不同，合约 API 依赖于 JSON Numbers 和显式的 保证金模式 配置。

要点:

数据类型: 始终将 price, size, 和 leverage 作为数字（整数/浮点数）发送。
安全第一: 在开仓之前配置您的 leverage 和 isCross 模式。
平仓: 使用 reduceOnly: true 安全平仓，避免意外开设新仓位。

下一步:

查阅合约 API 参考了解高级订单类型，如 IOC 和 FOK。
实现 WebSocket 监听器以实时监控您的 强平价格。

准备工作​

第一课：保证金模式与杠杆​

概念​

逻辑：设置 20倍 全仓杠杆​

第二课：下单​

关键参数​

示例：开多 (买入)​

第三课：平仓​

"只减仓" (Reduce-Only) 规则​

逻辑：平掉所有多头​

第四课：仓位数据​

完整示例​

结论​