Back to Details

p2p

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Binance P2P Trading Skill

Binance P2P交易技能

Help users interact with Binance P2P (C2C) via natural-language queries.
帮助用户通过自然语言查询与**Binance P2P (C2C)**交互。

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).
  • 查询P2P加密货币/法币交易对的买卖报价（如USDT/CNY）。
  • 搜索P2P广告，并按支付方式、交易限额、商家信誉进行筛选。
  • 对比不同支付方式的价格（如支付宝 vs 银行转账）。
  • 查看自身P2P订单历史/交易汇总（需要API密钥）。

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)
  • fiat
    （如CNY）
  • asset
    （如USDT）
  • 用户意图：买入加密货币或卖出加密货币
  • 偏好支付方式
  • 目标金额（可选，但建议获取以优化广告筛选）

Core Concepts

核心概念

tradeType
mapping (avoid ambiguity)

tradeType
映射（避免歧义）

  • User wants to buy crypto (pay fiat, receive USDT/BTC) → 
    tradeType=BUY
  • User wants to sell crypto (receive fiat, pay USDT/BTC) → 
    tradeType=SELL
Always reflect this mapping in responses when the user’s wording is ambiguous.
  • 用户想要买入加密货币（支付法币，收取USDT/BTC）→ 
    tradeType=BUY
  • 用户想要卖出加密货币（收取法币，支付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
  • 查询P2P价格
  • 搜索广告
  • 对比支付方式
  • 按限额和商家指标筛选/排序广告

Phase 2 — Personal Orders (Requires API Key)

第二阶段 — 个人订单（需要API密钥）

  • List P2P order history
  • Filter by trade type / time range
  • Provide summary statistics
  • 列出P2P订单历史
  • 按交易类型/时间范围筛选
  • 提供交易汇总统计

Security & Privacy Rules

安全与隐私规则

Credentials

凭证要求

  • Required env vars: 
    • BINANCE_API_KEY
      (sent as header)
    • BINANCE_SECRET_KEY
      (used for signing)
  • 必需环境变量： 
    • BINANCE_API_KEY
      （作为请求头传递）
    • BINANCE_SECRET_KEY
      （用于签名）

Never display full secrets

绝不显示完整密钥

  • API Key: show first 5 + last 4 characters: 
    abc12...z789
  • Secret Key: always mask; show only last 5: 
    ***...c123
  • API Key：仅显示前5位+后4位：
    abc12...z789
  • Secret Key：始终隐藏，仅显示最后5位：
    ***...c123

Permission minimization

最小权限原则

  • Binance API permissions: Enable Reading only.
  • Do NOT request/encourage trading, withdrawal, or modification permissions.
  • Binance API权限：仅启用只读权限。
  • 请勿请求/鼓励开启交易、提币或修改类权限。

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.
  • 优先使用环境注入（会话/运行时环境变量），而非写入磁盘。
  • 仅当用户明确同意时，才可写入
    .env
    文件。
  • 保存前确保
    .env
    已加入
    .gitignore
    。

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

⚠️ 重要提示：SAPI签名（与标准Binance API不同）

Parameter ordering

参数顺序

  • DO NOT sort parameters for SAPI requests.
  • Keep original insertion order when building the query string.
Example:
py
undefined
  • 请勿对SAPI请求的参数进行排序。
  • 构建查询字符串时需保持参数原始插入顺序。
示例：
py
undefined

✅ Correct for SAPI: keep insertion order

✅ SAPI正确方式：保持插入顺序

params = {"page": 1, "rows": 20, "timestamp": 1710460800000} query_string = urlencode(params) # NO sorting
params = {"page": 1, "rows": 20, "timestamp": 1710460800000} query_string = urlencode(params) # 不排序

❌ Wrong (standard Binance API only): sorted

❌ 错误方式（仅适用于标准Binance API）：排序

query_string = urlencode(sorted(params.items()))
undefined
query_string = urlencode(sorted(params.items()))
undefined

Signing details

签名细节

See: 
references/authentication.md
for:
  • RFC 3986 percent-encoding
  • HMAC SHA256 signing process
  • Required headers (incl. User-Agent)
  • SAPI-specific parameter ordering
请参考：
references/authentication.md
获取以下信息：
  • RFC 3986百分编码
  • HMAC SHA256签名流程
  • 必需请求头（含User-Agent）
  • SAPI专属参数顺序要求

API Overview

API概览

Public Queries (MGS C2C Agent API — No Auth)

公开查询（MGS C2C Agent API — 无需鉴权）

