binance-spot-openapi-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Binance Spot API Skill

Binance Spot API 技能

Use this skill to run Binance Spot REST operations through

uxc

+ OpenAPI.

Reuse the

uxc

skill for shared execution, auth, and error-handling guidance.

使用此技能通过

uxc

+ OpenAPI执行Binance现货REST操作。

复用

uxc

技能以获取共享的执行、认证和错误处理指引。

Prerequisites

前置条件

```
uxc
```
is installed and available in
```
PATH
```
.

Network access to:

```
https://api.binance.com
```
```
https://testnet.binance.vision
```

Access to the curated OpenAPI schema URL:

https://raw.githubusercontent.com/holon-run/uxc/main/skills/binance-spot-openapi-skill/references/binance-spot.openapi.json

```
uxc
```
已安装且可在
```
PATH
```
中访问。

可访问以下网络地址：

```
https://api.binance.com
```
```
https://testnet.binance.vision
```

可访问精选OpenAPI schema的URL：

https://raw.githubusercontent.com/holon-run/uxc/main/skills/binance-spot-openapi-skill/references/binance-spot.openapi.json

Scope

适用范围

This skill covers curated Binance Spot REST endpoints for:

public market reads
signed account reads
signed order queries
test orders
order placement and cancellation

This skill does not cover:

OCO, OTO, OTOCO, OPO, OPOCO, or other
```
orderList/*
```
endpoints
```
order/cancelReplace
```
```
order/amend/*
```
```
historicalTrades
```
```
uiKlines
```
```
ticker/tradingDay
```
SOR endpoints
Wallet, Margin, Earn, or
```
/sapi/*
```
endpoints
RSA request signing
```
https://demo-api.binance.com
```

此技能涵盖精选的Binance现货REST端点，用于：

公开市场数据读取
签名账户数据读取
签名订单查询
测试订单
订单下单与取消

此技能不涵盖：

OCO、OTO、OTOCO、OPO、OPOCO或其他
```
orderList/*
```
端点
```
order/cancelReplace
```
```
order/amend/*
```
```
historicalTrades
```
```
uiKlines
```
```
ticker/tradingDay
```
SOR端点
钱包、杠杆、理财或
```
/sapi/*
```
端点
RSA请求签名
```
https://demo-api.binance.com
```

Authentication

认证

Public market endpoints do not require credentials.

Signed Spot endpoints require:

```
api_key
```
field for
```
X-MBX-APIKEY
```
```
private_key
```
field for Ed25519 PKCS#8 PEM signing, or
```
secret_key
```
for deprecated HMAC SHA256 signing

公开市场端点无需凭证。

签名现货端点需要：

```
api_key
```
字段，用于
```
X-MBX-APIKEY
```
```
private_key
```
字段，用于Ed25519 PKCS#8 PEM签名，或
```
secret_key
```
用于已弃用的HMAC SHA256签名

Testnet API Key Setup

测试网API密钥设置

Binance Spot testnet uses a separate host and separate API key records from mainnet:

base URL:
```
https://testnet.binance.vision
```
testnet API keys do not work on mainnet
mainnet API keys do not work on testnet

There are two practical testnet flows:

```
Ed25519
```
(recommended by Binance)
- Generate an Ed25519 keypair locally.
- Register the public key in the Spot testnet API management UI.
- After registration, Binance shows a distinct
```
API key
```
  for that Ed25519 key record.
- Use that displayed
```
API key
```
  in
```
X-MBX-APIKEY
```
  , and use the matching private key PEM for signing.
```
HMAC
```
(legacy compatibility)
- Create an HMAC key in the Spot testnet API management UI.
- Binance shows both
```
API key
```
  and
```
Secret key
```
  .
- Use
```
API key
```
  in
```
X-MBX-APIKEY
```
  , and use
```
Secret key
```
  for HMAC SHA256 signing.

Important:

The Ed25519 public key you upload is not the
```
API key
```
.
Each Binance key record has its own
```
API key
```
.
Do not mix an HMAC
```
API key
```
with an Ed25519 private key, or an Ed25519
```
API key
```
with an HMAC secret.

If you do, Binance returns

-1022 Signature for this request is not valid.

Binance现货测试网使用独立的主机和API密钥记录，与主网不互通：

基础URL：
```
https://testnet.binance.vision
```
测试网API密钥无法在主网使用
主网API密钥无法在测试网使用

