onchain-pay-open-api

Binance Onchain-Pay Open API スキル

RSA SHA256 リクエスト署名を自動で行い、Binance Onchain-Pay Open API のエンドポイントを呼び出します。

ユースケースとシナリオ

このスキルは、次のシナリオ向けに設計されています。

1. 💳 法定通貨で暗号資産を購入して送金

使用する場面：ユーザーが法定通貨で暗号資産を購入し、外部のオンチェーンウォレットアドレスへ直接送金したい場合

• クレジットカードで USD／EUR／TWD を使って USDT を購入し、BSC 上の MetaMask アドレスへ送金する
• Google Pay で BTC を購入し、ハードウェアウォレットへ送金する
• P2P で USDC を購入し、DeFi プロトコルのコントラクトアドレスへ送金する

主な API：trading-pairs → payment-method-list → estimated-quote → pre-order

2. 🔄 暗号資産の直接送金（送金を優先）

使用する場面：ユーザーが Binance アカウントに暗号資産を保有しており、外部アドレスへ送金したい場合

• Binance Spot の既存の USDT を友人のウォレットアドレスへ送金する
• ETH を Uniswap コントラクトへ送金して取引する
• Binance からセルフカストディ型ウォレット（Trust Wallet、Ledger など）へ暗号資産を移す

主な API：SEND_PRIMARY のカスタマイズを指定した pre-order

3. 🔗 クロスチェーンブリッジ操作

使用する場面：あるチェーンで暗号資産を購入し、別のネットワークへ送金する必要がある場合

• Ethereum で USDC を購入し、手数料の安い Polygon へブリッジする
• BSC でトークンを購入し、Base ネットワークへ送金する
• Solana で法定通貨を暗号資産に交換し、DeFi 用に Arbitrum へ送金する

主な API：crypto-network → ネットワークを選択した pre-order

4. 🏪 マーチャント決済の統合

使用する場面：E コマースやサービス向けに暗号資産決済ゲートウェイを統合する場合

• 法定通貨での決済を受け付け、自動的に暗号資産へ交換する
• 「暗号資産で支払う」チェックアウトフローを有効にする
• 暗号資産でサブスクリプション決済を処理する

主な API：externalOrderId で追跡する pre-order

5. 🤖 スマートコントラクトとの連携（Onchain-Pay Easy）

使用する場面：暗号資産を購入し、1 回のトランザクションでスマートコントラクトを実行する場合

• USDT を購入してレンディングプロトコルに預け入れる
• トークンを購入して DeFi プールにステーキングする
• 法定通貨から暗号資産へのオンランプを、GameFi や NFT マーケットプレイスへ直接行う

主な API：ON_CHAIN_PROXY_MODE のカスタマイズを指定した pre-order

6. 📊 照会とモニタリング

使用する場面：注文状況、利用可能なネットワーク、または決済方法を確認する場合

• 注文の処理状況（保留中、完了、失敗）を監視する
• 対応している法定通貨と暗号資産を一覧表示する
• 特定の国／金額で利用できる決済方法を確認する
• ネットワーク手数料と上限を確認する

主な API：order、crypto-network、trading-pairs、payment-method-list

---

クイックリファレンス

エンドポイント	API パス	必須パラメーター	任意パラメーター
決済方法一覧（v1）	papi/v1/ramp/connect/buy/payment-method-list	fiatCurrency, cryptoCurrency, totalAmount, amountType	network, contractAddress
決済方法一覧（v2）	papi/v2/ramp/connect/buy/payment-method-list	（なし）	lang
取引ペア	papi/v1/ramp/connect/buy/trading-pairs	（なし）	（なし）
見積もり額	papi/v1/ramp/connect/buy/estimated-quote	fiatCurrency, requestedAmount, payMethodCode, amountType	cryptoCurrency, contractAddress, address, network
事前注文	papi/v1/ramp/connect/buy/pre-order	externalOrderId, merchantCode, merchantName, ts	fiatCurrency, fiatAmount, cryptoCurrency, requestedAmount, amountType, address, network, payMethodCode, payMethodSubCode, redirectUrl, failRedirectUrl, redirectDeepLink, failRedirectDeepLink, customization, destContractAddress, destContractABI, destContractParams, affiliateCode, gtrTemplateCode, contractAddress
注文を取得	papi/v1/ramp/connect/order	externalOrderId	（なし）
暗号資産ネットワーク	papi/v1/ramp/connect/crypto-network	（なし）	（なし）
P2P 取引ペア	papi/v1/ramp/connect/buy/p2p/trading-pairs	（なし）	fiatCurrency