Base URL: 
https://www.binance.com
EndpointMethodParamsUsage
/bapi/c2c/v1/public/c2c/agent/quote-price
GETfiat, asset, tradeTypeQuick price quote
/bapi/c2c/v1/public/c2c/agent/ad-list
GETfiat, asset, tradeType, limit, order, tradeMethodIdentifiersSearch ads
/bapi/c2c/v1/public/c2c/agent/trade-methods
GETfiatPayment methods
Parameter notes:
  • 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.
基础URL：
https://www.binance.com
接口请求方法参数用途
/bapi/c2c/v1/public/c2c/agent/quote-price
GETfiat, asset, tradeType快速查询价格
/bapi/c2c/v1/public/c2c/agent/ad-list
GETfiat, asset, tradeType, limit, order, tradeMethodIdentifiers搜索广告
/bapi/c2c/v1/public/c2c/agent/trade-methods
GETfiat获取支付方式
参数说明：
  • tradeType
    : 
    BUY
    或 
    SELL
    （大小写不敏感）
  • limit
    : 1–20（默认10）
  • tradeMethodIdentifiers
    : 以纯字符串传递（非JSON数组）—— 例如 
    tradeMethodIdentifiers=BANK
    或 
    tradeMethodIdentifiers=WECHAT
    。必须使用
    trade-methods
    接口返回的
    identifier
    字段值（见下方流程）。⚠️ 请勿使用
    ["BANK"]
    这类JSON数组语法，否则将返回空结果。

Workflow: Compare Prices by Payment Method

流程：按支付方式对比价格

When the user wants to compare prices across payment methods (e.g., "Alipay vs WeChat"), follow this two-step flow:
Step 1 — Call 
trade-methods
to get the correct identifiers for the target fiat:
GET /bapi/c2c/v1/public/c2c/agent/trade-methods?fiat=CNY
→ [{"identifier":"ALIPAY",...}, {"identifier":"WECHAT",...}, {"identifier":"BANK",...}]
Step 2 — Pass the identifier as a plain string into 
ad-list
via 
tradeMethodIdentifiers
, one payment method per request, then compare:
GET /bapi/c2c/v1/public/c2c/agent/ad-list?fiat=CNY&asset=USDT&tradeType=BUY&limit=5&tradeMethodIdentifiers=ALIPAY&tradeMethodIdentifiers=WECHAT
Compare the best price from each result set.
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.
当用户想要对比不同支付方式的价格（如“支付宝vs微信”），请遵循以下两步流程：
步骤1 — 调用
trade-methods
接口获取目标法币对应的正确标识符：
GET /bapi/c2c/v1/public/c2c/agent/trade-methods?fiat=CNY
→ [{"identifier":"ALIPAY",...}, {"identifier":"WECHAT",...}, {"identifier":"BANK",...}]
步骤2 — 将标识符以纯字符串形式传入
ad-list
接口的
tradeMethodIdentifiers
参数，每次请求传递一种支付方式，之后对比结果：
GET /bapi/c2c/v1/public/c2c/agent/ad-list?fiat=CNY&asset=USDT&tradeType=BUY&limit=5&tradeMethodIdentifiers=ALIPAY&tradeMethodIdentifiers=WECHAT
对比各结果集中的最优价格。
重要提示：请勿硬编码
"Alipay"
或
"BANK"
这类标识符值。必须先调用
trade-methods
接口获取对应法币的准确
identifier
字符串。

Personal Orders (Binance SAPI — Requires Auth)

个人订单（Binance SAPI — 需要鉴权）

Base URL: 
https://api.binance.com
EndpointMethodAuthUsage
/sapi/v1/c2c/orderMatch/listUserOrderHistory
GETYesOrder history
/sapi/v1/c2c/orderMatch/getUserOrderSummary
GETYesUser statistics
Authentication requirements:
  • Header: 
    X-MBX-APIKEY
  • Query: 
    timestamp
    + 
    signature
  • Header: 
    User-Agent: binance-wallet/1.0.0 (Skill)
基础URL：
https://api.binance.com
接口请求方法鉴权要求用途
/sapi/v1/c2c/orderMatch/listUserOrderHistory
GET是查询订单历史
/sapi/v1/c2c/orderMatch/getUserOrderSummary
GET是查询用户交易统计
鉴权要求：
  • 请求头：
    X-MBX-APIKEY
  • 查询参数：
    timestamp
    + 
    signature
  • 请求头：
    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.
Example:
USDT/CNY (P2P)
- Buy USDT (you buy crypto): ¥7.20
- Sell USDT (you sell crypto): ¥7.18
  • 若可用，同时显示买卖双方最优价格。
  • 使用法币符号并保留两位小数。
