Fiat

Binance Fiat Skill

Query Binance fiat payment capabilities, available payment methods, pricing, and supported currencies/countries using public APIs (no authentication required). For order and payment history, see Authenticated Endpoints.

Base URL

https://www.binance.com/bapi/fiat/v1/public/fiatpayment/agent

Available APIs

1. get_capabilities

Query supported fiat currencies, cryptos, and business types for a country.

curl "https://www.binance.com/bapi/fiat/v1/public/fiatpayment/agent/get-capabilities?country={COUNTRY_CODE}"

Optional: businessType (BUY, SELL, DEPOSIT, WITHDRAW) to filter.

Response: data.supportedBusinessTypes, data.fiatCurrencies[] (with code, name, supportedBusinessTypes), data.cryptoCurrencies[]

2. get_buy_and_sell_payment_methods

curl "https://www.binance.com/bapi/fiat/v1/public/fiatpayment/agent/get-buy-and-sell-payment-methods?businessType={BUY|SELL}&fiatCurrency={FIAT}&cryptoCurrency={CRYPTO}&country={COUNTRY_CODE}"

All 4 parameters required.

Response: data.paymentMethods[] and data.p2pPaymentMethods[], each with code, paymentMethodName, fiatMinLimit, fiatMaxLimit, cryptoMinLimit, cryptoMaxLimit, quotation, suspended

3. get_deposit_and_withdraw_payment_methods

curl "https://www.binance.com/bapi/fiat/v1/public/fiatpayment/agent/get-deposit-and-withdraw-payment-methods?businessType={DEPOSIT|WITHDRAW}&fiatCurrency={FIAT}&country={COUNTRY_CODE}"

All 3 parameters required. No cryptoCurrency, no quotation, no P2P methods.

Response: data.paymentMethods[] with code, paymentMethodName, fiatMinLimit, fiatMaxLimit, suspended

4. get_price

curl "https://www.binance.com/bapi/fiat/v1/public/fiatpayment/agent/get-price?fiatCurrency={FIAT}&cryptoCurrency={CRYPTO}&country={COUNTRY_CODE}"

Optional: businessType (BUY or SELL, defaults to BUY).

Response: data.bestPrice — indicative reference price, may differ from execution price

Recommended Workflow

1. `get_capabilities` first — confirms what's supported before making other calls 2. Payment methods API — BUY/SELL → get_buy_and_sell_payment_methods; DEPOSIT/WITHDRAW → get_deposit_and_withdraw_payment_methods 3. `get_price` — add if the user wants exchange rate info

Skip step 1 for simple price queries (e.g., "What's BTC in USD?").

Calling APIs

Use WebFetch or Bash (curl). All responses follow:

{ "code": "000000", "message": null, "data": { ... }, "success": true }

code: "000000" = success; otherwise check message.

Action Links

After presenting API results, always include a relevant action link so the user can proceed directly on Binance. Build the URL dynamically based on the fiat currency, crypto currency, and business type from the conversation context.

URL Templates

Language-aware URL

Replace the /en/ locale segment to match the user's language. Supported locales:

en, zh-CN, zh-TC, ru, es, es-LA, fr, vi, en-TR, it, pl, id, uk-UA, ar,
en-AU, pt-BR, en-IN, en-NG, ro, bg, cs, lv, sv, pt, es-MX, el, sk, sl,
es-AR, fr-AF, en-KZ, en-ZA, en-NZ, en-BH, ar-BH, ru-UA, de, kk-KZ,
ru-KZ, ja, da-DK, en-AE, en-JP, hu, lo-LA, si-LK, az-AZ, uz-UZ, pt-AO

Common mapping examples:

For regional English variants (en-AU, en-IN, en-NG, en-AE, en-NZ, etc.), use the specific regional locale rather than plain en — this ensures the user sees region-appropriate content.

Default to en if the user's language is unclear.

Always include at least one action link when the conversation involves a specific fiat/crypto pair or business type. For general questions, include all relevant links from get_capabilities. Format as a call-to-action, e.g.: "Ready to buy? Buy BTC with USD on Binance"