---

リクエストの実行方法

ステップ 1：認証情報を収集する

ユーザーから別途指定がない限り、デフォルトのアカウント（prod）を使用してください。以下が必要です。

• BASE_URL：API のベース URL
• CLIENT_ID：クライアント識別子
• API_KEY：署名アクセストークン
• PEM_PATH：RSA 秘密鍵 PEM ファイルの絶対パス

.local.md で (default) とマークされたアカウントを使用してください。

ステップ 2：JSON ボディを作成する

ユーザーが指定したパラメーターから、コンパクトな JSON ボディを作成します。ユーザーが指定していないパラメーターはすべて削除してください。

重要：アドレスとネットワークの検証

• address（送金先ウォレットアドレス）と network（ブロックチェーンネットワーク）は、すべての先行注文リクエストで必須です。
• ユーザーが .local.md で Default Address と Default Network を設定している場合は、自動的に使用してください。
• 設定されていない場合、またはユーザーから指定されていない場合は、続行する前に両方の値をユーザーに確認してください。

ステップ 3：同梱スクリプトを使用して署名し、呼び出す

bash <skill_path>/scripts/sign_and_call.sh \
  "<BASE_URL>" \
  "<API_PATH>" \
  "<CLIENT_ID>" \
  "<API_KEY>" \
  "<PEM_PATH>" \
  '<JSON_BODY>'

ステップ 4：結果を返す

JSON レスポンスを読みやすい形式でユーザーに表示してください。

---

認証

署名の詳細については、references/authentication.md を参照してください。

概要：

1. ペイロード = JSON_BODY + TIMESTAMP（ミリ秒）
2. PEM 秘密鍵を使用して、RSA SHA256 でペイロードに署名
3. 署名を Base64 エンコードする（1 行）
4. 次のヘッダーを付けて POST で送信：X-Tesla-ClientId、X-Tesla-SignAccessToken、X-Tesla-Signature、X-Tesla-Timestamp、Content-Type: application/json

---

パラメーターリファレンス

Payment Method List v1（buy/payment-method-list）

パラメーター	型	必須	説明
fiatCurrency	string	はい	法定通貨コード（例：USD、EUR、BRL、UGX）
cryptoCurrency	string	はい	暗号資産コード（例：BTC、USDT、USDC、SEI）
totalAmount	number	はい	金額
amountType	number	はい	1 = 法定通貨の金額、2 = 暗号資産の金額
network	string	いいえ	ブロックチェーンネットワーク（例：BSC、ETH、SOL、BASE、SEI）
contractAddress	string	いいえ	トークンのコントラクトアドレス（ネイティブではないトークンの場合は必須）

Payment Method List v2（v2/buy/payment-method-list）

法定通貨／暗号資産のパラメーターを指定せずに、利用可能なすべての支払い方法を取得します。v1 の簡易版です。

パラメーター	型	必須	説明
lang	string	いいえ	ローカライズされた支払い方法名に使用する言語コード（例：en、cn、es）

v1 との違い：

• より簡単：fiatCurrency、cryptoCurrency、金額を指定する必要はありません。
• 包括的：加盟店で利用可能なすべての支払い方法を返します。
• 用途：ユーザーが入力する前にすべての選択肢を表示するのに便利です。

レスポンス形式：v1 と同じです。上限や特性とともに、支払い方法の一覧を返します。

Estimated Quote（buy/estimated-quote）

パラメーター	型	必須	説明
fiatCurrency	string	はい	法定通貨コード
cryptoCurrency	string	いいえ	暗号資産コード（contractAddress が指定されている場合は省略可能）
requestedAmount	number	はい	金額
payMethodCode	string	はい	支払い方法（例：BUY_CARD、BUY_GOOGLE_PAY、BUY_P2P、BUY_WALLET）
amountType	number	はい	1 = 法定通貨の金額、2 = 暗号資産の金額
network	string	はい*	ブロックチェーンネットワーク（.local.md のデフォルトを使用できます）
contractAddress	string	いいえ	トークンのコントラクトアドレス
address	string	はい*	暗号資産の受け取り先ウォレットアドレス

