derivatives-trading-coin-futures

Binance 衍生品交易币本位期货 Skill

通过经过身份验证的 API 端点在 Binance 上发起衍生品交易币本位期货请求。某些端点需要 API key 和 secret key。以 JSON 格式返回结果。

快速参考

Endpoint	描述	必需	可选	身份验证
/dapi/v1/account (GET)	账户信息（USER_DATA）	无	recvWindow	是
/dapi/v1/balance (GET)	合约账户余额（USER_DATA）	无	recvWindow	是
/dapi/v1/positionSide/dual (GET)	获取当前持仓模式（USER_DATA）	无	recvWindow	是
/dapi/v1/positionSide/dual (POST)	更改持仓模式（TRADE）	dualSidePosition	recvWindow	是
/dapi/v1/order/asyn (GET)	获取合约订单历史记录的下载 ID（USER_DATA）	startTime, endTime	recvWindow	是
/dapi/v1/trade/asyn (GET)	获取合约交易历史记录的下载 ID（USER_DATA）	startTime, endTime	recvWindow	是
/dapi/v1/income/asyn (GET)	获取合约交易历史记录的下载 ID（USER_DATA）	startTime, endTime	recvWindow	是
/dapi/v1/order/asyn/id (GET)	通过 ID 获取合约订单历史记录下载链接（USER_DATA）	downloadId	recvWindow	是
/dapi/v1/trade/asyn/id (GET)	通过 ID 获取合约交易历史记录下载链接（USER_DATA）	downloadId	recvWindow	是
/dapi/v1/income/asyn/id (GET)	通过 ID 获取合约交易历史记录下载链接（USER_DATA）	downloadId	recvWindow	是
/dapi/v1/income (GET)	获取收入历史记录（USER_DATA）	无	symbol, incomeType, startTime, endTime, page, limit, recvWindow	是
/dapi/v1/leverageBracket (GET)	交易对名义价值档位（USER_DATA）	无	pair, recvWindow	是
/dapi/v2/leverageBracket (GET)	交易品种名义价值档位（USER_DATA）	无	symbol, recvWindow	是
/dapi/v1/commissionRate (GET)	用户手续费率（USER_DATA）	symbol	recvWindow	是
/dapi/v1/ticker/24hr (GET)	24 小时行情价格变动统计	无	symbol, pair	否
/futures/data/basis (GET)	基差	pair, contractType, period	limit, startTime, endTime	否
/dapi/v1/time (GET)	检查服务器时间	无	无	否
/dapi/v1/aggTrades (GET)	压缩／聚合交易列表	symbol	fromId, startTime, endTime, limit	否
/dapi/v1/continuousKlines (GET)	连续合约 K 线／蜡烛图数据	pair, contractType, interval	startTime, endTime, limit	否
/dapi/v1/exchangeInfo (GET)	交易所信息	无	无	否
/dapi/v1/fundingInfo (GET)	获取资金费率信息	无	无	否
/dapi/v1/fundingRate (GET)	获取永续合约资金费率历史记录	symbol	startTime, endTime, limit	否
/dapi/v1/constituents (GET)	查询指数价格成分	symbol	无	否
/dapi/v1/indexPriceKlines (GET)	指数价格 K 线／蜡烛图数据	pair, interval	startTime, endTime, limit	否
/dapi/v1/premiumIndex (GET)	指数价格和标记价格	无	symbol, pair	否
/dapi/v1/klines (GET)	K 线／蜡烛图数据	symbol, interval	startTime, endTime, limit	否
/futures/data/globalLongShortAccountRatio (GET)	多空比	pair, period	limit, startTime, endTime	否
/dapi/v1/markPriceKlines (GET)	标记价格 K 线／蜡烛图数据	symbol, interval	startTime, endTime, limit	否
/dapi/v1/historicalTrades (GET)	查询历史交易（MARKET_DATA）	symbol	limit, fromId	否
/futures/data/openInterestHist (GET)	未平仓合约统计	pair, contractType, period	limit, startTime, endTime	否
/dapi/v1/openInterest (GET)	未平仓合约	symbol	无	否
/dapi/v1/depth (GET)	订单簿	symbol	limit	否
/dapi/v1/premiumIndexKlines (GET)	溢价指数 K 线数据	symbol, interval	startTime, endTime, limit	否
/dapi/v1/trades (GET)	最近交易列表	symbol	limit	否
/dapi/v1/ticker/bookTicker (GET)	交易品种订单簿行情	无	symbol, pair	否
/dapi/v1/ticker/price (GET)	交易品种价格行情	无	symbol, pair	否
/futures/data/takerBuySellVol (GET)	主动买入／卖出量	pair, contractType, period	limit, startTime, endTime	否
/dapi/v1/ping (GET)	测试连通性	无	无	否
/futures/data/topLongShortAccountRatio (GET)	顶级交易者多空比（账户）	symbol, period	limit, startTime, endTime	否
/futures/data/topLongShortPositionRatio (GET)	顶级交易者多空比（持仓）	pair, period	limit, startTime, endTime	否
/dapi/v1/pmAccountInfo (GET)	经典组合保证金账户信息（USER_DATA）	asset	recvWindow	是
/dapi/v1/userTrades (GET)	账户交易列表（USER_DATA）	无	symbol, pair, orderId, startTime, endTime, fromId, limit, recvWindow	是
/dapi/v1/allOrders (GET)	所有订单（USER_DATA）	无	symbol, pair, orderId, startTime, endTime, limit, recvWindow	是
/dapi/v1/countdownCancelAll (POST)	自动取消所有未成交订单（TRADE）	symbol, countdownTime	recvWindow	是
/dapi/v1/allOpenOrders (DELETE)	取消所有未成交订单（TRADE）	symbol	recvWindow	是
/dapi/v1/batchOrders (DELETE)	取消多个订单（TRADE）	symbol	orderIdList, origClientOrderIdList, recvWindow	是
/dapi/v1/batchOrders (PUT)	修改多个订单（TRADE）	batchOrders	recvWindow	是
/dapi/v1/batchOrders (POST)	下多个订单（TRADE）	batchOrders	recvWindow	是
/dapi/v1/order (DELETE)	取消订单（TRADE）	symbol	orderId, origClientOrderId, recvWindow	是
/dapi/v1/order (PUT)	修改订单（TRADE）	symbol, side	orderId, origClientOrderId, quantity, price, priceMatch, recvWindow	是
/dapi/v1/order (POST)	新建订单（TRADE）	symbol, side, type	positionSide, timeInForce, quantity, reduceOnly, price, newClientOrderId, stopPrice, closePosition, activationPrice, callbackRate, workingType, priceProtect, newOrderRespType, priceMatch, selfTradePreventionMode, recvWindow	是
/dapi/v1/order (GET)	查询订单（USER_DATA）	symbol	orderId, origClientOrderId, recvWindow	是
/dapi/v1/leverage (POST)	更改初始杠杆（TRADE）	symbol, leverage	recvWindow	是
/dapi/v1/marginType (POST)	更改保证金类型（TRADE）	symbol, marginType	recvWindow	是
/dapi/v1/openOrders (GET)	当前所有未成交订单（USER_DATA）	无	symbol, pair, recvWindow	是
/dapi/v1/orderAmendment (GET)	获取订单修改历史记录（USER_DATA）	symbol	orderId, origClientOrderId, startTime, endTime, limit, recvWindow	是
/dapi/v1/positionMargin/history (GET)	获取持仓保证金变更历史记录（TRADE）	symbol	type, startTime, endTime, limit, recvWindow	是
/dapi/v1/positionMargin (POST)	修改逐仓持仓保证金（TRADE）	symbol, amount, type	positionSide, recvWindow	是
/dapi/v1/adlQuantile (GET)	持仓 ADL 分位数估算（USER_DATA）	无	symbol, recvWindow	是
/dapi/v1/positionRisk (GET)	持仓信息（USER_DATA）	无	marginAsset, pair, recvWindow	是
/dapi/v1/openOrder (GET)	查询当前未成交订单（USER_DATA）	symbol	orderId, origClientOrderId, recvWindow	是
/dapi/v1/forceOrders (GET)	用户强平订单（USER_DATA）	无	symbol, autoCloseType, startTime, endTime, limit, recvWindow	是
/dapi/v1/listenKey (DELETE)	关闭用户数据流（USER_STREAM）	无	无	否
/dapi/v1/listenKey (PUT)	保持用户数据流活跃（USER_STREAM）	无	无	否
/dapi/v1/listenKey (POST)	启动用户数据流（USER_STREAM）	无	无	否

