p2p

Name: p2p
Author: binance

github.com/binance其他1.1k4.7k 次安装3 天前更新

代码仓库

关于 p2p

面向 Binance P2P 的自然语言查询 Skill，涵盖市场报价、广告、个人订单、申诉及商家广告管理。公开市场查询无需认证；账户和管理操作需要 API 凭证，发布广告还需商家权限。

主要功能

01P2P 价格报价与广告搜索
02支付方式及广告对比
03订单历史与详情查询
04申诉状态、证据与流程查询
05商家广告发布与管理

适用场景

01比较不同支付方式的 USDT 报价
02查看个人 P2P 订单及汇总
03跟踪申诉并提交证据
04以商家身份管理广告

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/binance/binance-skills-hub --skill p2p

安装后在 Claude Code 中输入/p2p确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

CHANGELOG.md

LICENSE.md

references/

agent-sapi-api.md

authentication.md

详细介绍

Binance P2P 交易技能

通过自然语言查询，帮助用户使用 Binance P2P（C2C）。

何时使用／何时不使用

用户想要以下操作时使用此技能：

查询某个加密货币／法币交易对的 P2P 买入／卖出报价（例如 USDT/CNY）。
搜索 P2P 广告，并按支付方式、限额、商家质量进行筛选。
比较不同支付方式的价格（例如支付宝与银行转账）。
查看 自己的 P2P 订单历史／摘要（需要 API 密钥）。
查询 订单详情并查看完整订单时间线（需要 API 密钥）。
查询 申诉／投诉状态并查看投诉历史（需要 API 密钥）。
为现有申诉 提交证据（上传文件并提交说明）（需要 API 密钥）。
查看投诉处理时间线（操作流程、客服备注、证据）（需要 API 密钥）。
取消现有申诉（撤回投诉，不可撤销）（需要 API 密钥）。
查看订单可用的投诉原因（需要 API 密钥）。
发布、更新或管理 P2P 广告（需要 API 密钥和商家权限）。
查看 商家资料及其广告列表（需要 API 密钥）。
查询 支持的数字货币和法币（需要 API 密钥）。

用户询问以下内容时，请勿使用此技能：

现货／闪兑价格、期货／衍生品、保证金、交易机器人。
充值／提现、钱包转账、链上交易。
创建／取消订单、放币（交易操作）。支持取消申诉（投诉）。
发起新申诉（提交投诉暂不支持；支持为现有申诉补充证据）。
在订单对话中发送聊天消息。

缺少关键输入时，请先询问澄清问题（不要猜测）：

fiat（例如 CNY）
asset（例如 USDT）
用户意图：买入加密货币还是卖出加密货币
首选支付方式
目标金额（可选，但建议提供以筛选广告）

核心概念

`tradeType` 映射（避免歧义）

用户想要买入加密货币（支付法币，收到 USDT/BTC）→ tradeType=BUY
用户想要卖出加密货币（收到法币，支付 USDT/BTC）→ tradeType=SELL

如果用户的措辞存在歧义，回复时务必说明此映射关系。

功能

阶段 1 — 公共市场（无需身份验证）

查询 P2P 价格
搜索广告
比较支付方式
按限额和商家指标筛选／排序广告

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

列出 P2P 订单历史
按交易类型／时间范围筛选
提供汇总统计

阶段 3 — 订单与申诉 + 广告发布与管理（需要 API 密钥）

按订单编号查询订单详情
按状态、交易类型、资产、日期范围等条件列出订单
查看订单时间线（创建 → 付款 → 放币 → 完成）
检测申诉状态并显示申诉详情
按条件查询投诉／申诉记录
获取定价决策所需的市场参考价格
上传申诉证据文件（S3 预签名 URL + 提交）
查看投诉处理时间线／流程详情
取消现有申诉／撤回投诉
获取订单可用的投诉原因
搜索并分析市场广告分布
获取当前用户可用的广告类别
获取用户已配置的支付方式
列出所有系统交易方式
发布新广告（需确认）
更新现有广告参数（需确认）
更新广告状态：在线／离线／关闭（需确认）
查看商家资料及广告列表
列出所有支持的数字货币
列出所有支持的法币

环境配置

基础 URL（生产环境）

逻辑名称	URL
`SAPI_BASE`	`https://api.binance.com`
`MGS_BASE`	`https://www.binance.com`
`C2C_WEB`	`https://c2c.binance.com`

实现提示（用于代码生成）

当该技能生成 curl / Python / JS 代码时，使用以下固定基础 URL：

import os

SAPI_BASE = "https://api.binance.com"
MGS_BASE  = "https://www.binance.com"
C2C_WEB   = "https://c2c.binance.com"

def common_headers(api_key: str) -> dict:
    return {
        "X-MBX-APIKEY": api_key,
        "User-Agent": "binance-wallet/1.0.0 (Skill)",
    }

# Usage:
# f"{SAPI_BASE}/sapi/v1/c2c/agent/orderMatch/getUserOrderDetail"
# f"{MGS_BASE}/bapi/c2c/v1/public/c2c/agent/quote-price"
# f"{C2C_WEB}/en/adv?code={advNo}"
# headers = common_headers(os.getenv("BINANCE_API_KEY"))

