🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
BytesAgain β€Ί Skills β€Ί Binance Spot OpenAPI Skill
πŸ¦€ ClawHub

Binance Spot OpenAPI Skill

by @jolestar

Operate Binance Spot market, account, and order APIs through UXC with a curated OpenAPI schema, Binance query signing, and separate mainnet/testnet link flows.

Versionv1.0.1
Downloads632
Installs1
#clawhub
TERMINAL
clawhub install binance-spot-openapi-skill

πŸ“– About This 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_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

  • 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 ... is equivalent to uxc --schema-url ....

    • 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

    • βš™οΈ Configuration

  • 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