---

参数

通用参数

• recvWindow：（例如，5000）
• startTime：毫秒时间戳（例如，1623319461670）
• endTime：毫秒时间戳（例如，1641782889000）
• downloadId：通过下载 ID API 获取（例如，1）
• symbol：
• incomeType："TRANSFER"、"WELCOME_BONUS"、"FUNDING_FEE"、"REALIZED_PNL"、"COMMISSION"、"INSURANCE_CLEAR" 和 "DELIVERED_SETTELMENT"
• startTime：（例如，1623319461670）
• endTime：（例如，1641782889000）
• page：
• limit：默认值为 100；最大值为 1000（例如，100）
• pair：
• symbol：
• pair：BTCUSD
• fromId：获取聚合交易的起始 ID（包含该 ID）。（例如，1）
• asset：
• orderId：（例如，1）
• orderId：（例如，1）
• countdownTime：倒计时时间，1000 表示 1 秒。设为 0 可取消计时器
• orderIdList：最大长度为 10，例如 [1234567,2345678]
• origClientOrderIdList：最大长度为 10，例如 ["my_id_1","my_id_2"]；对双引号进行编码。逗号后不要加空格。
• origClientOrderId：（例如，1）
• leverage：目标初始杠杆：1 到 125 之间的整数
• dualSidePosition："true"：双向持仓模式；"false"：单向持仓模式
• type：1：增加持仓保证金，2：减少持仓保证金
• amount：（例如，1.0）
• batchOrders：订单列表。最多 5 个订单
• quantity：以合约数量为单位的数量；当 closePosition=true 时不能发送（例如，1.0）
• price：（例如，1.0）
• reduceOnly："true" 或 "false"。默认值为 "false"。双向持仓模式下不能发送；当 closePosition=true 时不能发送（全部平仓）
• newClientOrderId：未完成订单中的唯一 ID。若未发送，则自动生成。只能是符合以下规则的字符串：^[\.A-Z\:/a-z0-9_-]{1,36}$（例如，1）
• stopPrice：用于 STOP/STOP_MARKET 或 TAKE_PROFIT/TAKE_PROFIT_MARKET 订单。（例如，1.0）
• closePosition：true、false；全部平仓，与 STOP_MARKET 或 TAKE_PROFIT_MARKET 配合使用。
• activationPrice：用于 TRAILING_STOP_MARKET 订单，默认使用最新价格（支持不同的 workingType）（例如，1.0）
• callbackRate：用于 TRAILING_STOP_MARKET 订单，最小值为 0.1，最大值为 10；1 表示 1%（例如，1.0）
• priceProtect："TRUE" 或 "FALSE"，默认值为 "FALSE"。用于 STOP/STOP_MARKET 或 TAKE_PROFIT/TAKE_PROFIT_MARKET 订单。
• batchOrders：订单列表。最多 5 个订单
• marginAsset：

