币安 USDT 合约交易技能

概述

本技能提供币安 USDT-M 永续合约的完整交易功能, 通过 MCP 工具实现:

• 账户余额查询
• 持仓信息查询
• 杠杆/保证金模式设置
• 开仓/平仓操作
• 止损止盈设置
• 订单管理 (查询/撤销)

环境配置

必需的环境变量

# API 密钥 (必需)
BINANCE_API_KEY=your_api_key
BINANCE_API_SECRET=your_api_secret

# 模拟交易模式 (默认 true, 不执行真实订单)
TRADING_SIMULATION=true

# 使用测试网 (可选, 默认 false)
BINANCE_USE_TESTNET=false

安全提醒

• 禁止在代码中硬编码 API 密钥
• 建议先使用测试网验证策略
• 默认启用模拟模式, 防止误操作

可用工具

查询类 (只读)

注意: 止盈止损订单使用 Algo Order API, 需要用 binance_get_open_algo_orders 查询, 不会出现在 binance_get_open_orders 中.

设置类

交易类

使用示例

1. 查询账户状态

# 查询 USDT 余额
binance_get_balance(asset="USDT")

# 查询所有持仓
binance_get_positions()

# 查询指定交易对持仓
binance_get_positions(symbol="BTCUSDT")

2. 设置杠杆和保证金模式

# 设置 BTCUSDT 杠杆为 10 倍
binance_change_leverage(symbol="BTCUSDT", leverage=10)

# 切换为逐仓模式 (有持仓时无法切换)
binance_change_margin_type(symbol="BTCUSDT", margin_type="ISOLATED")

3. 开仓

# 市价做多 0.01 BTC
binance_place_order(
    symbol="BTCUSDT",
    side="BUY",
    type="MARKET",
    quantity=0.01,
    confirm_real_order=True  # 实盘必须
)

# 限价做空
binance_place_order(
    symbol="BTCUSDT",
    side="SELL",
    type="LIMIT",
    quantity=0.01,
    price=100000,
    timeInForce="GTC",
    confirm_real_order=True
)

4. 平仓

# 全部平仓
binance_close_position(
    symbol="BTCUSDT",
    confirm_real_order=True
)

# 部分平仓
binance_close_position(
    symbol="BTCUSDT",
    quantity=0.005,
    confirm_real_order=True
)

5. 设置止损止盈

# 同时设置止损和止盈
binance_set_stop_loss_take_profit(
    symbol="BTCUSDT",
    stopLossPrice=95000,
    takeProfitPrice=110000,
    confirm_real_order=True
)

# 只设置止损
binance_set_stop_loss_take_profit(
    symbol="BTCUSDT",
    stopLossPrice=95000,
    confirm_real_order=True
)

6. 订单管理

# 查询普通挂单 (限价单等)
binance_get_open_orders(symbol="BTCUSDT")

# 查询条件单 (止盈止损订单)
binance_get_open_algo_orders(symbol="BTCUSDT")

# 撤销指定订单
binance_cancel_order(symbol="BTCUSDT", orderId=123456789)

# 撤销所有普通挂单
binance_cancel_all_orders(symbol="BTCUSDT")

# 撤销单个条件单 (止盈止损)
binance_cancel_algo_order(symbol="BTCUSDT", algoId=123456789)

# 撤销所有条件单 (止盈止损)
binance_cancel_all_algo_orders(symbol="BTCUSDT")

重要:

• 止盈止损订单使用 Algo Order API (2025-12-09 迁移后)
• 查询条件单: binance_get_open_algo_orders
• 撤销条件单: binance_cancel_algo_order 或 binance_cancel_all_algo_orders
• 普通的 binance_cancel_all_orders 无法撤销条件单

订单类型说明

交易方向

账户使用对冲模式 (Hedge Mode), 所有交易操作必须指定 positionSide 参数:

• 开多: side=BUY + positionSide=LONG
• 平多: side=SELL + positionSide=LONG
• 开空: side=SELL + positionSide=SHORT
• 平空: side=BUY + positionSide=SHORT

注意: 不要使用 positionSide=BOTH, 会报错 -4061

模拟交易模式

默认情况下, 所有交易类工具运行在模拟模式:

1. 不会执行真实订单
2. 返回模拟订单信息
3. 用于验证参数和策略逻辑

启用实盘交易

1. 设置环境变量: TRADING_SIMULATION=false
2. 调用时传入: confirm_real_order=True

# 两个条件都满足才会执行真实订单
binance_place_order(
    symbol="BTCUSDT",
    side="BUY",
    type="MARKET",
    quantity=0.01,
    confirm_real_order=True  # 必须显式确认
)

风险提示

1. 资金安全: 合约交易有爆仓风险, 请谨慎操作
2. 杠杆风险: 高杠杆放大盈亏, 建议使用低杠杆
3. 止损保护: 开仓后应立即设置止损
4. 测试优先: 新策略先在测试网验证
5. 单笔风险: 建议单笔亏损不超过账户 1-2%

常见错误码

技术实现

本 MCP 工具使用 binance-futures-connector-python 官方 SDK, 无需手动处理签名等底层细节.

API 端点说明

普通订单 API:

• GET /fapi/v1/openOrders - 查询普通挂单
• DELETE /fapi/v1/order - 撤销单个普通订单
• DELETE /fapi/v1/allOpenOrders - 撤销所有普通订单

条件单 Algo Order API (2025-12-09 迁移后):

• POST /fapi/v1/algoOrder - 创建条件单 (止盈止损)
• GET /fapi/v1/openAlgoOrders - 查询条件单
• DELETE /fapi/v1/algoOrder - 撤销单个条件单
• 注意: 币安没有提供批量撤销条件单的 API, binance_cancel_all_algo_orders 工具通过先查询再逐个撤销实现

开发注意事项

修改本 MCP 服务前, 应使用 Context7 查询最新 API 文档:

# 查询币安合约 API 文档
resolve-library-id: "binance futures connector python"
get-library-docs: context7CompatibleLibraryID="/binance/binance-futures-connector-python", topic="具体功能"

参考资料

• 币安 USDT-M 合约 API 文档
• binance-futures-connector-python
• Context7 Library ID: /binance/binance-futures-connector-python