有两种实用的测试网流程：

```
Ed25519
```
（Binance推荐）
- 本地生成Ed25519密钥对。
- 在现货测试网API管理UI中注册公钥。
- 注册后，Binance会为该Ed25519密钥记录显示一个唯一的
```
API key
```
  。
- 在
```
X-MBX-APIKEY
```
  中使用该显示的
```
API key
```
  ，并使用匹配的私钥PEM进行签名。
```
HMAC
```
（遗留兼容性）
- 在现货测试网API管理UI中创建HMAC密钥。
- Binance会显示
```
API key
```
  和
```
Secret key
```
  。
- 在
```
X-MBX-APIKEY
```
  中使用
```
API key
```
  ，并使用
```
Secret key
```
  进行HMAC SHA256签名。

重要提示：

你上传的Ed25519公钥不是
```
API key
```
。
每个Binance密钥记录都有自己的
```
API key
```
。
不要将HMAC的
```
API key
```
与Ed25519私钥混用，也不要将Ed25519的
```
API key
```
与HMAC密钥混用。

如果混用，Binance会返回

-1022 Signature for this request is not valid.

Recommended Credential Setup

HMAC Fallback

HMAC兼容方案

If you already have legacy HMAC keys,

uxc

still supports them:

bash

uxc auth credential set binance-spot-mainnet-hmac \
  --auth-type api_key \
  --field api_key=env:BINANCE_MAINNET_API_KEY \
  --field secret_key=env:BINANCE_MAINNET_SECRET_KEY

uxc auth credential set binance-spot-testnet-hmac \
  --auth-type api_key \
  --field api_key=env:BINANCE_TESTNET_API_KEY \
  --field secret_key=env:BINANCE_TESTNET_SECRET_KEY

uxc auth binding add \
  --id binance-spot-mainnet-hmac \
  --host api.binance.com \
  --path-prefix /api/v3 \
  --scheme https \
  --credential binance-spot-mainnet-hmac \
  --signer-json '{"kind":"hmac_query_v1","algorithm":"hmac_sha256","signing_field":"secret_key","key_field":"api_key","key_placement":"header","key_name":"X-MBX-APIKEY","signature_param":"signature","signature_encoding":"hex","timestamp_param":"timestamp","timestamp_unit":"milliseconds","canonicalization":{"mode":"preserve_order"}}' \
  --priority 100

uxc auth binding add \
  --id binance-spot-testnet-hmac \
  --host testnet.binance.vision \
  --path-prefix /api/v3 \
  --scheme https \
  --credential binance-spot-testnet-hmac \
  --signer-json '{"kind":"hmac_query_v1","algorithm":"hmac_sha256","signing_field":"secret_key","key_field":"api_key","key_placement":"header","key_name":"X-MBX-APIKEY","signature_param":"signature","signature_encoding":"hex","timestamp_param":"timestamp","timestamp_unit":"milliseconds","canonicalization":{"mode":"preserve_order"}}' \
  --priority 100

如果你已有遗留的HMAC密钥，

uxc

仍然支持：

bash

uxc auth credential set binance-spot-mainnet-hmac \
  --auth-type api_key \
  --field api_key=env:BINANCE_MAINNET_API_KEY \
  --field secret_key=env:BINANCE_MAINNET_SECRET_KEY

uxc auth credential set binance-spot-testnet-hmac \
  --auth-type api_key \
  --field api_key=env:BINANCE_TESTNET_API_KEY \
  --field secret_key=env:BINANCE_TESTNET_SECRET_KEY

uxc auth binding add \
  --id binance-spot-mainnet-hmac \
  --host api.binance.com \
  --path-prefix /api/v3 \
  --scheme https \
  --credential binance-spot-mainnet-hmac \
  --signer-json '{"kind":"hmac_query_v1","algorithm":"hmac_sha256","signing_field":"secret_key","key_field":"api_key","key_placement":"header","key_name":"X-MBX-APIKEY","signature_param":"signature","signature_encoding":"hex","timestamp_param":"timestamp","timestamp_unit":"milliseconds","canonicalization":{"mode":"preserve_order"}}' \
  --priority 100