枚举值

• contractType：PERPETUAL | CURRENT_QUARTER | NEXT_QUARTER | CURRENT_QUARTER_DELIVERING | NEXT_QUARTER_DELIVERING | PERPETUAL_DELIVERING
• period：5m | 15m | 30m | 1h | 2h | 4h | 6h | 12h | 1d
• interval：1m | 3m | 5m | 15m | 30m | 1h | 2h | 4h | 6h | 8h | 12h | 1d | 3d | 1w | 1M
• marginType：ISOLATED | CROSSED
• positionSide：BOTH | LONG | SHORT
• type：LIMIT | MARKET | STOP | STOP_MARKET | TAKE_PROFIT | TAKE_PROFIT_MARKET | TRAILING_STOP_MARKET
• side：BUY | SELL
• priceMatch：NONE | OPPONENT | OPPONENT_5 | OPPONENT_10 | OPPONENT_20 | QUEUE | QUEUE_5 | QUEUE_10 | QUEUE_20
• timeInForce：GTC | IOC | FOK | GTX
• workingType：MARK_PRICE | CONTRACT_PRICE
• newOrderRespType：ACK | RESULT
• selfTradePreventionMode：NONE | EXPIRE_TAKER | EXPIRE_BOTH | EXPIRE_MAKER
• autoCloseType：LIQUIDATION | ADL