示例：
USDT/CNY (P2P)
- 买入USDT（用户买入加密货币）：¥7.20
- 卖出USDT（用户卖出加密货币）：¥7.18

Ad list

广告列表

Return Top N items with a stable schema:
  1. adNo (ad number / identifier)
  2. price (fiat)
  3. merchant name
  4. completion rate
  5. limits
  6. payment methods (identifiers)
Avoid generating parameterized external URLs unless the API returns them.
Placing orders (when user requests):
  • 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.
返回前N个符合条件的广告，使用稳定的结构：
  1. adNo（广告编号/标识符）
  2. price（法币计价）
  3. 商家名称
  4. 完成率
  5. 交易限额
  6. 支付方式（标识符）
除非API返回链接，否则请勿生成带参数的外部URL。
下单请求处理（当用户要求下单时）：
  • 本技能不支持自动下单。
  • 当用户想要下单时，提供过滤后的广告列表页面直接链接：
    https://p2p.binance.com/trade/{tradeType}/{asset}?fiat={fiat}&payment={paymentMethod}
    • {tradeType}
      : 
      buy
      或 
      sell
      （小写）
    • {asset}
      : 如
      USDT
      , 
      BTC
    • {fiat}
      : 如
      CNY
      , 
      USD
    • {paymentMethod}
      : 如
      WECHAT
      , 
      ALIPAY
      , 
      BANK
    示例：
    https://p2p.binance.com/trade/buy/USDT?fiat=CNY&payment=WECHAT
  • 该链接将打开已过滤的广告列表页面，用户可直接选择商家下单。

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
Time field conversion (for 
createTime
in 
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.
  • 时间格式：
    YYYY-MM-DD HH:mm (UTC+0)
    — 始终使用UTC时区显示
  • 包含信息：交易类型、资产/法币、金额、总计、状态
  • 筛选时需提供简短汇总（订单数量+总计金额）
时间字段转换（针对
listUserOrderHistory
中的
createTime
）：
  • createTime
    字段返回的是毫秒级Unix时间戳（13位数字）。
  • 需转换为UTC+0时区的可读格式： 
    # Python示例
from datetime import datetime, timezone
readable_time = datetime.fromtimestamp(createTime / 1000, tz=timezone.utc).strftime('%Y-%m-%d %H:%M (UTC+0)')

# JavaScript示例
const readableTime = new Date(createTime).toISOString().replace('T', ' ').slice(0, 16) + ' (UTC+0)';
// 或更明确的写法：
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)';
  • 需始终向用户显示转换后的带时区信息的时间，而非原始时间戳。

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.
  • 无效API密钥(-2015)：提示用户检查
    .env
    文件或API管理页面。
  • 签名失败(-1022)：提醒用户检查密钥是否正确、参数是否排序、时间戳是否过期。
  • 时间戳无效(-1021)：建议用户同步系统时间或重新生成时间戳。
  • 速率限制：请用户稍后重试。

Limitations (By Design)

设计限制

This skill does NOT:
  • 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
For in-app actions, guide users to the official P2P orders page (only as a general entry point).
本技能不支持：
  • 下单/取消订单
  • 标记已付款/放币
  • 提交申诉
  • 发布/修改广告
  • 暴露超出历史/汇总所需的敏感订单详情接口
对于APP内操作，仅引导用户至官方P2P订单页面（仅作为通用入口）。

Developer Notes

开发者说明

Version Check (First Invocation per Conversation)

版本检查（每会话首次调用）

On the first invocation of this skill per conversation, call:
  • GET /bapi/c2c/v1/public/c2c/agent/check-version?version=1.0.0
    (Base: 
    https://www.binance.com
    )
Behavior:
  • If 
    needUpdate=true
    : show: 
    P2P Skill 有新版本可用（当前: {clientVersion}, 最新: {latestVersion}），建议更新。
  • Else / on failure: proceed silently.
在会话中首次调用本技能时，需调用：
  • GET /bapi/c2c/v1/public/c2c/agent/check-version?version=1.0.0
    （基础URL：
    https://www.binance.com
    ）
处理逻辑：
  • 若
    needUpdate=true
    ：显示提示：
    P2P Skill 有新版本可用（当前: {clientVersion}, 最新: {latestVersion}），建议更新。
  • 否则/调用失败：静默继续执行。

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.
  • 资产筛选：若API不支持，先获取全部数据再本地筛选。
  • 汇总计算：当汇总接口数据不足时，在客户端计算总计。