uxc auth binding add \
  --id binance-spot-testnet-hmac \
  --host testnet.binance.vision \
  --path-prefix /api/v3 \
  --scheme https \
  --credential binance-spot-testnet-hmac \
  --signer-json '{"kind":"hmac_query_v1","algorithm":"hmac_sha256","signing_field":"secret_key","key_field":"api_key","key_placement":"header","key_name":"X-MBX-APIKEY","signature_param":"signature","signature_encoding":"hex","timestamp_param":"timestamp","timestamp_unit":"milliseconds","canonicalization":{"mode":"preserve_order"}}' \
  --priority 100

Core Workflow

核心工作流程

Use fixed link commands by default:

command -v binance-spot-mainnet-openapi-cli

If missing, create it:

uxc link binance-spot-mainnet-openapi-cli https://api.binance.com --schema-url https://raw.githubusercontent.com/holon-run/uxc/main/skills/binance-spot-openapi-skill/references/binance-spot.openapi.json

command -v binance-spot-testnet-openapi-cli

If missing, create it:

uxc link binance-spot-testnet-openapi-cli https://testnet.binance.vision --schema-url https://raw.githubusercontent.com/holon-run/uxc/main/skills/binance-spot-openapi-skill/references/binance-spot.openapi.json

Discover operations with help-first flow:

```
binance-spot-mainnet-openapi-cli -h
```
```
binance-spot-testnet-openapi-cli -h
```

binance-spot-testnet-openapi-cli post:/api/v3/order/test -h

binance-spot-testnet-openapi-cli get:/api/v3/account -h

Execute reads first:

public read:

binance-spot-mainnet-openapi-cli get:/api/v3/ticker/price symbol=BTCUSDT

signed read:

binance-spot-testnet-openapi-cli get:/api/v3/account omitZeroBalances=true recvWindow=5000

Use

order/test

before real writes:

binance-spot-testnet-openapi-cli post:/api/v3/order/test symbol=BTCUSDT side=BUY type=MARKET quoteOrderQty=100 recvWindow=5000

默认使用固定链接命令：

command -v binance-spot-mainnet-openapi-cli

如果不存在，创建它：

uxc link binance-spot-mainnet-openapi-cli https://api.binance.com --schema-url https://raw.githubusercontent.com/holon-run/uxc/main/skills/binance-spot-openapi-skill/references/binance-spot.openapi.json

command -v binance-spot-testnet-openapi-cli

如果不存在，创建它：

uxc link binance-spot-testnet-openapi-cli https://testnet.binance.vision --schema-url https://raw.githubusercontent.com/holon-run/uxc/main/skills/binance-spot-openapi-skill/references/binance-spot.openapi.json

通过帮助优先流程发现操作：

```
binance-spot-mainnet-openapi-cli -h
```
```
binance-spot-testnet-openapi-cli -h
```

binance-spot-testnet-openapi-cli post:/api/v3/order/test -h

binance-spot-testnet-openapi-cli get:/api/v3/account -h

优先执行读取操作：

公开读取：

binance-spot-mainnet-openapi-cli get:/api/v3/ticker/price symbol=BTCUSDT

签名读取：

binance-spot-testnet-openapi-cli get:/api/v3/account omitZeroBalances=true recvWindow=5000

在实际写入前使用

order/test

：

binance-spot-testnet-openapi-cli post:/api/v3/order/test symbol=BTCUSDT side=BUY type=MARKET quoteOrderQty=100 recvWindow=5000

Operation Groups

操作分组

Public Market

公开市场

```
get:/api/v3/ping
```
```
get:/api/v3/time
```
```
get:/api/v3/exchangeInfo
```
```
get:/api/v3/avgPrice
```
```
get:/api/v3/depth
```
```
get:/api/v3/klines
```
```
get:/api/v3/ticker/24hr
```
```
get:/api/v3/ticker/price
```
```
get:/api/v3/trades
```

```
get:/api/v3/ping
```
```
get:/api/v3/time
```
```
get:/api/v3/exchangeInfo
```
```
get:/api/v3/avgPrice
```
```
get:/api/v3/depth
```
```
get:/api/v3/klines
```
```
get:/api/v3/ticker/24hr
```
```
get:/api/v3/ticker/price
```
```
get:/api/v3/trades
```

Signed Reads

签名读取

```
get:/api/v3/account
```
```
get:/api/v3/openOrders
```
```
get:/api/v3/order
```
```
get:/api/v3/allOrders
```
```
get:/api/v3/myTrades
```
```
get:/api/v3/rateLimit/order
```

