/binance-spot-openapi-skill

name: binance-spot-openapi-skill
description: Operate Binance Spot market, account, and order APIs through UXC with a curated OpenAPI schema, Binance query signing, and separate mainnet/testnet link flows.

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:

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

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

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:

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:

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:

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_u