mcpField
P
p2p

p2p

github.com/binanceその他1.1k4.7k 回インストール2 日前に更新
リポジトリ

p2p について

Binance P2Pの相場、広告、個人注文、異議申し立て、加盟店向け広告管理を自然言語で扱うスキルです。公開市場の照会は認証不要ですが、アカウント操作にはAPI認証が必要で、広告公開には加盟店権限も必要です。

主な機能

  1. 01P2P価格の照会と広告検索
  2. 02決済方法や広告の比較
  3. 03注文履歴と詳細の照会
  4. 04異議申し立て状況・証拠・経過の確認
  5. 05加盟店広告の公開と管理

活用シーン

  1. 01決済方法別にUSDT価格を比較
  2. 02個人のP2P注文と集計を確認
  3. 03異議申し立てを追跡して証拠を提出
  4. 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 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_BASEhttps://api.binance.com
MGS_BASEhttps://www.binance.com
C2C_WEBhttps://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-priceGETfiat, asset, tradeType簡易価格見積もり
/bapi/c2c/v1/public/c2c/agent/ad-listGETfiat, asset, tradeType, limit, order, tradeMethodIdentifiers広告の検索
/bapi/c2c/v1/public/c2c/agent/trade-methodsGETfiat支払い方法

パラメーターに関する注記:

  • 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/listUserOrderHistoryGET必要注文履歴
/sapi/v1/c2c/orderMatch/getUserOrderSummaryGET必要ユーザー統計

認証要件:

  • ヘッダー: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 件の項目を安定したスキーマで返します:

  1. adNo(広告番号 / 識別子)
  2. price(法定通貨)
  3. merchant name(マーチャント名)
  4. completion rate(完了率)
  5. limits(制限)
  6. 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"

動作:

  1. ユーザーが注文番号を指定した場合 → getUserOrderDetail を呼び出します
  2. ユーザーが注文について曖昧に説明した場合 → フィルターを指定して listOrders を呼び出し、ユーザーに選択してもらいます
  3. 注文ステータスに応じて分岐します:

ステータスごとの処理:

ステータスアクション
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?"

動作:

  1. 注文番号を指定して query-complaints を呼び出します
  2. 苦情情報を構造化された形式で表示します

出力形式:

⚠️ 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)に対応しています。

苦情ステータスの対応表:

ステータスコード表示名説明
0Respondent Processing (被申诉人处理中)苦情が開始され、相手方の対応を待っています
1Complainant Processing (申诉人处理中)申立人による証拠の提出または対応を待っています
2CS Processing (客服处理中)カスタマーサービスが確認中です。双方が証拠を提出できます
3Completed (已完成)申立ては解決済みです
4Complaint Cancelled (申诉取消)申立ては取り下げられました

重要: これらを orderStatus のコードと混同しないでください。これらは別々の列挙型です。 complaintStatus=2(CS Processing)の場合、必要に応じて証拠を提出するようユーザーに案内してください。「相手方を待つ」ように案内してはいけません。

1.3 苦情履歴の照会

トリガー:

  • 「すべての申立て記録を表示して」
  • 「過去3か月にどのような申立てがありましたか?」
  • "List my complaints as complainant"

動作:

  1. 任意のフィルター(roleIdentity、status、日付範囲)を指定して query-complaints を呼び出します
  2. 日付が指定されていない場合、直近90日を対象にします
  3. ページ分割された結果を表示します

出力形式:

📋 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 の書き込み操作と同じ確認手順が適用されます。

  1. 提出する内容(ファイル名、説明、注文番号)の概要を表示します
  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... の申し立てのタイムラインを表示して」
  • 「異議申し立ての処理では何が起きましたか?」

動作:

  1. orderNo(任意で complaintNo も指定)を使って get-complaint-flows を呼び出します
  2. すべての処理手順を時系列で表示します

出力形式:

📜 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... の異議申し立てを取り消して」
  • 「申し立てを取り下げて」

⚠️ これは破壊的な操作です。必ず確認が必要です!

異議申し立ての取り消しは取り消しできません。ユーザーは紛争解決の機会を放棄し、注文は通常の解決手順に進みます。エージェントは、次の厳格な確認手順に必ず従う必要があります。

