Binance P2P Trading Skill

When to Use / When NOT to Use

Use this skill when the user wants to:

• Check P2P buy/sell quotes for a crypto/fiat pair (e.g., USDT/CNY).
• Search P2P advertisements and filter by payment method(s), limits, merchant quality.
• Compare prices across payment methods (e.g., Alipay vs bank transfer).
• View their own P2P order history / summary (requires API key).

Do NOT use this skill when the user asks about:

• Spot/Convert prices, futures/derivatives, margin, trading bots.
• Deposits/withdrawals, wallet transfers, on-chain transactions.
• Creating/cancelling orders, appeals, releasing coins (trading operations).

Ask clarifying questions (do not guess) if any key inputs are missing:

• fiat

  (e.g., CNY)

• asset

  (e.g., USDT)
• user intent: buy crypto or sell crypto
• preferred payment method(s)
• target amount (optional but recommended for ad filtering)

Core Concepts

tradeType

mapping (avoid ambiguity)

• User wants to buy crypto (pay fiat, receive USDT/BTC) →

  tradeType=BUY

• User wants to sell crypto (receive fiat, pay USDT/BTC) →

  tradeType=SELL

Capabilities

Phase 1 — Public Market (No Auth)

• Quote P2P prices
• Search ads
• Compare payment methods
• Filter/Rank ads by limits and merchant indicators

Phase 2 — Personal Orders (Requires API Key)

• List P2P order history
• Filter by trade type / time range
• Provide summary statistics

Security & Privacy Rules

Credentials

• Required env vars:

  • BINANCE_API_KEY

    (sent as header)

  • BINANCE_SECRET_KEY

    (used for signing)

Never display full secrets

• API Key: show first 5 + last 4 characters:

  abc12...z789

• Secret Key: always mask; show only last 5:

  ***...c123

Permission minimization

• Binance API permissions: Enable Reading only.
• Do NOT request/encourage trading, withdrawal, or modification permissions.

Storage guidance

• Prefer environment injection (session/runtime env vars) over writing to disk.
• Only write to

  .env

  if the user explicitly agrees.
• Ensure

  .env

  is in

  .gitignore

  before saving.

⚠️ CRITICAL: SAPI Signing (Different from Standard Binance API)

Parameter ordering

• DO NOT sort parameters for SAPI requests.
• Keep original insertion order when building the query string.

# ✅ Correct for SAPI: keep insertion order
params = {"page": 1, "rows": 20, "timestamp": 1710460800000}
query_string = urlencode(params)  # NO sorting

# ❌ Wrong (standard Binance API only): sorted
query_string = urlencode(sorted(params.items()))

Signing details

references/authentication.md

• RFC 3986 percent-encoding
• HMAC SHA256 signing process
• Required headers (incl. User-Agent)
• SAPI-specific parameter ordering

API Overview

Public Queries (MGS C2C Agent API — No Auth)

https://www.binance.com

/bapi/c2c/v1/public/c2c/agent/quote-price

/bapi/c2c/v1/public/c2c/agent/ad-list

/bapi/c2c/v1/public/c2c/agent/trade-methods

• tradeType

  :

  BUY

  or

  SELL

  (treat as case-insensitive)

• limit

  : 1–20 (default 10)

• tradeMethodIdentifiers

  : pass as a plain string (not JSON array) — e.g.

  tradeMethodIdentifiers=BANK

  or

  tradeMethodIdentifiers=WECHAT

  . Values must use the

  identifier

  field returned by the

  trade-methods

  endpoint (see workflow below). ⚠️ Do NOT use JSON array syntax like

  ["BANK"]

  — it will return empty results.

Workflow: Compare Prices by Payment Method

trade-methods

GET /bapi/c2c/v1/public/c2c/agent/trade-methods?fiat=CNY
→ [{"identifier":"ALIPAY",...}, {"identifier":"WECHAT",...}, {"identifier":"BANK",...}]

ad-list

tradeMethodIdentifiers

GET /bapi/c2c/v1/public/c2c/agent/ad-list?fiat=CNY&asset=USDT&tradeType=BUY&limit=5&tradeMethodIdentifiers=ALIPAY&tradeMethodIdentifiers=WECHAT