身份验证

对于需要身份验证的端点，你需要提供 Binance API 凭据。 所需凭据：

• apiKey：你的 Binance API 密钥（用于请求头）
• secretKey：你的 Binance API 密钥（用于签名）

基础 URL：

• 主网：https://dapi.binance.com
• 测试网：https://testnet.binancefuture.com

安全

共享凭据

用户可以通过不同方式提供 Binance API 凭据。Agent 会先尝试通过前两种方式自动获取凭据，但用户也可以明确告知 Agent 凭据已设置或存储在 .env 文件中，此时 Agent 应重新读取该文件。Agent 也可以通过前两种方式发送 HTTP 请求，无需用户确认。

1. 环境变量

仅搜索以下指定变量（绝不转储完整环境变量）：

已授权的环境变量

• 主网：BINANCE_API_KEY 和 BINANCE_SECRET_KEY
• 测试网：BINANCE_TESTNET_API_KEY 和 BINANCE_TESTNET_SECRET_KEY

在单次 exec 调用中读取并使用，避免原始密钥进入 Agent 的上下文：

KEY="$BINANCE_API_KEY"
SECRET="$BINANCE_SECRET_KEY"

response=$(curl -s -X GET "$URL" \
  -H "X-MBX-APIKEY: $KEY" \
  --data-urlencode "param1=value1")

echo "$response"

必须在 OpenClaw 启动前设置环境变量。它们会在进程启动时继承，无法注入正在运行的实例。如需在不重启的情况下添加或更新凭据，请使用密钥文件（参见选项 2）。

2. 密钥文件（.env）

检查 ~/.openclaw/secrets.env、~/.env 或工作区中的 .env 文件。使用 grep 读取单个密钥，绝不要 source 整个文件：

# Try all credential locations in order
API_KEY=$(grep '^BINANCE_API_KEY=' ~/.openclaw/secrets.env 2>/dev/null | cut -d= -f2-)
SECRET_KEY=$(grep '^BINANCE_SECRET_KEY=' ~/.openclaw/secrets.env 2>/dev/null | cut -d= -f2-)

# Fallback: search .env in known directories (KEY=VALUE then raw line format)
for dir in ~/.openclaw ~; do
  [ -n "$API_KEY" ] && break
  env_file="$dir/.env"
  [ -f "$env_file" ] || continue

  # Read first two lines
  line1=$(sed -n '1p' "$env_file")
  line2=$(sed -n '2p' "$env_file")

  # Check if lines contain '=' indicating KEY=VALUE format
  if [[ "$line1" == *=* && "$line2" == *=* ]]; then
    API_KEY=$(grep '^BINANCE_API_KEY=' "$env_file" 2>/dev/null | cut -d= -f2-)
    SECRET_KEY=$(grep '^BINANCE_SECRET_KEY=' "$env_file" 2>/dev/null | cut -d= -f2-)
  else
    # Treat lines as raw values
    API_KEY="$line1"
    SECRET_KEY="$line2"
  fi
done

无需重启 OpenClaw，随时可以更新此文件；每次调用时都会重新读取密钥。用户可以告知你变量现已设置或已存储在 .env 文件中，此时你应重新读取该文件。