動作:

  1. ユーザーが取り消しの意思を示したら、最初に明確な警告を表示します
  2. 明示的な確認(「確認取消」/「confirm cancel」/「yes」)を待ちます
  3. その後に限り、orderNo を指定して cancel-complaint を呼び出します
  4. 結果を表示します

警告形式(実行前に必ず表示):

⚠️ 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 苦情理由の取得

トリガー:

  • "我可以用什么理由申诉?"
  • "どのような理由で異議申し立てできますか?"
  • "この注文で利用できる苦情理由を表示して"
  • "申诉理由有哪些?"

動作:

  1. get-complaint-reasons を orderNo とともに呼び出します
  2. 利用可能な理由コードと説明の一覧を表示します

出力形式:

📋 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 のすべての書き込み操作では、次の手順に必ず従ってください。

  1. 事前確認: ユーザーに加盟店権限があることを確認します(API 自体でも確認しますが、403/Permission denied の場合はユーザーにはっきり伝えてください)
  2. 概要の提示: 書き込み API を実行する前に、操作の概要をすべて表示します
  3. 明示的な確認: 続行する前に、ユーザーが「确认」/「confirm」/「发布」/「yes」と言うまで待ちます
  4. 自動実行の禁止: ユーザーが最初のリクエストで「そのまま実行して」と言った場合も、必ず先に概要を表示します
2.1 市場分析と参考価格

トリガー:

  • "我想发一个 USDT/CNY 的卖单广告"
  • "BTC の買い注文広告を出して"
  • "現在の市場参考価格はいくらですか?"
  • "USDT/CNY の参考価格はいくらですか?"

動作:

  1. getReferencePrice を呼び出して、市場の参考価格を取得します
  2. search を呼び出して、現在の市場における広告の分布を分析します
  3. ユーザーが判断できるよう、価格設定に関する情報を提示します

出力形式(参考価格):

📊 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": "支付宝", ...}]

広告パラメーターのリファレンス:

パラメーター必須説明
classifyY広告カテゴリー:mass/profession/block/cash(デフォルト:mass)
tradeTypeY0 = 買い、1 = 売り
assetY暗号資産:BTC、ETH、USDT、BNB
fiatUnitY法定通貨:CNY、USD など
priceTypeY1 = 固定価格、2 = 変動価格
price条件付き固定価格(priceType=1 の場合に必須)
priceFloatingRatio条件付き変動率 %(priceType=2 の場合に必須)
initAmountY暗号資産の総数量
maxSingleTransAmountY1 注文あたりの法定通貨の上限額
minSingleTransAmountY1 注文あたりの法定通貨の下限額
buyerKycLimitY購入者の KYC を必須にするか:0=いいえ、1=はい
tradeMethodsY支払い方法:[{payId, identifier}]
payTimeLimitN支払い期限(分)(デフォルト:15)
onlineNowN直ちにオンラインにするか(デフォルト:true)
remarksN広告の取引条件/規約(最大 1000 文字、暗号資産関連の単語は使用不可)
autoReplyMsgN注文作成時の自動返信メッセージ(最大 1000 文字)
buyerRegDaysLimitN購入者の登録日数の下限
buyerBtcPositionLimitN購入者の BTC 保有量の下限
takerAdditionalKycRequiredN追加認証を必須にするか:0=いいえ、1=はい
launchCountryN対象国(デフォルト:すべての地域)

確認用の概要形式:

📋 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 の概要を提示した後)

動作:

  1. ユーザーが確認したら → POST /sapi/v1/c2c/agent/ads/post を呼び出します
  2. 結果を返します

出力形式(成功):

✅ 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クローズ済み已关闭
広告を更新する

動作:

  1. 更新する広告を特定します(一覧の番号または advNo で指定)
  2. 差分を表示します:変更前の値 → 変更後の値
  3. 確認を待ちます
  4. 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")
広告のステータスを更新する(オンライン/オフライン/クローズ)

動作:

  1. 対象の広告を特定します(複数の広告を一括操作できます)
  2. 確認を表示します
  3. 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/getUserOrderDetailPOSTはい注文番号で注文の詳細を取得
