Binance Spot Openapi Skill

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_unit":"milliseconds","canonicalization":{"mode":"preserve_order"}}' \
  --priority 100

Core Workflow

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

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

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

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