p2p について
Binance P2Pの相場、広告、個人注文、異議申し立て、加盟店向け広告管理を自然言語で扱うスキルです。公開市場の照会は認証不要ですが、アカウント操作には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.mdLICENSE.mdreferences/agent-sapi-api.mdauthentication.md詳細
Binance P2P Trading Skill
自然言語での問い合わせを通じて、**Binance P2P(C2C)**の利用を支援します。
使用する場合/使用しない場合
次のことをユーザーが希望する場合は、このスキルを使用します。
- 暗号資産/法定通貨のペア(例:USDT/CNY)のP2P買値/売値を確認する。
- P2P 広告を検索し、支払い方法、取引限度額、販売者の評価で絞り込む。
- 支払い方法(例:Alipay と銀行振込)ごとの価格を比較する。
- 自身の 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 配列構文は使用しないでください。結果が空になります。
ワークフロー:支払い方法ごとの価格を比較する
ユーザーが支払い方法ごとの価格比較(例:「Alipay と WeChat」)を希望する場合は、次の 2 ステップのフローに従ってください。
ステップ 1 — trade-methods を呼び出し、対象の法定通貨で使用する正しい識別子を取得します:
GET /bapi/c2c/v1/public/c2c/agent/trade-methods?fiat=CNY
→ [{"identifier":"ALIPAY",...}, {"identifier":"WECHAT",...}, {"identifier":"BANK",...}]
ステップ 2 — tradeMethodIdentifiers を介して識別子をプレーン文字列として ad-list に渡します。支払い方法ごとにリクエストを 1 回送信し、その後、結果を比較します:
GET /bapi/c2c/v1/public/c2c/agent/ad-list?fiat=CNY&asset=USDT&tradeType=BUY&limit=5&tradeMethodIdentifiers=ALIPAY&tradeMethodIdentifiers=WECHAT
各結果セットの最良価格を比較します。
重要:
"Alipay"や"BANK"のような識別子の値をハードコードしないでください。対象の法定通貨に対応する正確なidentifier文字列を取得するため、必ず最初にtrade-methodsを呼び出してください。
個人の注文(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(法定通貨)
- merchant name(マーチャント名)
- completion rate(完了率)
- limits(制限)
- payment methods(識別子)
API が返さない限り、パラメータ化された外部 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 タイムゾーンで表示 - 含める項目:type、asset/fiat、amount、total、status
- フィルタリング時には簡単なサマリー行(件数 + 合計)を提供
時刻フィールドの変換(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 管理を確認するよう促します。 - 署名失敗(-1022):シークレットの誤り、パラメータのソート、タイムスタンプの期限切れについて警告します。
- タイムスタンプ無効(-1021):時刻同期 / タイムスタンプの再生成を勧めます。
- レート制限:後で再試行するよう伝えます。
制限事項(設計上)
このスキルは以下を行いません:
- 注文の作成 / キャンセル
- 支払い済みマーク / コインのリリース
- 新規異議申し立ての開始 / 苦情の送信(既存の異議申し立てに対する証拠の補足のみサポート)
- 広告の投稿 / 変更(Phase 1/2 のみ — Phase 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 がサポートしていない場合、取得後にローカルでフィルタリングします。
- 集計:サマリーエンドポイントでは不十分な場合、クライアント側で合計を計算します。
Phase 3 — 注文 & 異議申し立て + 広告の公開 & 管理
Phase 3 では、スキルを読み取り専用のマーケット / 注文クエリから書き込み操作(広告管理)および高度な注文ワークフロー(注文詳細、異議申し立て / 苦情の追跡)へと拡張します。
Phase 3 の設計上の制約
| 制約 | 詳細 |
|---|---|
| 認証 | Phase 3 のすべての機能には API Key + Secret Key が必要です |
| 書き込み操作の確認 | あらゆる書き込み操作(広告の公開、広告の更新、ステータスの変更)は、実行前に操作サマリーを表示し、ユーザーの明示的な確認を得る必要があります |
| API Key の権限 | Phase 1 では「Enable Reading」のみが必要でしたが、Phase 3 ではさらに広告管理のための書き込み権限が必要です |
| プライバシーマスキング | 相手方の機密情報(銀行カード、Alipay アカウント、電話番号、メールアドレス、実名)や内部 ID(payId)を決して表示しないでください。API がこれらのフィールドを返したとしても、ユーザー向け出力ではフィルタリングして除外してください。支払い方法については、tradeMethodName(例:「支付宝」)のみを表示してください |
シーン 1:注文クエリ & 異議申し立ての処理
1.1 注文詳細の照会
トリガーの例:
- 「注文 20260315123456 の詳細を表示して」
- 「最近の USDT 購入注文はどうなっていますか?」
- 「この注文番号を調べてください」
- "Show me the details of order 20260315123456"
動作:
- ユーザーが注文番号を指定した場合 →
getUserOrderDetailを呼び出します - ユーザーが注文について曖昧に説明した場合 → フィルターを指定して
listOrdersを呼び出し、ユーザーに選択してもらいます - 注文ステータスに応じて分岐します:
ステータスごとの処理:
| ステータス | アクション |
|---|---|
| Completed (4) | 全タイムライン(作成 → 支払い → 確認 → 完了)を表示して終了します |
| Cancelled (6) / Expired (7) | キャンセル理由(タイムアウト/手動/システム)を表示して終了します |
| In Progress (1=Unpaid, 2=Paid, 3=Releasing) | 現在のステップとカウントダウンタイマーを表示します |
| In Appeal (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"}
カウントダウンの表示(進行中の注文の場合):
- ステータスが 1(未払い)の場合:「支払い期限:{notifyPayEndTime}」と残り時間を表示します
- ステータスが 2(支払い済み)の場合:「リリース期限:{confirmPayEndTime}」と残り時間を表示します
1.2 申立て/苦情のステータスを確認
トリガー:
- 注文ステータスが In Appeal (5) の場合、自動的に実行します
- 「この申立てはどこまで進んでいますか?」
- 「注文 20260315123456 の申立てはどうなっていますか?」
- "What's the appeal status?"
動作:
- 注文番号を指定して
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 (Respondent Processing) | "相手方の対応を待っています。更新があれば通知されます。" |
| 1 (Complainant Processing) | "⚡ 対応が必要です — 証拠を提出するか、回答する必要があります。今すぐ証拠をアップロードするには、"submit evidence for order {orderNo}" と入力してください。" |
| 2 (CS Processing) | "💡 この段階でも、双方が証拠を提出できます。このスキルから直接証拠を提出できます。支払い証明、スクリーンショット、その他の補足書類をアップロードするには、"submit evidence for order {orderNo}" または "提交证据" と入力してください。" |
| 3 (Completed) | "この申立ては解決済みです。" |
| 4 (Cancelled) | "この申立てはキャンセルされました。" |
必ず守ること:
complaintStatusが 0、1、または 2(申立てが進行中)の場合、ユーザーに「アプリに移動する」または「紛争センターに移動する」よう案内してはいけません。必ず、このスキルを使って証拠を提出するよう案内してください。このスキルは証拠アップロードの全フロー(シーン 1.5)に対応しています。
苦情ステータスの対応表:
| ステータスコード | 表示名 | 説明 |
|---|---|---|
| 0 | Respondent Processing (被申诉人处理中) | 苦情が開始され、相手方の対応を待っています |
| 1 | Complainant Processing (申诉人处理中) | 申立人による証拠の提出または対応を待っています |
| 2 | CS Processing (客服处理中) | カスタマーサービスが確認中です。双方が証拠を提出できます |
| 3 | Completed (已完成) | 申立ては解決済みです |
| 4 | Complaint Cancelled (申诉取消) | 申立ては取り下げられました |
重要: これらを
orderStatusのコードと混同しないでください。これらは別々の列挙型です。complaintStatus=2(CS Processing)の場合、必要に応じて証拠を提出するようユーザーに案内してください。「相手方を待つ」ように案内してはいけません。
1.3 苦情履歴の照会
トリガー:
- 「すべての申立て記録を表示して」
- 「過去3か月にどのような申立てがありましたか?」
- "List my complaints as complainant"
動作:
- 任意のフィルター(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 購入注文」
- 「今週完了した注文を表示して」
動作:
- 有効な注文/最近の注文には、
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} │
└──────────────┴──────┴───────┴──────────────┴────────┴───────────────┘
注文ステータスコードの対応表:
| コード | 名前 | 中国語 |
|---|---|---|
| 0 | 処理中 | 处理中 |
| 1 | 未払い | 未付款 |
| 2 | 支払い済み(未確認) | 已付款 |
| 3 | 暗号資産のリリース中 | 放币处理中 |
| 4 | 完了 | 已完成 |
| 5 | 異議申し立て中 | 申诉中 |
| 6 | キャンセル済み | 已取消 |
| 7 | 期限切れ(システムによるキャンセル) | 超时取消 |
1.5 異議申し立ての証拠を提出する
トリガー:
- 「このスクリーンショットを異議申し立ての証拠としてアップロードして」
- 「支払い証明を提出したい」
- 「注文 228... の証拠を提出して」
- 「異議申し立てのために支払い証明をアップロードして」
- 注文が異議申し立て中(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 申し立ての処理タイムラインを表示する
トリガー:
- 「申し立ての処理フローを表示して」
- 「この申し立てではどのような手順が行われましたか?」
- 「注文 228... の申し立てのタイムラインを表示して」
- 「異議申し立ての処理では何が起きましたか?」
動作:
- 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 | 説明 |
|---|---|
| 1 | 申し立て開始 |
| 2 | 証拠提出 |
| 3 | カスタマーサポートの確認メモ |
| 4 | 解決/決定 |
注: レスポンス内の
fileUrlsは CDN で組み立てられた URL で、そのままアクセスできます。 表示時にremarkHtmlがある場合は、remarkより優先されます。
1.7 申し立て/異議申し立てを取り消す
トリガー:
- 「この申し立てを取り消して」
- 「もう異議申し立てを続けたくありません」
- 「注文 228... の異議申し立てを取り消して」
- 「申し立てを取り下げて」
⚠️ これは破壊的な操作です。必ず確認が必要です!
異議申し立ての取り消しは取り消しできません。ユーザーは紛争解決の機会を放棄し、注文は通常の解決手順に進みます。エージェントは、次の厳格な確認手順に必ず従う必要があります。
動作:
- ユーザーが取り消しの意思を示したら、最初に明確な警告を表示します
- 明示的な確認(「確認取消」/「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 苦情理由の取得
トリガー:
- "我可以用什么理由申诉?"
- "どのような理由で異議申し立てできますか?"
- "この注文で利用できる苦情理由を表示して"
- "申诉理由有哪些?"
動作:
get-complaint-reasonsを orderNo とともに呼び出します- 利用可能な理由コードと説明の一覧を表示します
出力形式:
📋 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.
注: これは読み取り専用の情報照会です。このスキルでは新しい苦情を実際に提出することはできません(提出するには、ユーザーがアプリを使用する必要があります)。
シーン 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% にして"
- "Alipay を追加して"
- "おすすめの設定でお願いします"
- "単価を 6.99 に、上限と下限を 1000~100000 に変更して"
掲載前の準備ワークフロー:
ステップ 1 — 利用可能なカテゴリーを取得します:
GET /sapi/v1/c2c/agent/ads/getAvailableAdsCategory
→ {"advClassifies": ["mass", "profession", ...]}
ステップ 2 — ユーザーの支払い方法を取得します(売り広告では payId が必要です):
GET /sapi/v1/c2c/agent/ads/getPayMethodByUserId
→ [{"payId": 123, "identifier": "ALIPAY", "tradeMethodName": "支付宝"}]
表示ルール: ユーザーには
tradeMethodName(例:「支付宝」、「WeChat」、「Bank Transfer」)のみを表示します。payIdは API リクエスト本文でのみ使用する内部識別子です。ユーザー向けの出力に payId の値を決して表示しないでください。
ステップ 3 — すべてのシステム取引方法を取得します(買い広告では識別子が必要です):
POST /sapi/v1/c2c/agent/ads/listAllTradeMethods
→ [{"identifier": "ALIPAY", "tradeMethodName": "支付宝", ...}]
広告パラメーターのリファレンス:
| パラメーター | 必須 | 説明 |
|---|---|---|
| classify | Y | 広告カテゴリー:mass/profession/block/cash(デフォルト:mass) |
| tradeType | Y | 0 = 買い、1 = 売り |
| asset | Y | 暗号資産:BTC、ETH、USDT、BNB |
| fiatUnit | Y | 法定通貨:CNY、USD など |
| priceType | Y | 1 = 固定価格、2 = 変動価格 |
| price | 条件付き | 固定価格(priceType=1 の場合に必須) |
| priceFloatingRatio | 条件付き | 変動率 %(priceType=2 の場合に必須) |
| initAmount | Y | 暗号資産の総数量 |
| maxSingleTransAmount | Y | 1 注文あたりの法定通貨の上限額 |
| minSingleTransAmount | Y | 1 注文あたりの法定通貨の下限額 |
| buyerKycLimit | Y | 購入者の KYC を必須にするか:0=いいえ、1=はい |
| tradeMethods | Y | 支払い方法:[{payId, identifier}] |
| payTimeLimit | N | 支払い期限(分)(デフォルト:15) |
| onlineNow | N | 直ちにオンラインにするか(デフォルト:true) |
| remarks | N | 広告の取引条件/規約(最大 1000 文字、暗号資産関連の単語は使用不可) |
| autoReplyMsg | N | 注文作成時の自動返信メッセージ(最大 1000 文字) |
| buyerRegDaysLimit | N | 購入者の登録日数の下限 |
| buyerBtcPositionLimit | N | 購入者の BTC 保有量の下限 |
| takerAdditionalKycRequired | N | 追加認証を必須にするか:0=いいえ、1=はい |
| launchCountry | N | 対象国(デフォルト:すべての地域) |
確認用の概要形式:
📋 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 のエラー処理(追加)
| エラー | 原因 | ユーザーの操作 |
|---|---|---|
| Permission denied | ユーザーが認証済みマーチャントではありません | マーチャント認証ページを案内してください |
| FIAT_ASSET_ILLEGAL | BIDR が IDR 以外の法定通貨とペアになっています | BIDR の法定通貨には IDR を使用してください |
| ILLEGAL_PARAMETERS | 必須フィールドが不足しているか、無効です | 必須パラメーターを再確認してください |
| Ad not found | advNo が無効です | 一覧から広告番号を確認してください |
| Status update partial failure | ステータスを変更できない広告があります | failList 内の個別のエラーコードを確認してください |
フェーズ 3 の制限事項
このスキルは、フェーズ 3 では以下を行いません。
- 新しい異議申し立てを開始する/苦情を送信する(既存の異議申し立てに対する証拠の追加のみ対応)
- 異議申し立てのステータス変更を自動監視する(スキルではポーリングに非対応)
- ユーザーに代わって注文する(代わりに広告詳細ページを案内)
- 注文チャットのメッセージにアクセスする、またはメッセージを送信する
- 支払い方法の設定を変更する(読み取りのみ)
- KYC/認証ステータスの詳細にアクセスする
異議申し立ての開始やリアルタイムでの監視については、ユーザーを公式の P2P 紛争センターに案内してください。