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:

undefined

请勿对SAPI请求的参数进行排序。
构建查询字符串时需保持参数原始插入顺序。

示例：

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

Endpoint	Method	Params	Usage
`/bapi/c2c/v1/public/c2c/agent/quote-price`	GET	fiat, asset, tradeType	Quick price quote
`/bapi/c2c/v1/public/c2c/agent/ad-list`	GET	fiat, asset, tradeType, limit, order, tradeMethodIdentifiers	Search ads
`/bapi/c2c/v1/public/c2c/agent/trade-methods`	GET	fiat	Payment 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`	GET	fiat, asset, tradeType	快速查询价格
`/bapi/c2c/v1/public/c2c/agent/ad-list`	GET	fiat, asset, tradeType, limit, order, tradeMethodIdentifiers	搜索广告
`/bapi/c2c/v1/public/c2c/agent/trade-methods`	GET	fiat	获取支付方式

参数说明：

```
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

Endpoint	Method	Auth	Usage
`/sapi/v1/c2c/orderMatch/listUserOrderHistory`	GET	Yes	Order history
`/sapi/v1/c2c/orderMatch/getUserOrderSummary`	GET	Yes	User 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:

adNo (ad number / identifier)
price (fiat)
merchant name
completion rate
limits
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个符合条件的广告，使用稳定的结构：

adNo（广告编号/标识符）
price（法币计价）
商家名称
完成率
交易限额
支付方式（标识符）

除非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:

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

p2p

Original

Translation

Binance P2P Trading Skill

Binance P2P交易技能

When to Use / When NOT to Use

使用场景与禁用场景

Use this skill when the user wants to:

以下场景可使用本技能：

Do NOT use this skill when the user asks about:

以下场景请勿使用本技能：

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

若关键信息缺失，请询问用户明确信息（请勿猜测）：

Core Concepts

核心概念

tradeType mapping (avoid ambiguity)

tradeType映射（避免歧义）

Capabilities

功能范围

Phase 1 — Public Market (No Auth)

第一阶段 — 公开市场（无需鉴权）

Phase 2 — Personal Orders (Requires API Key)

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

Security & Privacy Rules

安全与隐私规则

Credentials

凭证要求

Never display full secrets

绝不显示完整密钥

Permission minimization

最小权限原则

Storage guidance

存储建议

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

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

Parameter ordering

参数顺序

✅ Correct for SAPI: keep insertion order

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

❌ Wrong (standard Binance API only): sorted

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

Signing details

签名细节

API Overview

API概览

Public Queries (MGS C2C Agent API — No Auth)

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

Workflow: Compare Prices by Payment Method

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

Personal Orders (Binance SAPI — Requires Auth)

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

Output Format Guidelines

输出格式规范

Price quote

价格查询

Ad list

广告列表

Personal orders

个人订单

Error Handling (User-Facing)

错误处理（面向用户）

Limitations (By Design)

设计限制

Developer Notes

开发者说明

Version Check (First Invocation per Conversation)

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

Client-side operations

客户端操作

`tradeType`
mapping (avoid ambiguity)

`tradeType`
映射（避免歧义）