# Bash equivalent:
SAPI_BASE="https://api.binance.com"
MGS_BASE="https://www.binance.com"
C2C_WEB="https://c2c.binance.com"

注意： SAPI 签名使用 HMAC SHA256，无需对参数排序。

安全与隐私规则

凭据

必需的环境变量：
- BINANCE_API_KEY（作为请求头发送）
- BINANCE_SECRET_KEY（用于签名）

绝不显示完整密钥

API Key：显示前 5 位 + 后 4 位字符：abc12...z789
Secret Key：始终掩码；仅显示最后 5 位：***...c123

权限最小化

Binance API 权限：仅启用读取（阶段 1/2）。
阶段 3 的广告管理还需要写入权限。
除所需权限外，切勿请求或鼓励授予提现或修改权限。

存储建议

优先使用环境注入（会话/运行时环境变量），而不是写入磁盘。
仅在用户明确同意后，才写入 .env。
保存前确保 .env 已添加到 .gitignore。

⚠️ 关键：SAPI 签名（不同于标准 Binance API）

参数顺序

SAPI 请求不要对参数排序。
构建查询字符串时保留原始插入顺序。

示例：

# ✅ 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()))

签名详情

参见：references/authentication.md，了解：

RFC 3986 百分号编码
HMAC SHA256 签名流程
必需的请求头（包括 User-Agent）
SAPI 特有的参数顺序

API 概览

公开查询（MGS C2C Agent API——无需身份验证）

基础 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 数组语法，否则会返回空结果。

工作流：按支付方式比较价格

当用户想比较不同支付方式的价格时（例如“支付宝与微信”），请按以下两步流程操作：

步骤 1——调用 trade-methods，获取目标法币对应的正确标识符：

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

步骤 2——将标识符作为纯字符串，通过 tradeMethodIdentifiers 传入 ad-list，每次请求使用一种支付方式，然后进行比较：

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 字符串。

个人订单（Binance SAPI——需要身份验证）

基础 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)

输出格式指南

价格报价

在有数据时显示买卖双方的价格（最佳买价 / 最佳卖价）。
使用法币符号，并保留 2 位小数。

示例：

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

广告列表

返回 前 N 项，并采用稳定的架构：

adNo（广告编号／标识符）
price（法币）
商家名称
完成率
限额
付款方式（标识符）

除非 API 返回了带参数的外部 URL，否则避免生成此类 URL。

下单（用户提出请求时）：

此技能不支持自动下单。
用户想要下单时，使用 adNo 提供指向特定广告的直接链接：
```
https://c2c.binance.com/en/adv?code={adNo}
```
- {adNo}：广告列表结果中的广告编号／标识符
示例：https://c2c.binance.com/en/adv?code=123
该链接会打开特定广告的详情页，用户可直接通过选定的广告下单。

个人订单

时间格式：YYYY-MM-DD HH:mm (UTC+0)——始终以 UTC 时区显示
包含：类型、资产／法币、金额、总额、状态
筛选时提供简短的汇总行（数量 + 总额）

时间字段转换（针对 listUserOrderHistory 中的 createTime）：

createTime 字段返回 Unix 时间戳，单位为毫秒（13 位数字）。

转换为易读的 UTC+0 时区格式：

# 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)';

向用户显示转换后的时间时，始终注明时区，不要显示原始时间戳。

错误处理（面向用户）

API 密钥无效（-2015）：提示检查 .env／API Management。
签名失败（-1022）：提醒检查密钥错误、参数排序或时间戳过期。
时间戳无效（-1021）：建议同步时间／重新生成时间戳。
频率限制：请用户稍后重试。

限制（设计如此）

此技能不支持：

下单／取消订单
标记为已付款／释放币
发起新的申诉／提交投诉（仅支持为现有申诉补充证据）
发布／修改广告（仅限第 1／2 阶段——第 3 阶段将为商家添加广告管理功能）
访问超出历史记录／摘要所需范围的敏感订单详情端点

对于应用内操作，请引导用户前往官方 P2P 订单页面（仅作为通用入口）。

开发者说明

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

在每次对话中首次调用此技能时，调用：

GET /bapi/c2c/v1/public/c2c/agent/check-version?version=2.0.0（基础地址：https://www.binance.com）

行为：

如果 needUpdate=true：显示：New version of P2P Skill is available (current: {clientVersion}, latest: {latestVersion}), update recommended.
否则／失败时：静默继续。

客户端操作

资产筛选：如果 API 不支持，则获取数据后在本地筛选。
汇总：摘要端点无法满足需求时，在客户端计算总额。

第 3 阶段——订单与申诉 + 广告发布与管理

第 3 阶段将此技能从只读市场／订单查询扩展到写入操作（广告管理）和高级订单工作流（订单详情、申诉／投诉跟踪）。

第 3 阶段设计约束

约束	详情
身份验证	所有第 3 阶段功能都需要 API Key + Secret Key
写入操作确认	执行任何写入操作（发布广告、更新广告、更改状态）前，必须展示操作摘要并获得用户明确确认
API Key 权限	第 1 阶段只需启用“Enable Reading”；第 3 阶段还需要广告管理的写入权限
隐私屏蔽	切勿显示交易对手的敏感信息（银行卡、支付宝账户、电话、电子邮件、真实姓名）或内部 ID（`payId`）。即使 API 返回了这些字段，也要从面向用户的输出中滤除。对于付款方式，仅显示 `tradeMethodName`（例如“支付宝”）