* 推奨：これらのパラメーターを指定してください。ユーザーから指定されていない場合は、.local.md にデフォルト値があるか確認してください。デフォルト値がない場合は、続行する前にユーザーに確認してください。

事前注文（buy/pre-order）

購入の事前注文を作成し、決済用のリダイレクトリンクを返します。

パラメーター	型	必須	説明
externalOrderId	string	はい	パートナー固有の注文 ID（重複不可）
merchantCode	string	はい	Binance から割り当てられたマーチャントコード（ユーザーから提供）
merchantName	string	はい	マーチャントの表示名（ユーザーから提供）
ts	number	はい	現在のタイムスタンプ（ミリ秒）
fiatCurrency	string	いいえ*	法定通貨コード（例：TWD、USD、EUR）
fiatAmount	number	いいえ*	使用する法定通貨の金額
cryptoCurrency	string	いいえ*	購入する暗号資産（例：USDT、BTC、ETH）
requestedAmount	number	いいえ*	金額（amountType に応じて法定通貨または暗号資産）
amountType	number	いいえ*	1 = 法定通貨の金額、2 = 暗号資産の金額
address	string	いいえ	暗号資産の受取先ウォレットアドレス
network	string	いいえ	ブロックチェーンネットワーク（例：BSC、ETH、SOL）
payMethodCode	string	いいえ	決済方法コード（例：BUY_CARD、BUY_P2P、BUY_GOOGLE_PAY、BUY_APPLE_PAY、BUY_PAYPAL、BUY_WALLET、BUY_REVOLUT）
payMethodSubCode	string	いいえ	決済方法のサブコード（例：card、GOOGLE_PAY、WECHAT）
redirectUrl	string	いいえ	成功時のリダイレクト URL
failRedirectUrl	string	いいえ	失敗時のリダイレクト URL
redirectDeepLink	string	いいえ	成功時のディープリンク（モバイルアプリ用）
failRedirectDeepLink	string	いいえ	失敗時のディープリンク（モバイルアプリ用）
customization	object	いいえ	カスタム設定オブジェクト（下記の「カスタマイズオプション」セクションを参照）
destContractAddress	string	いいえ	送信先コントラクトアドレス（Onchain-Pay Easy モード用）
destContractABI	string	いいえ	コントラクト ABI 名（Onchain-Pay Easy モード用）
destContractParams	object	いいえ	コントラクトパラメーター（Onchain-Pay Easy モード用）
affiliateCode	string	いいえ	手数料追跡用のアフィリエイトコード
gtrTemplateCode	string	いいえ	GTR テンプレートコード（例：OTHERS）
contractAddress	string	いいえ	トークンコントラクトアドレス（ネイティブトークン以外の場合）

• fiatAmount、または（requestedAmount + amountType）のいずれかを指定してください。fiatCurrency が指定されていない場合、システムは利用可能な法定通貨を自動選択します。

レスポンスの例：

{
  "code": "000000",
  "message": "success",
  "data": {
    "link": "https://app.binance.com/uni-qr/ccnt?...",
    "linkExpireTime": 1772852565045
  },
  "success": true
}

注文の取得（order）

パラメーター	型	必須	説明
externalOrderId	string	はい	照会する外部注文 ID

---

カスタマイズオプション

事前注文 API の customization フィールドでは、購入フローの動作をカスタマイズするためのさまざまなフラグを指定できます。各マーチャントには、db.merchant_info テーブルで対応する権限を設定する必要があります。

利用可能なカスタマイズフラグ