/sapi/v1/c2c/agent/orderMatch/listOrdersPOSTはい条件を指定して注文を一覧表示
/sapi/v1/c2c/agent/orderMatch/listUserOrderHistoryGETはい注文履歴を一覧表示(ページネーション対応)
/sapi/v1/c2c/agent/complaint/query-complaintsPOSTはい苦情/異議申し立ての記録を照会
/sapi/v1/c2c/agent/complaint/submit-evidencePOSTはい異議申し立ての証拠を提出(書き込み操作)
/sapi/v1/c2c/agent/complaint/get-complaint-flowsPOSTはい苦情処理のタイムラインを取得
/sapi/v1/c2c/agent/complaint/cancel-complaintPOSTはい異議申し立てをキャンセル/取り下げ(書き込み操作、取り消し不可)
/sapi/v1/c2c/agent/complaint/get-complaint-reasonsPOSTはい選択可能な苦情理由を取得
/sapi/v1/c2c/agent/file-upload/get-s3-presigned-urlGETはい証拠アップロード用の S3 署名付き URL を取得
広告管理(SAPI Agent — 認証が必要)

ベース URL:https://api.binance.com

エンドポイントメソッド認証用途
/sapi/v1/c2c/agent/ads/getDetailByNoPOSTはい広告番号で広告の詳細を取得
/sapi/v1/c2c/agent/ads/listWithPaginationPOSTはいユーザー自身の広告を一覧表示(ページネーション対応)
/sapi/v1/c2c/agent/ads/searchPOSTはいフィルターを指定してマーケットの広告を検索
/sapi/v1/c2c/agent/ads/getReferencePricePOSTはい資産/法定通貨の参考価格を取得
/sapi/v1/c2c/agent/ads/getAvailableAdsCategoryGETはい公開可能な広告カテゴリーを取得
/sapi/v1/c2c/agent/ads/getPayMethodByUserIdGETはいユーザーの支払い方法を取得
/sapi/v1/c2c/agent/ads/listAllTradeMethodsPOSTはいシステムのすべての取引方法を一覧表示
/sapi/v1/c2c/agent/ads/postPOSTはい新しい広告を公開(書き込み)
/sapi/v1/c2c/agent/ads/updatePOSTはい既存の広告を更新(書き込み)
/sapi/v1/c2c/agent/ads/updateStatusPOSTはい広告のステータスを一括更新(書き込み)
マーチャント(SAPI Agent — 認証が必要)

ベース URL:https://api.binance.com

エンドポイントメソッド認証用途
/sapi/v1/c2c/agent/merchant/getAdDetailsGETはいマーチャントのプロフィールと広告一覧を取得
サポート(SAPI Agent — 認証が必要)

ベース URL:https://api.binance.com

エンドポイントメソッド認証用途
/sapi/v1/c2c/agent/digitalCurrency/listPOSTはいサポート対象のデジタル通貨を一覧表示
/sapi/v1/c2c/agent/fiatCurrency/listPOSTはいサポート対象の法定通貨を一覧表示

リクエスト/レスポンスのスキーマを含む完全な API リファレンスについては、references/agent-sapi-api.md を参照してください。

フェーズ 3 のエラー処理(追加)

エラー原因ユーザーの操作
Permission deniedユーザーが認証済みマーチャントではありませんマーチャント認証ページを案内してください
FIAT_ASSET_ILLEGALBIDR が IDR 以外の法定通貨とペアになっていますBIDR の法定通貨には IDR を使用してください
ILLEGAL_PARAMETERS必須フィールドが不足しているか、無効です必須パラメーターを再確認してください
Ad not foundadvNo が無効です一覧から広告番号を確認してください
Status update partial failureステータスを変更できない広告がありますfailList 内の個別のエラーコードを確認してください

フェーズ 3 の制限事項

このスキルは、フェーズ 3 では以下を行いません。

  • 新しい異議申し立てを開始する/苦情を送信する(既存の異議申し立てに対する証拠の追加のみ対応)
  • 異議申し立てのステータス変更を自動監視する(スキルではポーリングに非対応)
  • ユーザーに代わって注文する(代わりに広告詳細ページを案内)
  • 注文チャットのメッセージにアクセスする、またはメッセージを送信する
  • 支払い方法の設定を変更する(読み取りのみ)
  • KYC/認証ステータスの詳細にアクセスする

異議申し立ての開始やリアルタイムでの監視については、ユーザーを公式の P2P 紛争センターに案内してください。

コメント