derivatives-trading-portfolio-margin-pro

Binance 衍生品交易组合保证金专业版技能

通过经过身份验证的 API 端点，在 Binance 上执行衍生品交易组合保证金专业版请求。某些端点需要 API key 和 secret key。以 JSON 格式返回结果。

快速参考

端点	描述	必需	可选	身份验证
/sapi/v1/portfolio/bnb-transfer (POST)	BNB 转账（USER_DATA）	amount, transferSide	recvWindow	是
/sapi/v1/portfolio/repay-futures-switch (POST)	更改自动偿还期货状态（TRADE）	autoRepay	recvWindow	是
/sapi/v1/portfolio/repay-futures-switch (GET)	获取自动偿还期货状态（USER_DATA）	无	recvWindow	是
/sapi/v1/portfolio/repay (POST)	组合保证金专业版破产贷款偿还	无	from, recvWindow	是
/sapi/v1/portfolio/auto-collection (POST)	资金自动归集（USER_DATA）	无	recvWindow	是
/sapi/v1/portfolio/asset-collection (POST)	按资产归集资金（USER_DATA）	asset	recvWindow	是
/sapi/v2/portfolio/account (GET)	获取组合保证金专业版 SPAN 账户信息（USER_DATA）	无	recvWindow	是
/sapi/v1/portfolio/account (GET)	获取组合保证金专业版账户信息（USER_DATA）	无	recvWindow	是
/sapi/v1/portfolio/balance (GET)	获取组合保证金专业版账户余额（USER_DATA）	无	asset, recvWindow	是
/sapi/v1/portfolio/delta-mode (GET)	获取 Delta 模式状态（USER_DATA）	无	recvWindow	是
/sapi/v1/portfolio/delta-mode (POST)	切换 Delta 模式（TRADE）	deltaEnabled	recvWindow	是
/sapi/v1/portfolio/earn-asset-balance (GET)	获取组合保证金可转入的 Earn 资产余额（USER_DATA）	asset, transferType	recvWindow	是
/sapi/v1/portfolio/pmLoan (GET)	查询组合保证金专业版破产贷款金额（USER_DATA）	无	recvWindow	是
/sapi/v1/portfolio/interest-history (GET)	查询组合保证金专业版负余额利息历史记录（USER_DATA）	无	asset, startTime, endTime, size, recvWindow	是
/sapi/v1/portfolio/pmloan-history (GET)	查询组合保证金专业版破产贷款偿还历史记录（USER_DATA）	无	startTime, endTime, current, size, recvWindow	是
/sapi/v1/portfolio/repay-futures-negative-balance (POST)	偿还期货负余额（USER_DATA）	无	from, recvWindow	是
/sapi/v1/portfolio/earn-asset-transfer (POST)	为组合保证金转入或转出 LDUSDT/RWUSD（TRADE）	asset, transferType, amount	recvWindow	是
/sapi/v1/portfolio/collateralRate (GET)	组合保证金抵押品比率（MARKET_DATA）	无	无	否
/sapi/v1/portfolio/margin-asset-leverage (GET)	获取组合保证金资产杠杆（USER_DATA）	无	无	是
/sapi/v2/portfolio/collateralRate (GET)	组合保证金专业版分层抵押品比率（USER_DATA）	无	recvWindow	是
/sapi/v1/portfolio/asset-index-price (GET)	查询组合保证金资产指数价格（MARKET_DATA）	无	asset	否

---

参数

通用参数

• amount： （例如，1.0）
• transferSide："TO_UM"、"FROM_UM"
• recvWindow： （例如，5000）
• autoRepay：默认值：true；设为 false 可关闭自动偿还期货负余额功能（例如，true）
• from：SPOT 或 MARGIN，默认值为 SPOT（例如，SPOT）
• asset：LDUSDT 和 RWUSD
• asset：
• transferType：EARN_TO_FUTURE /FUTURE_TO_EARN
• startTime： （例如，1623319461670）
• endTime： （例如，1641782889000）
• size：默认值：10，最大值：100（例如，10）
• current：当前查询页码。从 1 开始。默认值：1（例如，1）
• deltaEnabled：true 启用 Delta 模式；false 禁用 Delta 模式

身份验证

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

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

基础 URL：

• 主网：https://api.binance.com

安全

共享凭据

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

1. 环境变量

仅搜索以下特定变量（绝不输出完整环境变量）：

授权的环境变量

• 主网：BINANCE_API_KEY 和 BINANCE_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
• 绝不在未锚定到特定密钥（'^VARNAME='）的情况下对 env 文件运行 grep
• 绝不将密钥文件载入 shell 环境（source .env 或 . .env）
• 仅读取当前任务明确需要的凭据
• 绝不在输出或回复中回显或记录原始凭据
• 如果 TOOLS.md 包含真实凭据，绝不将其提交到版本控制；应将其添加到 .gitignore

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

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

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

绝不显示完整密钥

向用户显示凭据时：

• API 密钥： 显示前 5 个字符和后 4 个字符：su1Qc...8akf
• 密钥密文： 始终遮蔽，仅显示最后 5 个字符：***...aws1

用户询问凭据时的回复示例： 账户：main API 密钥：su1Qc...8akf 密钥密文：***...aws1

列出账户

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

• main（主网）
• futures-keys（主网）

主网交易

在主网执行交易时，务必先向用户确认，并要求用户回复 "CONFIRM" 后再继续。

---

Binance 账户

main

• API 密钥：your_mainnet_api_key
• 密钥密文：your_mainnet_secret

TOOLS.md 结构

## Binance Accounts

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


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

Agent 行为

1. 请求凭据：遮蔽密钥（仅显示最后 5 个字符）
2. 列出账户：显示名称和环境，绝不显示密钥
3. 选择账户：有歧义时询问，默认选择 main
4. 在主网执行交易时，先向用户确认，并要求用户回复 "CONFIRM" 后再继续
5. 新凭据：询问名称、环境和签名模式

添加新账户

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

• 询问账户名称
• 将凭据存储在 TOOLS.md 中，并确认时以遮蔽形式显示

请求签名

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

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

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

User Agent 标头

添加 User-Agent 标头，值为以下字符串：binance-derivatives-trading-portfolio-margin-pro/1.1.0 (Skill)

有关实现细节，请参阅 references/authentication.md。