p2p
Binance P2P trading assistant for natural-language queries about P2P/C2C market ads, the user's own P2P order history, order detail & appeal tracking, and advertisement publish & management. Use when the user asks about P2P prices, searching/choosing ads, comparing payment methods, reviewing P2P ord
By binance · 3,709 installs
npx skills add binance/binance-skills-hub --skill p2p
Source repository · Upstream listing
Binance P2P Trading Skill
Help users interact with Binance P2P (C2C) via natural language queries.
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).
Query order detail and view full order timeline (requires API key).
Check appeal/complaint status and view complaint history (requires API key).
Submit evidence for an existing appeal (upload files + submit description) (requires API key).
View complaint process timeline (flow of actions, CS notes, evidence) (requires API key).
Cancel an existing appeal (withdraw complaint, irreversible) (requires API key).
View available complaint reasons for an order (requires API key).
Publish, update, or manage P2P advertisements (requires API key + merchant permission).
View merchant profiles and their ad listings (requires API key).
Query supported digital and fiat currencies (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, releasing coins (trading operations). Cancelling appeals (complaints) IS supported.
Initiating new appeals (submit complaint is deferred; evidence supplement for existing appeals IS supported).
Sending chat messages in order conversations.
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
Always reflect this mapping in responses when the user's wording is ambiguous.
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
Phase 3 — Order & Appeal + Ad Publish & Management (Requires API Key)
Query order detail by order number
List orders with rich filters (status, trade type, asset, date range)
View order timeline (creation → payment → release → completion)
Detect appeal status and show appeal details
Query complaint/appeal records with filters
Get market reference prices for pricing decisions
Upload appeal evidence files (S3 presigned URL + submit)
View complaint process timeline / flow details
Cancel an existing appeal / withdraw complaint
Get available complaint reasons for an order
Search and analyze market ad distribution
Get available ad categories for current user
Get user's configured payment methods
List all system trade methods
Publish new advertisements (with confirmation)
Update existing ad parameters (with confirmation)
Update ad status: online / offline / close (with confirmation)
View merchant profile and ad listings
List all supported digital currencies
List all supported fiat currencies
Environment Configuration
Base URLs (production)
Logical Name URL
SAPI BASE https://api.binance.com
MGS BASE https://www.binance.com
C2C WEB https://c2c.binance.com
Implementation hint (for code generation)
When the skill generates curl / Python / JS code, use these fixed base URLs:
Note: SAPI signing uses HMAC SHA256, no param sorting required.
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 (Phase 1/2).
Phase 3 ad management additionally needs write permissions.
Do NOT request/encourage withdrawal or modification permissions beyond what's needed.
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.
Example:
Signing details
See: references/authentication.md for:
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)
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.
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:
Step 2 — Pass the identifier as a plain string into ad list via tradeMethodIdentifiers , one payment method per request, then compare:
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.
Personal Orders (Binance SAPI — Requires Auth)
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)
Output Format Guidelines
Price quote
Show both sides when available (best buy / best sell).
Use fiat symbol and 2 decimal formatting.
Example:
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 specific ad using the adNo:
{adNo} : the ad number/identifier from the ad list result
Example: https://c2c.binance.com/en/adv?code=123
This opens the specific ad detail page where user can place order directly with the selected advertisement.
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 :
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)
This skill does NOT:
Place/cancel orders
Mark as paid / release coins
Initiate new appeals / submit complaint (only evidence supplement for existing appeals is supported)
Post/modify advertisements (Phase 1/2 only — Phase 3 adds ad management for merchants)
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).
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=2.0.0 (Base: https://www.binance.com )
Behavior:
If needUpdate=true : show: New version of P2P Skill is available (current: {clientVersion}, latest: {latestVersion}), update recommended.
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.
Phase 3 — Order & Appeal + Ad Publish & Management
Phase 3 extends the skill from read only market/order queries to write operations (ad management) and advanced order workflows (order detail, appeal/complaint tracking).
Phase 3 Design Constraints
Constraint Details
Authentication All Phase 3 features require API Key + Secret Key
Write op confirmation Any write operation (publish ad, update ad, change status) must show an operation summary and get explicit user confirmation before executing
API Key permissions Phase 1 only needed "Enable Reading"; Phase 3 additionally needs write permissions for ad management
Privacy masking Never display counterparty sensitive info (bank card, Alipay account, phone, email, real name) or internal IDs ( payId ). Even if the API returns these fields, filter them out in user facing output . For payment methods, show only tradeMethodName (e.g. "支付宝")
Scene 1: Order Query & Appeal Handling
1.1 Query Order Detail
Trigger examples:
"查看订单 20260315123456 的详情"
"我最近那笔 USDT 买入订单怎么样了？"
"帮我查一下这个订单号"
"Show me the details of order 20260315123456"
Behavior:
1. If user provides an order number → call getUserOrderDetail
2. If user describes an order vaguely → call listOrders with filters, then let user pick
3. Based on order status, branch:
Status branch handling:
Status Action
Completed (4) Show full timeline (create → pay → confirm → complete), finish
Cancelled (6) / Expired (7) Show cancel reason (timeout / manual / system), finish
In Progress (1=Unpaid, 2=Paid, 3=Releasing) Show current step + countdown timers
In Appeal (5) Auto enter 1.2 — show appeal status
Output format (Order Detail):
Countdown display (for in progress orders):
If status=1 (Unpaid): show "Payment deadline: {notifyPayEndTime}" with remaining time
If status=2 (Paid): show "Release deadline: {confirmPayEndTime}" with remaining time
1.2 View Appeal / Complaint Status
Trigger:
Automatically when order status = In Appeal (5)
"这个申诉进展到哪了？"
"订单 20260315123456 的申诉怎么样了？"
"What's the appeal status?"
Behavior:
1. Call query complaints with the order number
2. Display complaint info