Important: Do not hardcode identifier values like

"Alipay"

or

"BANK"

. Always call

trade-methods

first to get the exact

identifier

strings for the given fiat currency.

Personal Orders (Binance SAPI — Requires Auth)

https://api.binance.com

/sapi/v1/c2c/orderMatch/listUserOrderHistory

/sapi/v1/c2c/orderMatch/getUserOrderSummary

• Header:

  X-MBX-APIKEY

• Query:

  timestamp

  +

  signature

• Header:

  User-Agent: binance-wallet/1.0.0 (Skill)

Output Format Guidelines

Price quote

• Show both sides when available (best buy / best sell).
• Use fiat symbol and 2-decimal formatting.

USDT/CNY (P2P)
- Buy USDT (you buy crypto): ¥7.20
- Sell USDT (you sell crypto): ¥7.18

Ad list

1. adNo (ad number / identifier)
2. price (fiat)
3. merchant name
4. completion rate
5. limits
6. payment methods (identifiers)

• This skill does NOT support automated order placement.
• When user wants to place an order, provide a direct link to the filtered ad list page:

  https://p2p.binance.com/trade/{tradeType}/{asset}?fiat={fiat}&payment={paymentMethod}

  • {tradeType}

    :

    buy

    or

    sell

    (lowercase)

  • {asset}

    : e.g.,

    USDT

    ,

    BTC

  • {fiat}

    : e.g.,

    CNY

    ,

    USD

  • {paymentMethod}

    : e.g.,

    WECHAT

    ,

    ALIPAY

    ,

    BANK

  Example:

  https://p2p.binance.com/trade/buy/USDT?fiat=CNY&payment=WECHAT

• This opens the pre-filtered ad list page where user can select a merchant and place order directly.

Personal orders

• Time format:

  YYYY-MM-DD HH:mm (UTC+0)

  — always display in UTC timezone
• Include: type, asset/fiat, amount, total, status
• Provide a brief summary line (count + totals) when filtering

createTime

listUserOrderHistory

• The

  createTime

  field returns a Unix timestamp in milliseconds (13 digits).
• Convert to human-readable format in UTC+0 timezone:

  # Python example
  from datetime import datetime, timezone
  readable_time = datetime.fromtimestamp(createTime / 1000, tz=timezone.utc).strftime('%Y-%m-%d %H:%M (UTC+0)')
  
  # JavaScript example
  const readableTime = new Date(createTime).toISOString().replace('T', ' ').slice(0, 16) + ' (UTC+0)';
  // Or more explicitly:
  const date = new Date(createTime);
  const readableTime = date.getUTCFullYear() + '-' +
    String(date.getUTCMonth() + 1).padStart(2, '0') + '-' +
    String(date.getUTCDate()).padStart(2, '0') + ' ' +
    String(date.getUTCHours()).padStart(2, '0') + ':' +
    String(date.getUTCMinutes()).padStart(2, '0') + ' (UTC+0)';

• Always display the converted time to users with timezone info, not the raw timestamp.

Error Handling (User-Facing)

• Invalid API key (-2015): prompt to verify

  .env

  / API Management.
• Signature failed (-1022): warn about wrong secret, sorted params, or stale timestamp.
• Timestamp invalid (-1021): advise time sync / regenerate timestamp.
• Rate limit: ask to retry later.

Limitations (By Design)

• Place/cancel orders
• Mark as paid / release coins
• Submit appeals
• Post/modify advertisements
• Expose sensitive order-detail endpoints beyond what’s needed for history/summary

Developer Notes

Version Check (First Invocation per Conversation)

• GET /bapi/c2c/v1/public/c2c/agent/check-version?version=1.0.0

  (Base:

  https://www.binance.com

  )

• If

  needUpdate=true

  : show:

  P2P Skill 有新版本可用（当前: {clientVersion}, 最新: {latestVersion}），建议更新。

• Else / on failure: proceed silently.

Client-side operations

• Asset filtering: if API doesn’t support it, fetch then filter locally.
• Aggregations: compute totals client-side when summary endpoint is insufficient.