Presenting Results

• Table format for payment methods (names, limits, pricing); flag suspended methods
• Note that prices are indicative/reference prices
• Respond in the user's language
• Always end with the relevant action link(s)

Price Sorting and Best Value Logic

Price direction depends on the business type — always apply the correct comparison:

When summarizing: for BUY highlight the lowest quotation; for SELL highlight the highest quotation. Example (BUY USD/BTC): $70,236 beats $74,291 — more BTC per dollar.

Wallet Payment Method (BUY)

If the BUY response includes a payment method with code containing WALLET (case-insensitive), it represents buying crypto using the user's Binance fiat wallet balance.

When this occurs, proactively mention:

"One of the available payment methods is your Binance fiat wallet balance. If your wallet doesn't have sufficient funds, you'll need to deposit fiat first. Would you like me to look up the available deposit methods for you?"

If the user confirms, call get_deposit_and_withdraw_payment_methods with businessType=DEPOSIT using the same fiat currency and country, and present the results along with the Deposit action link.

Order & Payment History (Authenticated)

See `references/sapi-endpoints.md` for authenticated endpoints (order/payment history, deposit/withdraw records). Requires Binance API key and secret.

Country Code Reference

Use ISO 3166-1 alpha-2 codes: BR, GB, DE, FR, JP, KR, AU, etc. Never use `US` as the country parameter — US users are not supported by Binance fiat payment APIs.

Country Inference Rules

Determine the country parameter using this priority order:

1. Explicit context — If the country is already known from the conversation (user stated it, or inferred in a prior turn), reuse it without re-inferring.

2. Fiat currency → country mapping — Map directly from currency. Examples:

• SGD → SG, BRL → BR, JPY → JP, KRW → KR, AUD → AU, GBP → GB, CAD → CA, INR → IN, TRY → TR, MXN → MX, NGN → NG
• EUR → FR (since the user did not specify a country, use FR as the default for EUR)
• USD → SG (since the user did not specify a country, use SG as the default for USD)

MANDATORY: US MUST NEVER be used as the country parameter under any circumstances.

3. Empty results — If the API returns no payment methods or an unsupported combination, ask: "No results found for your current settings. Would you like to try a different country? If so, please tell me which country." Then use the country the user provides.

Changelog

1.1.0 - 2026-03-24

• Environmental variables or files can now be used as input for the API key and secret key.
• Fix signature generation for RSA and Ed25519 keys.
• Add Openclaw metadata to the User Agent header

1.0.0 - 2026-03-20

• Initial release

MIT License

Copyright (c) 2026 Binance

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Binance Authentication

All trading endpoints require either HMAC SHA256, RSA, or Ed25519 signed requests. Always detect the key type before signing, do not assume HMAC.

Base URLs

Required Headers

• X-MBX-APIKEY: your_api_key
• User-Agent: binance-fiat/1.1.0 (Skill)

Signing Process

Step 1: Build Query String

Include all parameters plus timestamp (current Unix time in milliseconds): transactionType=...&timestamp=1234567890123

Optional: Add recvWindow (default 5000ms) for timestamp tolerance.

Step 2: Percent‑Encode Parameters

Before generating the signature, percent‑encode all parameter names and values using UTF‑8 encoding according to RFC 3986. Unreserved characters that must not be encoded: A-Z a-z 0-9 - _ . ~

• Chinese characters example:

symbol=这是测试币456

Percent‑encoded: symbol=%E8%BF%99%E6%98%AF%E6%B5%8B%E8%AF%95%E5%B8%81456

Important: The exact encoded query string must be used for both signing and the HTTP request.

Step 3: Generate Signature

Generate the signature from the encoded query string.

HMAC SHA256 signature

Create HMAC SHA256 signature of the query string using your secret key:

# Example using openssl
echo -n "transactionType=...&timestamp=1234567890123" | \
  openssl dgst -sha256 -hmac "your_secret_key"

RSA signature

Create RSA signature of the query string using your private key:

# Example using openssl
echo -n "transactionType=...&timestamp=1234567890123" | \
  openssl dgst -sha256 -sign private_key.pem | base64

Ed25519 signature

Create Ed25519 signature of the query string using your private key:

# Example using openssl
echo -n "transactionType=...&timestamp=1234567890123" | \
  openssl pkeyutl -sign -inkey private_key.pem | base64

Step 4: Append Signature

Add signature parameter to the query string: transactionType=...&timestamp=1234567890123&signature=abc123...

Step 5: Add Product User Agent Header

Include User-Agent header with the following string: binance-fiat/1.1.0 (Skill)

Complete Example

Request:

curl -X GET "https://api.binance.com/sapi/v1/fiat/orders" \
  -H "X-MBX-APIKEY: your_api_key" \
  -H "User-Agent: binance-fiat/1.1.0 (Skill)" \
  -d "transactionType=...&timestamp=1234567890123&signature=..."

#!/bin/bash
API_KEY="your_api_key"
SECRET_KEY="your_secret_key"
BASE_URL="https://api.binance.com"  

# Get current timestamp
TIMESTAMP=$(date +%s000)

# Build query string (without signature)
QUERY="transactionType=...&timestamp=${TIMESTAMP}"

# Generate signature
# For HMAC SHA256:
SIGNATURE=$(echo -n "$QUERY" | openssl dgst -sha256 -hmac "$SECRET_KEY" | cut -d' ' -f2)

# For RSA or Ed25519, replace the above line with the appropriate signing command.
##  RSA:
# SIGNATURE=$(echo -n "$QUERY" | openssl dgst -sha256 -sign private_key.pem | base64)

##  Ed25519:
# SIGNATURE=$(echo -n "$QUERY" | openssl pkeyutl -sign -inkey private_key.pem | base64)

# Make request
curl -X GET "${BASE_URL}/sapi/v1/fiat/orders?${QUERY}&signature=${SIGNATURE}" \
  -H "X-MBX-APIKEY: ${API_KEY}"\
  -H "User-Agent: binance-fiat/1.1.0 (Skill)"

Security Notes

• Never share your secret key
• Use IP whitelist in Binance API settings
• Enable only required permissions (spot trading, no withdrawals)

Binance Fiat Skill

Fiat request on Binance using authenticated API endpoints. Requires API key and secret key for certain endpoints. Return the result in JSON format.

Quick Reference

---

Parameters

Common Parameters

• recvWindow: (e.g., 5000)
• transactionType: 0-buy,1-sell
• beginTime:
• endTime: (e.g., 1641782889000)
• page: default 1 (e.g., 1)
• rows: default 100, max 500 (e.g., 100)
• orderNo: order id retrieved from the api call of withdrawal

Authentication

For endpoints that require authentication, you will need to provide Binance API credentials. Required credentials:

• apiKey: Your Binance API key (for header)
• secretKey: Your Binance API secret (for signing)

Base URLs:

• Mainnet: https://api.binance.com

Security

Share Credentials

Users can provide Binance API credentials in different ways. The agent will try to retrieve automatically with the two first ways the credentials, but users can also explicitly tell the agent that they have set the credentials or stored them in a .env file, and the agent should re-read that file when they do. The agent can also make http requests with the two first methods without user confirmation.

1. Environment variables

Search for the following specific variables only (never dump the full environment):

Authorized environment variables

• Mainnet: BINANCE_API_KEY and BINANCE_SECRET_KEY

Read and use in a single exec call so the raw key never enters the agent's context:

KEY="$BINANCE_API_KEY"
SECRET="$BINANCE_SECRET_KEY"

response=$(curl -s -X GET "$URL" \
  -H "X-MBX-APIKEY: $KEY" \
  --data-urlencode "param1=value1")

echo "$response"

Environment variables must be set before OpenClaw starts. They are inherited at process startup and cannot be injected into a running instance. If you need to add or update credentials without restarting, use a secrets file (see option 2).

2. Secrets file (.env)

Check ~/.openclaw/secrets.env , ~/.env, or a .env file in the workspace. Read individual keys with grep, never source the full file:

