UXC

One CLI for tools across protocols.

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

Scope

This skill covers curated Binance Spot REST endpoints for:

This skill does not cover:

Authentication

Public market endpoints do not require credentials.

Signed Spot endpoints require:

Testnet API Key Setup

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

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:

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

Operation Groups

Public Market

Signed Reads

Signed Writes

Guardrails

References