场景 1：订单查询与申诉处理

1.1 查询订单详情

触发示例：

“查看订单 20260315123456 的详情”
“我最近那笔 USDT 买入订单怎么样了？”
“帮我查一下这个订单号”
“显示订单 20260315123456 的详情”

行为：

如果用户提供了订单号 → 调用 getUserOrderDetail
如果用户对订单的描述比较模糊 → 调用 listOrders 并设置筛选条件，然后让用户选择
根据订单状态分支处理：

状态分支处理：

状态	操作
已完成 (4)	显示完整时间线（创建 → 付款 → 确认 → 完成），结束
已取消 (6) / 已过期 (7)	显示取消原因（超时 / 手动 / 系统），结束
进行中 (1=未付款，2=已付款，3=放币中)	显示当前步骤和倒计时
申诉中 (5)	自动进入 1.2 — 显示申诉状态

输出格式（订单详情）：

📋 Order No: {orderNumber}
├─ Type: {tradeType} {asset}
├─ Amount: {amount} {asset} @ {price} {fiatUnit}
├─ Total: {fiatSymbol}{totalPrice}
├─ Status: {orderStatus description}
├─ Counterparty: {buyerNickname / sellerNickname}
├─ Created: {createTime in UTC+0}
│
├─ Timeline:
│  ├─ Created:     {createTime}
│  ├─ Paid:        {notifyPayTime or "—"}
│  ├─ Confirmed:   {confirmPayTime or "—"}
│  └─ Cancelled:   {cancelTime or "—"}
│
├─ Commission: maker {commissionRate}% = {commission} {asset}
│              taker {takerCommissionRate}% = {takerCommission} {asset}
└─ Complaint: {isComplaintAllowed ? "Allowed" : "Not Allowed"} | Status: {complaintStatus or "None"}

倒计时显示（适用于进行中的订单）：

如果 status=1（未付款）：显示“付款截止时间：{notifyPayEndTime}”及剩余时间
如果 status=2（已付款）：显示“放币截止时间：{confirmPayEndTime}”及剩余时间

1.2 查看申诉 / 投诉状态

触发条件：

订单状态 = 申诉中 (5) 时自动触发
“这个申诉进展到哪了？”
“订单 20260315123456 的申诉怎么样了？”
“申诉状态怎么样？”

行为：

使用订单号调用 query-complaints
以结构化格式显示投诉信息

输出格式：

⚠️ Appeal Status for Order {orderNo}
├─ Complaint No: {complaintNo}
├─ Status: {complaintStatus description}
├─ Role: {roleIdentity} (COMPLAINANT / RESPONDENT)
├─ Reason: {reason}
├─ Created: {complaintCreateTime}
├─ Order Asset: {orderAsset} | Fiat: {orderFiat}
├─ Order Amount: {orderAmount} ({fiatSymbol})
├─ Amount in USDT: {orderAmountInUsdt}
└─ Dispute Amount: {disputeAmount}

后续指引（根据 complaintStatus，在状态块后附加）：

complaintStatus	要显示的指引
0（被申诉人处理中）	“正在等待对方回复。有更新时会通知你。”
1（申诉人处理中）	“⚡ 需要采取行动 — 你需要提供证据或回复。说 “提交订单 {orderNo} 的证据”，即可立即上传证明。”
2（客服处理中）	“💡 在此阶段，双方仍可提交证据。你可以直接通过此技能提交证据 — 说 “提交订单 {orderNo} 的证据” 或 “提交证据”，即可上传付款凭证、截图或其他证明文件。”
3（已完成）	“此申诉已处理完毕。”
4（已取消）	“此申诉已取消。”

必须遵循： 当 complaintStatus 为 0、1 或 2（申诉仍在进行中）时，绝不要告诉用户“前往应用”或“前往争议中心”。始终引导他们使用此技能提交证据。此技能支持完整的证据上传流程（场景 1.5）。

投诉状态映射：

状态码	显示名称	描述
0	被申诉人处理中 (被申诉人处理中)	投诉已发起，正在等待对方回复
1	申诉人处理中 (申诉人处理中)	正在等待申诉人提供证据或采取行动
2	客服处理中 (客服处理中)	客服正在审核；双方均可提交证据
3	已完成 (已完成)	申诉已处理完毕
4	投诉已取消 (申诉取消)	申诉已撤回

重要： 不要将这些状态代码与 orderStatus 代码混淆——它们是不同的枚举。当 complaintStatus=2（客服处理中）时，如有需要，应引导用户提交证据；不要告诉他们“等待对方”。

1.3 查询投诉历史

触发条件：

“查看我的所有申诉记录”
“最近 3 个月有哪些申诉？”
“列出我作为申诉人的投诉”

行为：

使用可选筛选条件（roleIdentity、status、日期范围）调用 query-complaints
如果未指定日期，默认查询最近 90 天
显示分页结果

输出格式：

📋 Complaint Records (Total: {total})
┌───────────┬──────────────┬──────────┬────────┬───────────────┐
│ Order No  │ Complaint No │ Status   │ Role   │ Created       │
├───────────┼──────────────┼──────────┼────────┼───────────────┤
│ {orderNo} │ {no}         │ {status} │ {role} │ {time UTC+0}  │
└───────────┴──────────────┴──────────┴────────┴───────────────┘