フラグ	コード	型	利用可否	説明	使用例
LOCK_ORDER_ATTRIBUTES	1	array	Open API ✓	特定の注文属性をロックし、ユーザーが変更できないようにします。値：1=法定通貨、2=暗号資産、3=金額、4=支払い方法、5=ネットワーク、6=アドレス、7=法定通貨額、8=暗号資産額	パラメーター固定注文
SKIP_CASHIER	2	boolean	Open API ✓	キャッシャーページをスキップして、支払いに直接進みます。チェックアウトの手順でユーザーの負担を軽減します。	スムーズな支払い体験
AUTO_REDIRECTION	3	boolean	Open API ✓	注文完了後、成功ページを表示せずに redirectUrl へ自動的にリダイレクトします。	シームレスなユーザー体験
HIDE_SEND	6	boolean	Open API ✓	UI の「送金」タブを非表示にします。購入フローのみが必要な場合に便利です。	購入のみの連携
SEND_PRIMARY	7	boolean	Open API ✓	暗号資産送金機能を有効にします。ユーザーの Binance 残高が不足している場合、最初に購入フローを自動的に開始します。	外部アドレスへの暗号資産送金
MERCHANT_DISPLAY_NAME	8	string	Open API ✓	UI でユーザーに表示される名前を上書きします。	カスタムブランディング
NET_RECEIVE	9	boolean	Open API ✓	すべての手数料を差し引いた純額をユーザーが受け取ります。合計コストがより明確になります。	最終受取額をわかりやすく表示するための UX 向上
P2P_EXPRESS	10	boolean	Open API ✓	P2P 注文のマッチングを高速化する P2P Express モードを有効にします。	P2P 取引の迅速化
OPEN_NETWORK	11	boolean	Web3 のみ	ユーザーが異なるネットワークを選択できるようにします。デフォルトでは、事前選択されたネットワークに固定されます。注意：現在は Web3 エントランスでのみ利用可能で、Open API では利用できません。	マルチネットワーク対応（Web3 のみ）
ON_CHAIN_PROXY_MODE	12	boolean	Open API ✓	Onchain-Pay Easy モードを有効にします。暗号資産の購入後、Onchain-Pay はユーザーのウォレットへ直接出金する代わりに、スマートコントラクトとの連携を実行します。destContractAddress、destContractABI、および destContractParams が必要です。	法定通貨からスマートコントラクトへの連携
SEND_PRIMARY_FLEXIBLE	13	boolean	Open API ✓	より多くのオプションを備えた柔軟な Send Primary モードです。	高度な暗号資産送金シナリオ

カスタマイズの例

例 1：基本的なカード決済

{
  "customization": {}
}

例 2：Onchain-Pay Easy（オンチェーンプロキシ）

{
  "customization": {
    "ON_CHAIN_PROXY_MODE": true,
    "NET_RECEIVE": true,
    "SEND_PRIMARY": true
  },
  "destContractAddress": "0x128...974",
  "destContractABI": "depositFor",
  "destContractParams": {
    "accountType": 2
  }
}

例 3：暗号資産の送金

{
  "customization": {
    "SEND_PRIMARY_FLEXIBLE": true,
    "SEND_PRIMARY": true
  }
}

例 4：自動リダイレクト付き P2P

{
  "customization": {
    "AUTO_REDIRECTION": true,
    "P2P_EXPRESS": true
  }
}

例 5：注文属性のロック

{
  "customization": {
    "LOCK_ORDER_ATTRIBUTES": [2, 3, 6, 7, 8],
    "MERCHANT_DISPLAY_NAME": "My Custom Brand"
  }
}

属性コードをロックします：

• 2 = 暗号資産
• 3 = 金額
• 6 = アドレス
• 7 = 法定通貨額
• 8 = 暗号資産額

例 6：純額受取モード

{
  "customization": {
    "NET_RECEIVE": true,
    "SEND_PRIMARY": true
  }
}

例 7：「送金」タブを非表示

{
  "customization": {
    "HIDE_SEND": true
  }
}

例 8：キャッシャーをスキップ（直接支払い）

{
  "customization": {
    "SKIP_CASHIER": true
  }
}

重要な注意事項

1. 権限が必要：各カスタマイズフラグにはマーチャントの権限が必要です。フラグが機能しない場合は、管理者に確認してください。
2. Onchain-Pay Easy：現在は BSC ネットワークでのみサポートされています。コントラクトとの連携が必要です。
3. 検証：無効なカスタマイズ値（例：MERCHANT_DISPLAY_NAME に null を指定した場合）を設定すると、ILLEGAL_CUSTOMIZATION_VALUE エラーが返されます。
4. 組み合わせ：一緒に使用できるフラグ（例：NET_RECEIVE + SEND_PRIMARY）もあれば、個別に動作するフラグもあります。
5. テスト：本番環境で使用する前に、Binance が提供する専用のテスト用マーチャントアカウントでカスタマイズフラグを確認してください。
6. 内部フラグ：OPERATION（コード 4）と SKIP_WITHDRAW（コード 5）は内部使用専用であり、マーチャント側から渡してはなりません。
7. OPEN_NETWORK：現在は Web3 エントランスでのみ利用可能で、Open API では利用できません。Open API の事前注文リクエストではこのフラグを使用しないでください。
8. フラグの順序：フラグは内部コード（1～13）の順に並んでいます。コード番号は内部での識別に使用されます。