3. 内联文件

发送内容为以下格式的文件：

abc123...xyz
secret123...key

• 绝不运行 printenv、env、export，也绝不在未指定具体变量名的情况下运行 set
• 绝不对 env 文件运行未限定到特定密钥的 grep（必须使用 '^VARNAME='）
• 绝不将密钥文件载入 shell 环境（source .env 或 . .env）
• 仅读取当前任务明确需要的凭据
• 绝不在输出或回复中回显或记录原始凭据
• 如果 TOOLS.md 中包含真实凭据，绝不将其提交到版本控制；请将其添加到 .gitignore

绝不泄露 API 密钥和密钥文件

绝不泄露 API 密钥和密钥文件的位置。

绝不将 API 密钥和 Secret 发送到主网和测试网以外的任何网站。

绝不显示完整密钥

向用户显示凭据时：

• API 密钥： 显示前 5 位和后 4 位：su1Qc...8akf
• Secret Key： 始终屏蔽，仅显示最后 5 位：***...aws1

询问凭据时的回复示例： 账户：main API 密钥：su1Qc...8akf Secret：***...aws1 环境：主网

列出账户

列出账户时，仅显示名称和环境，绝不显示密钥： Binance 账户：

• main（主网/测试网）
• testnet-dev（测试网）
• futures-keys（主网）

主网交易

在主网执行交易前，始终先请用户输入“CONFIRM”确认。

---

Binance 账户

main

• API 密钥：your_mainnet_api_key
• Secret：your_mainnet_secret
• 测试网：false

testnet-dev

• API 密钥：your_testnet_api_key
• Secret：your_testnet_secret
• 测试网：true

TOOLS.md 结构

## Binance Accounts

### main
- API Key: abc123...xyz
- Secret: secret123...key
- Testnet: false
- Description: Primary trading account

### testnet-dev
- API Key: test456...abc
- Secret: testsecret...xyz
- Testnet: true
- Description: Development/testing

### futures-keys
- API Key: futures789...def
- Secret: futuressecret...uvw
- Testnet: false
- Description: Futures trading account

Agent 行为

1. 请求凭据：屏蔽密钥（仅显示最后 5 位）
2. 列出账户：显示名称和环境，绝不显示密钥
3. 选择账户：如有歧义则询问，默认选择 main
4. 在主网执行交易时，先请用户输入“CONFIRM”确认
5. 新凭据：询问名称、环境和签名模式
6. 当请求需要签名时，如果该请求不是订单，且 API 密钥未注明为 mainnet 或 testnet 密钥，则尝试向不同的基础 URL 发送请求并查看是否成功，无需询问用户。如果成功，则将密钥存储为对应的环境。

添加新账户

用户通过内联文件或消息提供新凭据时：

• 询问账户名称
• 询问：主网、测试网
• 将其存储在 TOOLS.md 中，并确认时屏蔽凭据

请求签名

对于需要签名的交易端点：

1. 先检测密钥类型，在签名前检查密钥格式。
2. 使用所有参数（包括时间戳，Unix 毫秒）构建查询字符串。
3. 根据 RFC 3986，使用 UTF-8 对参数进行百分比编码。
4. 根据账户配置，使用 secretKey 通过 HMAC SHA256、RSA 或 Ed25519 对查询字符串签名。
5. 将签名附加到查询字符串。
6. 包含 X-MBX-APIKEY 请求头。

否则，不要执行步骤 4–6。

新客户端订单 ID

对于包含 newClientOrderId 参数的端点，该值必须始终以 agent- 开头。如果未提供该参数，系统将自动生成 agent- 加 18 个随机字母数字字符。如果提供了值，则会为其添加 agent- 前缀。

示例：agent-1a2b3c4d5e6f7g8h9i

User Agent 请求头

包含 User-Agent 请求头，其值为：binance-derivatives-trading-coin-futures/1.1.0 (Skill)

实现详情请参阅 references/authentication.md。