1.4 订单列表与历史记录

触发条件：

“查看我的订单列表”
“最近的 USDT 买入订单”
“Show my completed orders this week”

行为：

对于进行中／最近的订单 → 使用 listOrders（筛选条件更丰富：advNo、status、payType）
对于历史订单 → 使用 listUserOrderHistory（支持 tradeType、日期范围）

输出格式（订单列表）：

📋 Orders (Page {page}, Total: {total})
┌──────────────┬──────┬───────┬──────────────┬────────┬───────────────┐
│ Order No     │ Type │ Asset │ Total        │ Status │ Created       │
├──────────────┼──────┼───────┼──────────────┼────────┼───────────────┤
│ {orderNo}    │ BUY  │ USDT  │ ¥{totalPrice}│ 已完成  │ {time UTC+0}  │
└──────────────┴──────┴───────┴──────────────┴────────┴───────────────┘

订单状态代码映射：

Code	Name	Chinese
0	Pending	处理中
1	Unpaid	未付款
2	Paid (Unconfirmed)	已付款
3	Releasing	放币处理中
4	Completed	已完成
5	In Appeal	申诉中
6	Cancelled	已取消
7	Expired (System Cancel)	超时取消

1.5 提交申诉证据

触发条件：

“帮我上传这个截图作为申诉证据”
“我要提交付款凭证”
“Submit evidence for order 228...”
“Upload proof of payment for my appeal”
当订单处于申诉中（status=5）且 complaintStatus=2（客服处理中）时自动建议

行为（3 步流程）：

步骤 1 — 获取预签名上传 URL：

GET /sapi/v1/c2c/agent/file-upload/get-s3-presigned-url?fileName=proof.jpg&scenario=complaint
→ { "uploadUrl": "https://s3...presigned...", "filePath": "/client_upload/c2c/complaint/..." }

步骤 2 — 将文件上传到 S3：

curl -X PUT -T /path/to/local/file.jpg "{uploadUrl}"

预签名 URL 的有效期为 5 分钟。必须在此时间内完成上传。

步骤 3 — 向 SAPI 提交证据：

POST /sapi/v1/c2c/agent/complaint/submit-evidence
Body: { "orderNo": "228...", "description": "付款截图", "fileUrls": ["/client_upload/c2c/complaint/..."] }
→ { "data": true }

支持的文件类型： txt, doc, xls, docx, xlsx, jpg, jpeg, png, pdf, mp3, mp4, avi, rm, rmvb, mov, wmv

输出格式（上传进度）：

📤 Evidence Upload for Order {orderNo}
├─ Step 1/3: Getting upload URL... ✅
├─ Step 2/3: Uploading file "{fileName}"... ✅
├─ Step 3/3: Submitting evidence...
│  ├─ Description: {description}
│  └─ Files: {n} file(s)
└─ Result: ✅ Evidence submitted successfully

💡 Tip: You can submit additional evidence by saying "再上传一个文件"

输出格式（失败）：

❌ Evidence Upload Failed
├─ Step: {which step failed}
├─ Error: {error message}
└─ Suggestion: {actionable fix}

常见错误：

Unsupported file type → 检查文件扩展名；请参阅上方支持的文件类型
Presigned URL expired → 重新请求上传 URL（步骤 1）
Order not in appeal → 只能为存在有效申诉的订单提交证据
File too large → 缩小文件，或将其拆分为多个文件

写操作确认规则： 提交证据遵循与场景 2 写操作相同的确认流程：

显示将要提交的内容摘要（文件名、描述、订单号）
等待用户确认后再执行步骤 3

确认格式：

📋 Evidence Submission Summary
├─ Order: {orderNo}
├─ Description: {description}
├─ Files to submit:
│  1. {fileName1} ({fileType}, uploaded ✅)
│  2. {fileName2} ({fileType}, uploaded ✅)
└─ ⚠️ Confirm submission? (reply "确认" or "confirm")

1.6 查看申诉处理时间线

触发条件：

“查看申诉的处理流程”
“这个申诉经历了哪些步骤？”
“Show complaint timeline for order 228...”
“What happened in the appeal process?”

行为：

使用 orderNo（以及可选的 complaintNo）调用 get-complaint-flows
按时间顺序显示所有处理步骤

输出格式：