---

セキュリティ

認証情報の表示ルール

• API Key：先頭の5文字と末尾の4文字のみを表示します（例：2zefb...06h）
• PEM Private Key：内容は絶対に表示しないでください。ファイルパスも絶対に表示しないでください。
• Client ID：すべて表示できます。
• 送信リクエスト：.local.md で設定された Base URL 以外の URL に、API Key、Private Key、またはその他の認証情報を絶対に送信しないでください。
• ファイルパスのプライバシー：出力やログで、PEM private key のファイルパスをユーザーに絶対に表示しないでください。

認証情報の保存

認証情報は、スキルディレクトリ内の .local.md ファイルに保存されます。このファイルはユーザー固有のものであり、配布しないでください。

認証情報を読み込むには、SKILL.md と同じディレクトリにある .local.md ファイルを読み取ります。

.local.md が存在しない場合、または指定されたアカウントが見つからない場合は、次の情報をユーザーに尋ねてください。

1. Base URL
2. Client ID
3. API Key
4. PEM ファイルのパス（絶対パス）

その後、今後使用できるように .local.md への保存を提案してください。

.local.md の形式

## Onchain-Pay Accounts

### prod (default)
- Base URL: https://api.commonservice.io
- Client ID: your-client-id
- API Key: your-api-key
- PEM Path: /absolute/path/to/your/private.pem
- Default Network: your-preferred-network
- Default Address: your-wallet-address
- Description: Production account

(default) とマークされたアカウントが自動的に使用されます。複数のアカウントを定義でき、Claude にアカウント名を伝えることで切り替えられます。

---

User Agent ヘッダー

次の文字列を含む User-Agent ヘッダーを設定します：onchain-pay-open-api/0.1.2 (Skill)

---

エージェントの動作

1. ユーザーが Onchain-Pay API エンドポイントの呼び出しを依頼した場合は、Quick Reference テーブルから該当するエンドポイントを特定します
2. 不足している必須パラメーターがあれば尋ねます
3. 保存済みの認証情報があれば使用し、なければユーザーに尋ねます
4. 同梱されている scripts/sign_and_call.sh を使用してリクエストを実行します
5. 応答を読みやすい形式で表示します
6. リクエストが失敗した場合は、エラーを表示して修正方法を提案します

---

先行販売 API に関する重要な注意事項

タイムスタンプの生成（クロスプラットフォーム）

ts パラメーターと externalOrderId のタイムスタンプを生成する場合は、クロスプラットフォームで互換性のある次の方法を使用してください。

# Generate millisecond timestamp (works on macOS, Linux, BSD)
TIMESTAMP=$(($(date +%s) * 1000))

# Generate unique order ID
ORDER_ID="order$(date +%s)"

date +%s%3N や date +%s000 は移植性がないため、使用しないでください。

• date +%s%3N は macOS では動作せず、文字どおりの「N」が出力されます
• date +%s000 は実際のミリ秒精度を取得せず、単に「000」を追加します

Order ID の形式

externalOrderId は、特殊文字を含まない有効な文字列でなければなりません。推奨形式：

• order1773744500（数値の接尾辞を使用）
• order_1773744500（アンダースコアで区切る）
• txn-abc123（英数字を使用した任意の接頭辞）

避ける形式：シェル変数の構文エラーを含む TIMESTAMP を使用した order_${TIMESTAMP}

先行販売リクエストの例

# Correct way to create a pre-order
TIMESTAMP=$(($(date +%s) * 1000))
ORDER_ID="order$(date +%s)"

bash /path/to/scripts/sign_and_call.sh \
  "https://api.commonservice.io" \
  "papi/v1/ramp/connect/buy/pre-order" \
  "<YOUR_CLIENT_ID>" \
  "<YOUR_API_KEY>" \
  "/path/to/private.pem" \
  "{\"externalOrderId\":\"$ORDER_ID\",\"merchantCode\":\"<YOUR_MERCHANT_CODE>\",\"merchantName\":\"<YOUR_MERCHANT_NAME>\",\"ts\":$TIMESTAMP,\"fiatCurrency\":\"USD\",\"requestedAmount\":100,\"cryptoCurrency\":\"BNB\",\"amountType\":1,\"address\":\"0x...\",\"network\":\"BSC\",\"payMethodCode\":\"BUY_CARD\"}"