```
get:/api/v3/account
```
```
get:/api/v3/openOrders
```
```
get:/api/v3/order
```
```
get:/api/v3/allOrders
```
```
get:/api/v3/myTrades
```
```
get:/api/v3/rateLimit/order
```

Signed Writes

签名写入

```
post:/api/v3/order/test
```
```
post:/api/v3/order
```
```
delete:/api/v3/order
```
```
delete:/api/v3/openOrders
```

```
post:/api/v3/order/test
```
```
post:/api/v3/order
```
```
delete:/api/v3/order
```
```
delete:/api/v3/openOrders
```

Guardrails

防护措施

Keep automation on the JSON output envelope; do not use
```
--text
```
.
Parse stable fields first:
```
ok
```
,
```
kind
```
,
```
protocol
```
,
```
data
```
,
```
error
```
.
Treat
```
order/test
```
as the default validation path before any real order placement.
Treat all mainnet write operations as high-risk and require explicit user confirmation before execution.
Prefer testnet for all signed examples unless the user explicitly asks for mainnet.
Before placing orders, query
```
exchangeInfo
```
for symbol filters and
```
ticker/price
```
or
```
depth
```
for current market context.
If Binance returns
```
-1021
```
, call
```
get:/api/v3/time
```
, then retry with a fresh timestamp and, if needed, a larger
```
recvWindow
```
.
If Binance returns
```
-1022
```
, first verify you are using the
```
API key
```
from the same Binance key record as the signing material:
- Ed25519: displayed
```
API key
```
  + matching private key PEM
- HMAC: displayed
```
API key
```
  + matching
```
Secret key
```
Use
```
--path-prefix /api/v3
```
on auth bindings.
```
uxc
```
now resolves OpenAPI auth against the final operation URL, so this narrower binding works for signed Spot requests and avoids over-broad host-level matching.
```
timestamp
```
and
```
signature
```
are injected by the signer binding; users normally provide business parameters plus optional
```
recvWindow
```
.

binance-spot-*-openapi-cli <operation> ...

is equivalent to

uxc <host> --schema-url <binance_spot_openapi_schema> <operation> ...

仅对JSON输出包进行自动化处理；不要使用
```
--text
```
参数。
优先解析稳定字段：
```
ok
```
、
```
kind
```
、
```
protocol
```
、
```
data
```
、
```
error
```
。
在实际下单前，将
```
order/test
```
作为默认验证流程。
将所有主网写入操作视为高风险操作，执行前需用户明确确认。
除非用户明确要求主网，否则所有签名示例优先使用测试网。
下单前，查询
```
exchangeInfo
```
获取交易对限制，查询
```
ticker/price
```
或
```
depth
```
获取当前市场信息。
如果Binance返回
```
-1021
```
，调用
```
get:/api/v3/time
```
，然后使用新的时间戳重试，必要时增大
```
recvWindow
```
。
如果Binance返回
```
-1022
```
，首先验证你使用的
```
API key
```
与签名材料来自同一Binance密钥记录：
- Ed25519：显示的
```
API key
```
  + 匹配的私钥PEM
- HMAC：显示的
```
API key
```
  + 匹配的
```
Secret key
```
在认证绑定上使用
```
--path-prefix /api/v3
```
。
```
uxc
```
现在会针对最终操作URL解析OpenAPI认证，因此这个更窄的绑定适用于签名现货请求，避免过度宽泛的主机级匹配。
```
timestamp
```
和
```
signature
```
由签名绑定自动注入；用户通常只需提供业务参数以及可选的
```
recvWindow
```
。

binance-spot-*-openapi-cli <operation> ...

等价于

uxc <host> --schema-url <binance_spot_openapi_schema> <operation> ...

。

References

参考资料

Usage patterns:
```
references/usage-patterns.md
```
Curated OpenAPI schema:
```
references/binance-spot.openapi.json
```
Binance Spot skill source material: https://github.com/binance/binance-skills-hub/tree/main/skills/binance/spot
Official Binance Spot API docs: https://github.com/binance/binance-spot-api-docs

使用模式：
```
references/usage-patterns.md
```
精选OpenAPI schema：
```
references/binance-spot.openapi.json
```
Binance现货技能源材料：https://github.com/binance/binance-skills-hub/tree/main/skills/binance/spot
官方Binance现货API文档：https://github.com/binance/binance-spot-api-docs