# Try all credential locations in order
API_KEY=$(grep '^BINANCE_API_KEY=' ~/.openclaw/secrets.env 2>/dev/null | cut -d= -f2-)
SECRET_KEY=$(grep '^BINANCE_SECRET_KEY=' ~/.openclaw/secrets.env 2>/dev/null | cut -d= -f2-)

# Fallback: search .env in known directories (KEY=VALUE then raw line format)
for dir in ~/.openclaw ~; do
  [ -n "$API_KEY" ] && break
  env_file="$dir/.env"
  [ -f "$env_file" ] || continue

  # Read first two lines
  line1=$(sed -n '1p' "$env_file")
  line2=$(sed -n '2p' "$env_file")

  # Check if lines contain '=' indicating KEY=VALUE format
  if [[ "$line1" == *=* && "$line2" == *=* ]]; then
    API_KEY=$(grep '^BINANCE_API_KEY=' "$env_file" 2>/dev/null | cut -d= -f2-)
    SECRET_KEY=$(grep '^BINANCE_SECRET_KEY=' "$env_file" 2>/dev/null | cut -d= -f2-)
  else
    # Treat lines as raw values
    API_KEY="$line1"
    SECRET_KEY="$line2"
  fi
done

This file can be updated at any time without restarting OpenClaw, keys are read fresh on each invocation. Users can tell you the variables are now set or stored in a .env file, and you should re-read that file when they do.

3. Inline file

Sending a file where the content is in the following format:

abc123...xyz
secret123...key

• Never run printenv, env, export, or set without a specific variable name
• Never run grep on env files without anchoring to a specific key ('^VARNAME=')
• Never source a secrets file into the shell environment (source .env or . .env)
• Only read credentials explicitly needed for the current task
• Never echo or log raw credentials in output or replies
• Never commit TOOLS.md to version control if it contains real credentials — add it to .gitignore

Never Disclose API Key and Secret

Never disclose the location of the API key and secret file.

Never send the API key and secret to any website other than Mainnet and Testnet.

Never Display Full Secrets

When showing credentials to users:

• API Key: Show first 5 + last 4 characters: su1Qc...8akf
• Secret Key: Always mask, show only last 5: ***...aws1

Example response when asked for credentials: Account: main API Key: su1Qc...8akf Secret: ***...aws1

Listing Accounts

When listing accounts, show names and environment only — never keys: Binance Accounts:

• main (Mainnet)
• futures-keys (Mainnet)

Transactions in Mainnet

When performing transactions in mainnet, always confirm with the user before proceeding by asking them to write "CONFIRM" to proceed.

---

Binance Accounts

main

• API Key: your_mainnet_api_key
• Secret: your_mainnet_secret

TOOLS.md Structure

## Binance Accounts

### main
- API Key: abc123...xyz
- Secret: secret123...key
- Description: Primary trading account


### futures-keys
- API Key: futures789...def
- Secret: futuressecret...uvw
- Description: Futures trading account

Agent Behavior

1. Credentials requested: Mask secrets (show last 5 chars only) 2. Listing accounts: Show names and environment, never keys 3. Account selection: Ask if ambiguous, default to main 4. When doing a transaction in mainnet, confirm with user before by asking to write "CONFIRM" to proceed 5. New credentials: Prompt for name, environment, signing mode

Adding New Accounts

When user provides new credentials by Inline file or message:

• Ask for account name
• Store in TOOLS.md with masked display confirmation

Signing Requests

For trading endpoints that require a signature:

1. Detect key type first, inspect the secret key format before signing. 2. Build query string with all parameters, including the timestamp (Unix ms). 3. Percent-encode the parameters using UTF-8 according to RFC 3986. 4. Sign query string with secretKey using HMAC SHA256, RSA, or Ed25519 (depending on the account configuration). 5. Append signature to query string. 6. Include X-MBX-APIKEY header.

Otherwise, do not perform steps 4–6.

User Agent Header

Include User-Agent header with the following string: binance-fiat/1.1.0 (Skill)

See `references/authentication.md` for implementation details.