币安 USDT 合约交易技能

概述

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

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

环境配置

必需的环境变量

bash
1# API 密钥 (必需)
2BINANCE_API_KEY=your_api_key
3BINANCE_API_SECRET=your_api_secret
4
5# 模拟交易模式 (默认 true, 不执行真实订单)
6TRADING_SIMULATION=true
7
8# 使用测试网 (可选, 默认 false)
9BINANCE_USE_TESTNET=false

安全提醒

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

可用工具

查询类 (只读)

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

设置类

交易类

使用示例

1. 查询账户状态

python
1# 查询 USDT 余额
2binance_get_balance(asset="USDT")
3
4# 查询所有持仓
5binance_get_positions()
6
7# 查询指定交易对持仓
8binance_get_positions(symbol="BTCUSDT")

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

python
1# 设置 BTCUSDT 杠杆为 10 倍
2binance_change_leverage(symbol="BTCUSDT", leverage=10)
3
4# 切换为逐仓模式 (有持仓时无法切换)
5binance_change_margin_type(symbol="BTCUSDT", margin_type="ISOLATED")

3. 开仓

python
1# 市价做多 0.01 BTC
2binance_place_order(
3    symbol="BTCUSDT",
4    side="BUY",
5    type="MARKET",
6    quantity=0.01,
7    confirm_real_order=True  # 实盘必须
8)
9
10# 限价做空
11binance_place_order(
12    symbol="BTCUSDT",
13    side="SELL",
14    type="LIMIT",
15    quantity=0.01,
16    price=100000,
17    timeInForce="GTC",
18    confirm_real_order=True
19)

4. 平仓

python
1# 全部平仓
2binance_close_position(
3    symbol="BTCUSDT",
4    confirm_real_order=True
5)
6
7# 部分平仓
8binance_close_position(
9    symbol="BTCUSDT",
10    quantity=0.005,
11    confirm_real_order=True
12)

5. 设置止损止盈

python
1# 同时设置止损和止盈
2binance_set_stop_loss_take_profit(
3    symbol="BTCUSDT",
4    stopLossPrice=95000,
5    takeProfitPrice=110000,
6    confirm_real_order=True
7)
8
9# 只设置止损
10binance_set_stop_loss_take_profit(
11    symbol="BTCUSDT",
12    stopLossPrice=95000,
13    confirm_real_order=True
14)

6. 订单管理

python
1# 查询普通挂单 (限价单等)
2binance_get_open_orders(symbol="BTCUSDT")
3
4# 查询条件单 (止盈止损订单)
5binance_get_open_algo_orders(symbol="BTCUSDT")
6
7# 撤销指定订单
8binance_cancel_order(symbol="BTCUSDT", orderId=123456789)
9
10# 撤销所有普通挂单
11binance_cancel_all_orders(symbol="BTCUSDT")
12
13# 撤销单个条件单 (止盈止损)
14binance_cancel_algo_order(symbol="BTCUSDT", algoId=123456789)
15
16# 撤销所有条件单 (止盈止损)
17binance_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

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

风险提示

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