p2p

What this skill does

# 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:

```python
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
# Bash equivalent:
SAPI_BASE="https://api.binance.com"
MGS_BASE="https://www.binance.com"
C2C_WEB="https://c2c.binance.com"
```

> **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:
```py
# ✅ 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()))
```

### 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:
```
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.

### Personal Orders (Binance SAPI