Binance Spot API Skill

Use this skill to run Binance Spot REST operations through

uxc

+ OpenAPI.

Reuse the

uxc

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

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

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
```

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

Testnet API Key Setup

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.

Recommended Credential Setup

Binance recommends

Ed25519

. Store the private key PEM text in an environment variable, or source it from 1Password.

bash

export BINANCE_TESTNET_ED25519_PRIVATE_KEY="$(cat /absolute/path/to/binance_testnet_ed25519_private.pem)"
export BINANCE_MAINNET_ED25519_PRIVATE_KEY="$(cat /absolute/path/to/binance_mainnet_ed25519_private.pem)"

Create one credential per environment so mainnet and testnet keys are never mixed:

bash

uxc auth credential set binance-spot-mainnet \
  --auth-type api_key \
  --field api_key=env:BINANCE_MAINNET_API_KEY \
  --field private_key=env:BINANCE_MAINNET_ED25519_PRIVATE_KEY

uxc auth credential set binance-spot-testnet \
  --auth-type api_key \
  --field api_key=env:BINANCE_TESTNET_API_KEY \
  --field private_key=env:BINANCE_TESTNET_ED25519_PRIVATE_KEY

Add one signer binding per environment:

bash

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

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

HMAC Fallback

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

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

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
```

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
```

Signed Writes

```
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> ...

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

binance-spot-openapi-skill

NPX Install

Tags

SKILL.md Content

Binance Spot API Skill

Prerequisites

Scope

Authentication

Testnet API Key Setup

Recommended Credential Setup

HMAC Fallback

Core Workflow

Operation Groups

Public Market

Signed Reads

Signed Writes

Guardrails

References