P2p

1---2name: p2p3description: |4  Binance P2P trading assistant for natural-language queries about P2P/C2C market ads and (optionally) the user’s own P2P order history.5 6  Use when the user asks about P2P prices, searching/choosing ads, comparing payment methods, or reviewing their P2P order history (requires API key).7 8  Do NOT use for spot/futures prices, exchange trading, deposits/withdrawals, on-chain transfers, or anything unrelated to P2P/C2C.9---10 11# Binance P2P Trading Skill12 13Help users interact with **Binance P2P (C2C)** via natural-language queries.14 15## When to Use / When NOT to Use16 17### Use this skill when the user wants to:18- Check **P2P** buy/sell quotes for a crypto/fiat pair (e.g., USDT/CNY).19- Search **P2P advertisements** and filter by payment method(s), limits, merchant quality.20- Compare prices across payment methods (e.g., Alipay vs bank transfer).21- View **their own P2P order history / summary** (requires API key).22 23### Do NOT use this skill when the user asks about:24- Spot/Convert prices, futures/derivatives, margin, trading bots.25- Deposits/withdrawals, wallet transfers, on-chain transactions.26- Creating/cancelling orders, appeals, releasing coins (trading operations).27 28### Ask clarifying questions (do not guess) if any key inputs are missing:29- `fiat` (e.g., CNY)30- `asset` (e.g., USDT)31- user intent: **buy crypto** or **sell crypto**32- preferred payment method(s)33- target amount (optional but recommended for ad filtering)34 35## Core Concepts36 37### `tradeType` mapping (avoid ambiguity)38- User wants to **buy crypto** (pay fiat, receive USDT/BTC) → `tradeType=BUY`39- User wants to **sell crypto** (receive fiat, pay USDT/BTC) → `tradeType=SELL`40 41Always reflect this mapping in responses when the user’s wording is ambiguous.42 43## Capabilities44 45### Phase 1 — Public Market (No Auth)46- Quote P2P prices47- Search ads48- Compare payment methods49- Filter/Rank ads by limits and merchant indicators50 51### Phase 2 — Personal Orders (Requires API Key)52- List P2P order history53- Filter by trade type / time range54- Provide summary statistics55 56## Security & Privacy Rules57 58### Credentials59- Required env vars:60    - `BINANCE_API_KEY` (sent as header)61    - `BINANCE_SECRET_KEY` (used for signing)62 63### Never display full secrets64- API Key: show **first 5 + last 4** characters: `abc12...z789`65- Secret Key: always mask; show **only last 5**: `***...c123`66 67### Permission minimization68- Binance API permissions: **Enable Reading** only.69- Do NOT request/encourage trading, withdrawal, or modification permissions.70 71### Storage guidance72- Prefer environment injection (session/runtime env vars) over writing to disk.73- Only write to `.env` if the user explicitly agrees.74- Ensure `.env` is in `.gitignore` before saving.75 76## ⚠️ CRITICAL: SAPI Signing (Different from Standard Binance API)77 78### Parameter ordering79- **DO NOT sort parameters** for SAPI requests.80- Keep original insertion order when building the query string.81 82Example:83```py84# ✅ Correct for SAPI: keep insertion order85params = {"page": 1, "rows": 20, "timestamp": 1710460800000}86query_string = urlencode(params)  # NO sorting87 88# ❌ Wrong (standard Binance API only): sorted89query_string = urlencode(sorted(params.items()))90```91 92### Signing details93See: `references/authentication.md` for:94- RFC 3986 percent-encoding95- HMAC SHA256 signing process96- Required headers (incl. User-Agent)97- SAPI-specific parameter ordering98 99## API Overview100 101### Public Queries (MGS C2C Agent API — No Auth)102Base URL: `https://www.binance.com`103 104| Endpoint | Method | Params | Usage |105|----------|--------|--------|-------|106| `/bapi/c2c/v1/public/c2c/agent/quote-price` | GET | fiat, asset, tradeType | Quick price quote |107| `/bapi/c2c/v1/public/c2c/agent/ad-list` | GET | fiat, asset, tradeType, limit, order, tradeMethodIdentifiers | Search ads |108| `/bapi/c2c/v1/public/c2c/agent/trade-methods` | GET | fiat | Payment methods |109 110Parameter notes:111- `tradeType`: `BUY` or `SELL` (treat as case-insensitive)112- `limit`: 1–20 (default 10)113- `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.114 115### Workflow: Compare Prices by Payment Method116 117When the user wants to compare prices across payment methods (e.g., "Alipay vs WeChat"), follow this two-step flow:118 119**Step 1** — Call `trade-methods` to get the correct identifiers for the target fiat:120```121GET /bapi/c2c/v1/public/c2c/agent/trade-methods?fiat=CNY122→ [{"identifier":"ALIPAY",...}, {"identifier":"WECHAT",...}, {"identifier":"BANK",...}]123```124 125**Step 2** — Pass the identifier as a plain string into `ad-list` via `tradeMethodIdentifiers`, one payment method per request, then compare:126```127GET /bapi/c2c/v1/public/c2c/agent/ad-list?fiat=CNY&asset=USDT&tradeType=BUY&limit=5&tradeMethodIdentifiers=ALIPAY&tradeMethodIdentifiers=WECHAT128```129Compare the best price from each result set.130 131> **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.132 133### Personal Orders (Binance SAPI — Requires Auth)134Base URL: `https://api.binance.com`135 136| Endpoint | Method | Auth | Usage |137|----------|--------|------|-------|138| `/sapi/v1/c2c/orderMatch/listUserOrderHistory` | GET | Yes | Order history |139| `/sapi/v1/c2c/orderMatch/getUserOrderSummary` | GET | Yes | User statistics |140 141Authentication requirements:142- Header: `X-MBX-APIKEY`143- Query: `timestamp` + `signature`144- Header: `User-Agent: binance-wallet/1.0.0 (Skill)`145 146## Output Format Guidelines147 148### Price quote149- Show both sides when available (best buy / best sell).150- Use fiat symbol and 2-decimal formatting.151 152Example:153```154USDT/CNY (P2P)155- Buy USDT (you buy crypto): ¥7.20156- Sell USDT (you sell crypto): ¥7.18157```158 159### Ad list160Return **Top N** items with a stable schema:1611) adNo (ad number / identifier)1622) price (fiat)1633) merchant name1644) completion rate1655) limits1666) payment methods (identifiers)167 168Avoid generating parameterized external URLs unless the API returns them.169 170**Placing orders (when user requests):**171- This skill does NOT support automated order placement.172- When user wants to place an order, provide a direct link to the specific ad using the adNo:173  ```174  https://c2c.binance.com/en/adv?code={adNo}175  ```176    - `{adNo}`: the ad number/identifier from the ad list result177 178  Example: `https://c2c.binance.com/en/adv?code=123`179- This opens the specific ad detail page where user can place order directly with the selected advertisement.180 181### Personal orders182- Time format: `YYYY-MM-DD HH:mm (UTC+0)` — always display in UTC timezone183- Include: type, asset/fiat, amount, total, status184- Provide a brief summary line (count + totals) when filtering185 186**Time field conversion (for `createTime` in `listUserOrderHistory`):**187- The `createTime` field returns a Unix timestamp in **milliseconds** (13 digits).188- Convert to human-readable format in **UTC+0 timezone**:189  ```190  # Python example191  from datetime import datetime, timezone192  readable_time = datetime.fromtimestamp(createTime / 1000, tz=timezone.utc).strftime('%Y-%m-%d %H:%M (UTC+0)')193  194  # JavaScript example195  const readableTime = new Date(createTime).toISOString().replace('T', ' ').slice(0, 16) + ' (UTC+0)';196  // Or more explicitly:197  const date = new Date(createTime);198  const readableTime = date.getUTCFullYear() + '-' +199    String(date.getUTCMonth() + 1).padStart(2, '0') + '-' +200    String(date.getUTCDate()).padStart(2, '0') + ' ' +201    String(date.getUTCHours()).padStart(2, '0') + ':' +202    String(date.getUTCMinutes()).padStart(2, '0') + ' (UTC+0)';203  ```204- Always display the converted time to users with timezone info, not the raw timestamp.205 206## Error Handling (User-Facing)207 208- Invalid API key (-2015): prompt to verify `.env` / API Management.209- Signature failed (-1022): warn about wrong secret, sorted params, or stale timestamp.210- Timestamp invalid (-1021): advise time sync / regenerate timestamp.211- Rate limit: ask to retry later.212 213## Limitations (By Design)214 215This skill does NOT:216- Place/cancel orders217- Mark as paid / release coins218- Submit appeals219- Post/modify advertisements220- Expose sensitive order-detail endpoints beyond what’s needed for history/summary221 222For in-app actions, guide users to the official P2P orders page (only as a general entry point).223 224## Developer Notes225 226### Version Check (First Invocation per Conversation)227On the first invocation of this skill per conversation, call:228 229- `GET /bapi/c2c/v1/public/c2c/agent/check-version?version=1.0.1` (Base: `https://www.binance.com`)230 231Behavior:232- If `needUpdate=true`: show: `New version of P2P Skill is available (current: {clientVersion}, latest: {latestVersion}), update recommended.`233- Else / on failure: proceed silently.234 235### Client-side operations236- Asset filtering: if API doesn’t support it, fetch then filter locally.237- Aggregations: compute totals client-side when summary endpoint is insufficient.