📜 Complaint Timeline: Order {orderNo} (Complaint #{complaintNo})
│
├─ [{createTime}] {creatorNickName}
│  ├─ Type: {infoType description}
│  ├─ Description: {description}
│  ├─ Evidence: {fileUrls count} file(s) attached
│  └─ Source: {source}
│
├─ [{createTime}] {operatorName or creatorNickName}
│  ├─ Type: {infoType description}
│  ├─ Remark: {remark}
│  └─ Evidence: {fileUrls or "None"}
│
└─ ... (chronological order)

💡 Actions: "提交证据" to submit evidence | "刷新" to check for updates

信息类型映射（用于显示）：

infoType	Description
1	Complaint Initiated
2	Evidence Submitted
3	CS Review Note
4	Resolution / Decision

注意： 响应中的 fileUrls 是由 CDN 拼接的 URL，可直接访问。如有 remarkHtml，渲染时优先使用它，而非 remark。

1.7 取消投诉／申诉

触发条件：

“取消这个申诉”
“我不想继续申诉了”
“Cancel my appeal for order 228...”
“Withdraw my complaint”

⚠️ 这是一个破坏性操作 — 必须确认！

取消申诉后无法撤销。用户将放弃争议，订单将继续按正常流程处理。Agent MUST 遵循以下严格的确认流程：

行为：

用户表达取消意图时，首先明确显示警告
等待用户明确确认（“确认取消”／“confirm cancel”／“yes”）
之后才能使用 orderNo 调用 cancel-complaint
显示结果

警告格式（执行前必须显示）：

⚠️ Cancel Appeal Confirmation
├─ Order: {orderNo}
├─ Current complaint status: {status from previous query if available}
│
╔══════════════════════════════════════════════╗
║  WARNING: This action CANNOT be undone!      ║
║  - Your appeal will be permanently withdrawn ║
║  - You will lose the right to dispute this   ║
║    order through the appeal process          ║
║  - The order will proceed to normal          ║
║    resolution without CS intervention        ║
╚══════════════════════════════════════════════╝
│
└─ Reply "确认取消" or "confirm cancel" to proceed

成功时：

✅ Appeal Cancelled
├─ Order: {orderNo}
├─ Status: Appeal withdrawn
└─ The order will now proceed to normal resolution.

失败时：

❌ Cancel Failed
├─ Order: {orderNo}
├─ Reason: {error message}
└─ Possible causes: no active appeal, order already resolved, or insufficient permissions.

必须遵循的规则：

绝不可在未显示警告并获得明确确认的情况下取消
如果用户的表达含糊不清（例如在讨论其他事情时说“算了”／“never mind”），不要将其理解为取消意图——应要求用户澄清
如果投诉状态已解决／关闭，应告知用户，而不是尝试调用 API

1.8 获取申诉理由

触发条件：

“我可以用什么理由申诉？”
“我可以用什么理由申诉？”
“显示此订单可用的申诉理由”
“申诉理由有哪些？”

行为：

使用 orderNo 调用 get-complaint-reasons
显示可用理由代码及其说明

输出格式：

📋 Available Complaint Reasons for Order {orderNo}
│
├─ [{reasonCode}] {reasonDesc}
├─ [{reasonCode}] {reasonDesc}
├─ [{reasonCode}] {reasonDesc}
└─ ...

💡 Note: These are the reasons you can use when initiating an appeal.
   This skill does NOT support initiating appeals — only viewing reasons.

**注意：**这是只读信息查询。此技能不支持实际提交新申诉（需由用户使用 App 提交）。

场景 2：广告发布与管理

⚠️ 写操作安全规则

场景 2 中的所有写操作都必须遵循以下流程：

**预先检查：**确认用户具有商户权限（API 本身会进行检查，但遇到 403/Permission denied 时，需向用户明确说明）
**显示摘要：**执行任何写入 API 之前，显示完整的操作摘要
**明确确认：**等待用户回复“确认”/“confirm”/“发布”/“yes”后再继续
**绝不自动执行：**即使用户在初始请求中说“直接执行”，也必须先显示摘要

2.1 市场分析与参考价格

触发条件：

“我想发一个 USDT/CNY 的卖单广告”
“帮我挂一个 BTC 买单”
“当前市场参考价是多少？”
“USDT/CNY 的参考价格是多少？”

行为：

调用 getReferencePrice 获取市场参考价格
调用 search 分析当前市场广告分布
提供定价参考信息，帮助用户做决定

输出格式（参考价格）：

📊 Market Reference Price
├─ Asset: {asset} / {fiatCurrency}
├─ Reference Price: {currencySymbol}{referencePrice}
├─ Price Scale: {priceScale} decimals
└─ Asset Scale: {assetScale} decimals

输出格式（市场分析）：

📊 Market Ad Analysis: {asset}/{fiat} ({tradeType})
├─ Total Active Ads: {total}
├─ Price Range: {min} ~ {max}
├─ Top 5 Ads:
│  1. {advNo} | {price} | {surplusAmount} {asset} | Limit: {min}~{max} | {merchantNick}
│     └─ Terms: {remarks or "—"}
│  2. ...
└─ Recommended Price: {suggestion based on reference + market}

2.2 广告配置

触发条件：

“使用浮动价格，溢价 0.5%”
“加上支付宝”
“就按推荐的来”
“单价改成 6.99，限额改到 1000-100000”

发布前准备流程：

步骤 1 — 获取可用分类：

GET /sapi/v1/c2c/agent/ads/getAvailableAdsCategory
→ {"advClassifies": ["mass", "profession", ...]}

步骤 2 — 获取用户的付款方式（发布 SELL 广告时需要 payId）：

GET /sapi/v1/c2c/agent/ads/getPayMethodByUserId
→ [{"payId": 123, "identifier": "ALIPAY", "tradeMethodName": "支付宝"}]

**显示规则：**只向用户显示 tradeMethodName（例如“支付宝”、“WeChat”、“Bank Transfer”）。 payId 是仅用于 API 请求正文的内部标识符，绝不能在面向用户的输出中泄露 payId 值。

步骤 3 — 获取所有系统交易方式（发布 BUY 广告时需要标识符）：

POST /sapi/v1/c2c/agent/ads/listAllTradeMethods
→ [{"identifier": "ALIPAY", "tradeMethodName": "支付宝", ...}]

广告参数参考：

参数	必填	说明
classify	是	广告分类：mass / profession / block / cash（默认：mass）
tradeType	是	0 = BUY，1 = SELL
asset	是	加密货币：BTC、ETH、USDT、BNB
fiatUnit	是	法币：CNY、USD 等
priceType	是	1 = 固定价格，2 = 浮动价格
price	条件必填	固定价格值（priceType=1 时必填）
priceFloatingRatio	条件必填	浮动比例 %（priceType=2 时必填）
initAmount	是	加密货币总数量
maxSingleTransAmount	是	每笔订单的法币金额上限
minSingleTransAmount	是	每笔订单的法币金额下限
buyerKycLimit	是	是否要求买家完成 KYC：0=否，1=是
tradeMethods	是	付款方式：[{payId, identifier}]
payTimeLimit	否	付款时限（分钟，默认 15）
onlineNow	否	立即上线（默认 true）
remarks	否	广告交易条款/条件（最多 1000 个字符，不得包含与加密货币相关的词语）
autoReplyMsg	否	创建订单时发送的自动回复消息（最多 1000 个字符）
buyerRegDaysLimit	否	买家注册天数下限
buyerBtcPositionLimit	否	买家 BTC 持仓下限
takerAdditionalKycRequired	否	是否要求额外验证：0=否，1=是
launchCountry	否	目标国家/地区（默认：所有地区）

确认摘要格式：

📋 Ad Configuration Summary
┌────────────────────────────────────┐
│ Trade Direction: {SELL/BUY} {asset}│
│ Fiat Currency:   {fiatUnit}        │
│ Price Type:      {Fixed/Floating}  │
│ Price:           {price or ratio%} │
│ Total Quantity:  {initAmount} {asset}│
│ Order Limit:     {min} ~ {max} {fiat}│
│ Payment Methods: {method1, method2}│
│ Payment Timeout: {payTimeLimit} min│
│ Status:          {Online/Offline}  │
├────────────────────────────────────┤
│ Advanced Settings:                 │
│  Buyer KYC: {Yes/No}              │
│  Min Reg Days: {days or "—"}      │
│  Min BTC: {amount or "—"}         │
│  Extra Verify: {Yes/No}           │
│  Regions: {countries or "All"}    │
│  Remarks: {text or "—"}           │
│  Auto Reply: {text or "—"}        │
└────────────────────────────────────┘

⚠️ Please confirm to publish (reply "确认" or "confirm")

2.3 发布广告

触发条件：

“确认”/“confirm”/“发布”（在显示 2.2 中的摘要后）

行为：

用户确认后 → 调用 POST /sapi/v1/c2c/agent/ads/post
返回结果

输出格式（成功）：

✅ Ad Published Successfully!
├─ Ad Number: {advNo}
├─ Status: Online
├─ View: https://c2c.binance.com/en/adv?code={advNo}
└─ Manage: say "查看我的广告" to see all your ads

输出格式（失败）：

❌ Ad Publish Failed
├─ Error: {error message}
└─ Suggestion: {actionable fix}

常见错误：

Permission denied → 用户不是已认证商户
FIAT_ASSET_ILLEGAL → BIDR 只能与 IDR 配对
余额不足 → 发布前检查资产余额

2.4 管理现有广告

触发条件：

“查看我的广告” / “列出我的广告”
“把第 1 条广告下架” / “将第一条广告下线”
“修改我那条 USDT 卖单的价格” / “更新我的 USDT 卖单价格”

列出我的广告

调用 POST /sapi/v1/c2c/agent/ads/listWithPagination

输出格式：

📋 My Advertisements (Total: {total})
┌────┬──────────────┬──────┬───────┬──────────┬─────────────┬──────────┬────────┐
│ #  │ Ad No        │ Type │ Asset │ Price    │ Remaining   │ Limit    │ Status │
├────┼──────────────┼──────┼───────┼──────────┼─────────────┼──────────┼────────┤
│ 1  │ {advNo}      │ SELL │ USDT  │ ¥{price} │ {surplus}   │ {min}~{max}│ Online │
│ 2  │ {advNo}      │ BUY  │ BTC   │ ¥{price} │ {surplus}   │ {min}~{max}│ Offline│
└────┴──────────────┴──────┴───────┴──────────┴─────────────┴──────────┴────────┘

# If any ad has remarks or autoReplyMsg, show below the table:
Ad Terms:
  #1: {remarks or "—"} | Auto-reply: {autoReplyMsg or "—"}
  #2: {remarks or "—"} | Auto-reply: {autoReplyMsg or "—"}

Actions: "修改第1条广告价格" | "下架第2条" | "查看详情 {advNo}"

查看广告详情

调用 POST /sapi/v1/c2c/agent/ads/getDetailByNo

触发条件：“查看详情 {advNo}” / “查看广告详情”

输出格式：

📄 Ad Detail: {advNo}
├─ Type: {tradeType} {asset}/{fiatUnit}
├─ Price: {currencySymbol}{price} ({priceType: Fixed/Floating})
├─ Remaining: {surplusAmount} / {initAmount} {asset}
├─ Limit: {minSingleTransAmount} ~ {maxSingleTransAmount} {fiatUnit}
├─ Payment Methods: {tradeMethodName1, tradeMethodName2}
├─ Status: {status}
├─ Payment Timeout: {payTimeLimit} min
│
├─ Trading Terms:
│  {remarks or "No terms set"}
│
├─ Auto-Reply Message:
│  {autoReplyMsg or "No auto-reply set"}
│
└─ Advanced:
   ├─ Buyer KYC: {Yes/No}
   ├─ Min Reg Days: {buyerRegDaysLimit or "—"}
   └─ Extra Verify: {takerAdditionalKycRequired ? "Yes" : "No"}

remarks 和 autoReplyMsg 的显示规则：getDetailByNo、listWithPagination 和 search 会返回这些字段。字段存在且非空时，始终显示；字段为 null 或空时，显示“—”或“未设置条款”等占位内容。切勿默默省略该部分——用户应当知道是否存在条款。

广告状态代码映射：

代码	显示内容	中文
1	在线	在线
2	离线	离线
4	已关闭	已关闭

更新广告

行为：

确定要更新的广告（通过列表中的 # 或 advNo）
显示差异：旧值 → 新值
等待确认
调用 POST /sapi/v1/c2c/agent/ads/update

确认格式：

📝 Update Ad: {advNo}
┌──────────────┬─────────────┬─────────────┐
│ Field        │ Current     │ New         │
├──────────────┼─────────────┼─────────────┤
│ Price        │ ¥7.20       │ ¥6.99       │
│ Max Limit    │ ¥50,000     │ ¥100,000    │
└──────────────┴─────────────┴─────────────┘

⚠️ Confirm update? (reply "确认" or "confirm")

更新广告状态（在线 / 离线 / 关闭）

行为：

确定目标广告 — 支持批量操作
显示确认信息
调用 POST /sapi/v1/c2c/agent/ads/updateStatus

确认格式：

🔄 Status Update
├─ Ads: {advNo1}, {advNo2}
├─ Action: {Online → Offline}
└─ ⚠️ Confirm? (reply "确认" or "confirm")

结果格式：

✅ Status updated: {n} ad(s) → {status}
# Or if partial failure:
⚠️ Partial success: {n} updated, {m} failed
Failed:
├─ {advNo}: {errorMessage}

场景 2 补充：商家与货币查询

查看商家资料

触发条件：

“查看商家 {merchantNo} 的信息”
“向我展示商家详情”

**行为：**调用 GET /sapi/v1/c2c/agent/merchant/getAdDetails?merchantNo={merchantNo}

输出格式：

👤 Merchant: {nickName}
├─ Type: {userType}
├─ Total Orders: {orderCount}
├─ 30-Day Orders: {monthOrderCount}
├─ 30-Day Completion: {monthFinishRate}%
├─ Avg Release Time: {advConfirmTime}s
├─ Online: {onlineStatus}
├─ Registered: {registerDays} days
│
├─ 30-Day Stats:
│  ├─ Avg Release: {avgReleaseTimeOfLatest30day}s
│  ├─ Avg Payment: {avgPayTimeOfLatest30day}s
│  └─ Completed: {completedOrderNumOfLatest30day}
│
├─ Buy Ads ({n}):
│  1. {advNo} | {asset}/{fiat} | {price} | {surplus} remaining
│     └─ Terms: {remarks or "—"}
│
└─ Sell Ads ({n}):
   1. {advNo} | {asset}/{fiat} | {price} | {surplus} remaining
      └─ Terms: {remarks or "—"}

列出支持的货币

触发条件：

“P2P 支持哪些币种？”
“支持哪些法币？”

行为：

数字货币：POST /sapi/v1/c2c/agent/digitalCurrency/list
法币：POST /sapi/v1/c2c/agent/fiatCurrency/list

第 3 阶段 API 概览

订单与申诉（SAPI Agent — 需要身份验证）

基础 URL：https://api.binance.com

端点	方法	身份验证	用途
`/sapi/v1/c2c/agent/orderMatch/getUserOrderDetail`	POST	是	按订单编号获取订单详情
`/sapi/v1/c2c/agent/orderMatch/listOrders`	POST	是	根据筛选条件列出订单
`/sapi/v1/c2c/agent/orderMatch/listUserOrderHistory`	GET	是	列出订单历史（分页）
`/sapi/v1/c2c/agent/complaint/query-complaints`	POST	是	查询投诉／申诉记录
`/sapi/v1/c2c/agent/complaint/submit-evidence`	POST	是	提交申诉证据（写入操作）
`/sapi/v1/c2c/agent/complaint/get-complaint-flows`	POST	是	获取投诉处理时间线
`/sapi/v1/c2c/agent/complaint/cancel-complaint`	POST	是	取消／撤回申诉（写入操作，不可撤销）
`/sapi/v1/c2c/agent/complaint/get-complaint-reasons`	POST	是	获取可用的投诉原因
`/sapi/v1/c2c/agent/file-upload/get-s3-presigned-url`	GET	是	获取用于上传证据的 S3 预签名 URL

广告管理（SAPI Agent — 需要身份验证）

基础 URL：https://api.binance.com

端点	方法	身份验证	用途
`/sapi/v1/c2c/agent/ads/getDetailByNo`	POST	是	根据广告编号获取广告详情
`/sapi/v1/c2c/agent/ads/listWithPagination`	POST	是	列出用户自己的广告（分页）
`/sapi/v1/c2c/agent/ads/search`	POST	是	按筛选条件搜索市场广告
`/sapi/v1/c2c/agent/ads/getReferencePrice`	POST	是	获取资产/法币的参考价格
`/sapi/v1/c2c/agent/ads/getAvailableAdsCategory`	GET	是	获取可发布的广告类别
`/sapi/v1/c2c/agent/ads/getPayMethodByUserId`	GET	是	获取用户的支付方式
`/sapi/v1/c2c/agent/ads/listAllTradeMethods`	POST	是	列出所有系统交易方式
`/sapi/v1/c2c/agent/ads/post`	POST	是	发布新广告（写入）
`/sapi/v1/c2c/agent/ads/update`	POST	是	更新现有广告（写入）
`/sapi/v1/c2c/agent/ads/updateStatus`	POST	是	批量更新广告状态（写入）

商家（SAPI Agent — 需要身份验证）

基础 URL：https://api.binance.com

端点	方法	身份验证	用途
`/sapi/v1/c2c/agent/merchant/getAdDetails`	GET	是	获取商家资料和广告列表

支持（SAPI Agent — 需要身份验证）

基础 URL：https://api.binance.com

端点	方法	身份验证	用途
`/sapi/v1/c2c/agent/digitalCurrency/list`	POST	是	列出支持的数字货币
`/sapi/v1/c2c/agent/fiatCurrency/list`	POST	是	列出支持的法币

完整 API 参考（含请求/响应架构）：请参阅 references/agent-sapi-api.md

第 3 阶段错误处理（补充）

错误	原因	用户操作
权限被拒绝	用户不是已验证的商家	引导用户前往商家验证页面
FIAT_ASSET_ILLEGAL	BIDR 与非 IDR 法币配对	BIDR 请使用 IDR 作为法币
ILLEGAL_PARAMETERS	缺少字段或字段无效	重新检查必填参数
未找到广告	advNo 无效	通过列表核实广告编号
状态更新部分失败	部分广告无法更改状态	在 failList 中检查各项错误代码

第 3 阶段限制

此技能在第 3 阶段不会：

发起新的申诉/提交投诉（仅支持为现有申诉补充证据）
自动监控申诉状态变化（此技能不支持轮询）
代表用户下单（改为引导用户前往广告详情页）
访问聊天消息或在订单聊天中发送消息
修改支付方式配置（仅支持读取）
访问 KYC/验证状态详情

如需发起申诉并实时监控申诉状态，请引导用户前往官方 P2P 争议处理中心。

支持 Markdown

登录后评论

基本信息

作者: binance
仓库: binance/binance-skills-hub
分类: 其他
安装次数: 4,740
GitHub Stars: 1,101

报告问题

p2p

关于 p2p

主要功能

适用场景

安装

包含的文件

详细介绍

Binance P2P 交易技能

何时使用／何时不使用

用户想要以下操作时使用此技能：

用户询问以下内容时，请勿使用此技能：

缺少关键输入时，请先询问澄清问题（不要猜测）：

核心概念

tradeType 映射（避免歧义）

功能

阶段 1 — 公共市场（无需身份验证）

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

阶段 3 — 订单与申诉 + 广告发布与管理（需要 API 密钥）

环境配置

基础 URL（生产环境）

实现提示（用于代码生成）

安全与隐私规则

凭据

绝不显示完整密钥

权限最小化

存储建议

⚠️ 关键：SAPI 签名（不同于标准 Binance API）

参数顺序

签名详情

API 概览

公开查询（MGS C2C Agent API——无需身份验证）

工作流：按支付方式比较价格

个人订单（Binance SAPI——需要身份验证）

输出格式指南

价格报价

广告列表

个人订单

错误处理（面向用户）

限制（设计如此）

开发者说明

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

客户端操作

第 3 阶段——订单与申诉 + 广告发布与管理

第 3 阶段设计约束

场景 1：订单查询与申诉处理

1.1 查询订单详情

1.2 查看申诉 / 投诉状态

1.3 查询投诉历史

1.4 订单列表与历史记录

1.5 提交申诉证据

1.6 查看申诉处理时间线

1.7 取消投诉／申诉

1.8 获取申诉理由

场景 2：广告发布与管理

⚠️ 写操作安全规则

2.1 市场分析与参考价格

2.2 广告配置

2.3 发布广告

2.4 管理现有广告

列出我的广告

查看广告详情

更新广告

更新广告状态（在线 / 离线 / 关闭）

场景 2 补充：商家与货币查询

查看商家资料

列出支持的货币

第 3 阶段 API 概览

订单与申诉（SAPI Agent — 需要身份验证）

广告管理（SAPI Agent — 需要身份验证）

商家（SAPI Agent — 需要身份验证）

支持（SAPI Agent — 需要身份验证）

第 3 阶段错误处理（补充）

第 3 阶段限制

评论

`tradeType` 映射（避免歧义）