# AI で連携 · blockwallets

> 自分でコードを書かずに blockwallets の暗号資産決済を追加:サイトと AI ツールを選び、生成されたプロンプトを Claude Code、Codex、Cursor、ChatGPT に貼り付けると、ドキュメントに基づいて連携し、自分で結果を確認します。
>
> HTML: https://blockwallets.io/docs/ai?lang=ja · English: https://blockwallets.io/docs/ai.md?lang=en

## 汎用プロンプト

```text
blockwallets を使って、私のウェブサイトで暗号資産決済を受け付けられるようにしてください(お客様は USDT、USDC、BTC などで支払い、私には米ドルで計上されます)。

1. API を推測せず、まずドキュメントを読んでください:https://blockwallets.io/llms-full.txt(ドキュメント全文)と https://blockwallets.io/agents.md(連携ルール、よくある間違い、受け入れチェックリスト)。開けない場合は教えてください。
2. 私のプロジェクトを調べ、何で作られているか、どのように連携するつもりかを教えて、私の OK を待ってください。
3. 既定は「請求を作成して決済ページへリダイレクト + Webhook」です。Webhook の署名は必ず検証し、同じ Webhook が2回届くことがあるので重複を排除してください。
4. merchant ID と API key は環境変数に保存し、まず Test の認証情報でテストネット上で動くようにしてください。
5. 完了したら、agents.md の受け入れチェックリストを項目ごとに確認し、結果を教えてください。

私はプログラマーではありません。各ステップで、何を変更したか、私が何をする必要があるかを教えてください。
```

## サイトについて教えてください。

わからない場合は「その他 / わからない」を選ぶと、AI がまずプロジェクトを調べます。

- サイトの構成: WordPress / WooCommerce · PHP · Node.js / Next.js · Python · Go · Java · その他 / わからない
- 希望する受け取り方:
  - 決済ページへリダイレクト: チェックアウト時に請求を作成し、支払いが完了するとサーバーに通知します。注文は自動で発送されます。
  - ユーザーごとの固定入金アドレス: ユーザーごとに恒久アドレスを発行し、いつでも好きな金額をチャージできます。
  - 決済リンク(コード不要): 管理画面でリンクを作成して共有します。AI はボタンを追加するだけです。

決済リンクにコードは不要です。管理画面 →「入金 › 支払いリンク」→ 金額を入力 → 作成、そしてリンクを共有します。AI がサイトに置くのはボタンだけです。

## どの AI を使いますか?

- **Claude Code / Codex**: コードを編集してコマンドを実行する AI。いちばん簡単です。
  - サイトのプロジェクトフォルダーでターミナルを開き、連携ルールを AGENTS.md として保存します。
  - `curl -fsSL https://blockwallets.io/agents.md -o AGENTS.md`
  - Codex は AGENTS.md を自動で読み込みます。Claude Code では、さらに次を実行します。
  - `echo '@AGENTS.md' >> CLAUDE.md`
  - そのあと、ステップ 3 のプロンプトを貼り付けます。
  - blockwallets の MCP サーバーをインストールすると、AI がドキュメントを検索し、テスト用の請求を直接作成できるようになります。 https://blockwallets.io/docs/mcp?lang=ja
- **Cursor / Windsurf / Copilot**: コードエディターの中で動く AI。
  - こちらも AGENTS.md をプロジェクトのルートに置きます(Cursor は自動で認識します)。
  - `curl -fsSL https://blockwallets.io/agents.md -o AGENTS.md`
  - Agent モードに切り替えて、プロンプトを貼り付けます。
  - blockwallets の MCP サーバーをインストールすると、AI がドキュメントを検索し、テスト用の請求を直接作成できるようになります。 https://blockwallets.io/docs/mcp?lang=ja
- **ChatGPT / Claude(Web)**: チャットのみ。コードはご自身でサイトに貼り付けます。
  - 新しいチャットにプロンプトを貼り付けるか、下の「ChatGPT / Claude で開く」を使います。
  - リンクを開けないと言われたら、https://blockwallets.io/llms-full.txt を開き、全選択してコピーし、それも貼り付けてください。
  - 完全なコードと置き場所が示されるので、ステップごとに従ってください。コードを代わりに編集してくれるツール(Claude Code、Codex、Cursor)を使うと、コピー作業が大幅に減ります。
- **その他の AI**: Gemini、Copilot のチャットなど。
  - プロンプトを貼り付けます。Web ページを開けない場合は、llms-full.txt の内容も貼り付けてください。

## プロンプトをコピー。

上の選択に合わせて更新され、ドキュメントへのリンク、よくある落とし穴、受け入れチェックリストが含まれます。

例:その他 / わからない + 決済ページへリダイレクト + Claude Code / Codex

```text
あなたは私の開発者です。blockwallets を使って、私のウェブサイトで暗号資産決済を受け付けられるようにしてください(お客様は USDT、USDC、BTC ほか 14 種類の通貨で支払い、私には米ドルで計上されます)。

## 私について
- 私のサイトの構成:わかりません。まず私のプロジェクトを見て、何で作られているかを教えてから、作業を始めてください。
- 希望する受け取り方:チェックアウト時に請求を作成してお客様を blockwallets の決済ページへリダイレクトし、入金されたら blockwallets が私のサーバーを呼び出すので、私は注文を支払済みにして発送します。
- 私はプログラマーではありません。各ステップで、どのファイルを変更したか、私が何をする必要があるか(たとえば環境変数をどこに置くか)を教えてください。一度に大きく変更しないでください。
- プロジェクトのルートにある AGENTS.md に blockwallets の連携ルールがあります。まずそれを読み、詳細は https://blockwallets.io/llms-full.txt を読んでください。

## まずドキュメントを読み、API を記憶で推測しないでください
- 連携ドキュメント全文(Markdown):https://blockwallets.io/llms-full.txt
- 連携ルールとよくある間違い:https://blockwallets.io/agents.md
- すでに Cryptomus、NOWPayments、Coinbase Commerce を使っているサイトなら、書き直さずに対応する互換 API へ切り替えてください:https://blockwallets.io/docs/migrate.md?lang=en
- リンクを開けない場合は、そう伝えてください。内容を貼り付けます。

## 要点(連携でよく間違える箇所)
1. すべてのエンドポイントは https://blockwallets.io への POST + JSON です。ヘッダー:merchant = merchant UUID、sign = md5(base64(リクエストボディ) + API key)。送信する JSON 文字列そのものに署名し、署名後に再シリアライズしないでください。
2. POST /v1/payment で請求を作成します。必須:amount(小数点以下 2 桁までの文字列、例:"42.00")、currency("USD")、order_id(私の注文番号:英字、数字、- と _、100 文字以内)。さらに url_callback(Webhook の URL)と url_success(支払い後にお客様が戻る先)も渡します。お客様を result.url へリダイレクトします。
3. 同じ order_id で再度呼び出すと同じ請求が返るため、再試行は安全で、2件目の請求が作られることはありません。
4. Webhook の署名は必ず検証してください。Webhook の JSON を解析して sign フィールドを取り除き、残りを PHP の json_encode と同じ方法で再エンコードします(コンパクト、非 ASCII はそのまま、/ は \/ にエスケープ)。そのうえで md5(base64(エンコード結果) + API key) が sign と一致しなければなりません。/ のエスケープ忘れが最もよくある間違いです。
5. 注文を支払済みにするのは、status が paid または paid_over のときだけで、payment_amount_usd を使います。同じ Webhook が複数回届くことがあるため、uuid + status で重複を排除してください。処理が済んだら 2xx のステータスで応答します。
6. merchant ID と API key は環境変数(例:BW_MERCHANT、BW_API_KEY)に保存し、コードに直接書いたりコミットしたりしないでください。先に、管理画面の「開発者 › 連携とキー」ページの「サイトのドメイン」に、Webhook URL のドメインを追加します。
7. まず Test の認証情報(テストネット、本物のお金は動きません)ですべて動くようにしてください。Live への切り替えは、私が確認してからにします。

## 完了したら、各項目を確認して結果を教えてください
- [ ] Test の認証情報でテスト用の請求を作成し、決済ページのリンク(result.url)を取得する
- [ ] 決済ページを開き、「決済をシミュレート」→ 全額 をクリックする
- [ ] 私のサーバーが status が paid の Webhook を受け取り、署名の検証が通る
- [ ] 対応する注文が支払済みになる
- [ ] 同じ Webhook が再度届いても(管理画面の「開発者 › Webhook ログ」から再送するか、POST /v1/payment/resend)、二重に発送されない

いずれかの項目が失敗したら、ほかの変更を加える前に、どこで止まっているかと正確なエラーメッセージを教えてください。
```

### AI が完了したら、これを確認

**決済ページへリダイレクト**

1. Test の認証情報でテスト用の請求を作成し、決済ページのリンク(result.url)を取得する
2. 決済ページを開き、「決済をシミュレート」→ 全額 をクリックする
3. 私のサーバーが status が paid の Webhook を受け取り、署名の検証が通る
4. 対応する注文が支払済みになる
5. 同じ Webhook が再度届いても(管理画面の「開発者 › Webhook ログ」から再送するか、POST /v1/payment/resend)、二重に発送されない

**ユーザーごとの固定入金アドレス**

1. Test の認証情報でテストユーザーのアドレスを発行し、アドレスと入金ページのリンクを取得する
2. POST /v1/test-webhook/wallet でサンプル Webhook を送る
3. 私のサーバーが type が wallet の Webhook を受け取り、署名の検証が通る
4. そのユーザーの残高が payment_amount_usd の分だけ増える
5. 同じ Webhook が再度届いても、残高が二重に加算されない

**決済リンク(コード不要)**

1. ボタンがデスクトップでもスマートフォンでも問題なく表示される
2. ボタンが私の決済リンクを開く(まず Test モードで作成したリンクを使う)
3. 決済ページで「決済をシミュレート」をクリックすると、管理画面の「入金 › 入金履歴」にその支払いが表示される

## AI が行き詰まったら。

- **署名がどうしても検証できない**: Webhook の生のボディを[署名チェッカー](https://blockwallets.io/docs/sign?lang=ja)に貼り付けてください。途中の各ステップが表示され、最初の相違箇所に印が付きます。何が異なるのかをそのまま AI に伝えてください。
- **エンドポイントがエラーを返す**: リクエストとレスポンス(message を含む)を、そのまま AI に貼り付けてください。署名が誤っている場合、401 レスポンスの debug.body_base64 は当社が署名したテキストなので、AI 自身の結果と比べさせてください。
- **どこで止まっているかわからない**: AI に、受け入れチェックリストを最初の項目から1つずつ確認させ、各結果を報告させてください。管理画面の「開発者 › Webhook ログ」には、すべての Webhook リクエストとあなたのサーバーの応答が表示されます。

### 注意していただきたい4つのこと。

- **AI に渡すのは Test の認証情報だけ**: Test の merchant ID と API key はテストネットで動くため、漏えいしてもお金は動きません。
- **Live の API key をチャットに出さない**: Live の API key は、ご自身でサーバーの環境変数に設定してください。チャットに貼り付けたり、リポジトリにコミットしたりしないでください。
- **AI が編集する前にバックアップ**: AI が作業を始める前に、サイトのファイルをコミット(git commit)またはコピーしておけば、元に戻せます。
- **本番前に自分で一度支払う**: Live に切り替えたら、管理画面ホームの「試しに 1 件決済」で少額の実際の支払いを行い、注文が支払済みになり、残高に入ることを確認してください。

## コーディングエージェント向けのルールファイル。

AGENTS.md には、連携の要点、よくある間違い、受け入れチェックリストがまとまっています。プロジェクトのルートに置くと、Codex と Cursor は自動で読み込み、Claude Code は @AGENTS.md で取り込めます。

```sh
curl -fsSL https://blockwallets.io/agents.md -o AGENTS.md
echo '@AGENTS.md' >> CLAUDE.md
```

- [連携ルール(AGENTS.md)](https://blockwallets.io/agents.md)
- [1ページの概要](https://blockwallets.io/llms.txt)
- [ドキュメント全文](https://blockwallets.io/llms-full.txt)
- [このページの Markdown](https://blockwallets.io/docs/ai.md?lang=ja)
- [ドキュメントの Markdown](https://blockwallets.io/docs.md?lang=ja)
- [MCP サーバー](https://blockwallets.io/docs/mcp?lang=ja)

## 疑問にお答えします。

### コードが書けなくても、本当に AI で連携できますか?

ほとんどのサイトでは可能です。AI がドキュメントをもとに請求作成と署名のコードを書き、あなたは認証情報を環境変数に設定して、テストモードで受け入れチェックリストを順に確認します。コードをまったく書きたくない場合は、決済リンクを使ってください。

### どの AI ツールを使えばよいですか?

プロジェクトを編集してコマンドを実行できるツールがいちばん簡単です。Claude Code、Codex、Cursor などです。Web 版の ChatGPT や Claude でも可能ですが、コードはご自身でサイトに貼り付ける必要があります。

### API key を AI に渡してもよいですか?

渡してよいのは Test の認証情報だけで、チャットではなく環境ファイルに入れてください。Live の API key は、ご自身でサーバーに設定します。

### Webhook の署名がどうしても検証できません。どうすればよいですか?

sign を取り除き、残りを PHP の json_encode と同じ方法で再エンコードして、/ を \/ にエスケープします。Webhook の生のボディを /docs/sign に貼り付けて各ステップを比較し、何が異なるかを AI に伝えてください。

### AI が完了したと言っています。どう確認すればよいですか?

受け入れチェックリストを実行します。テスト用の請求を作成し、支払いをシミュレートして、Webhook の検証が通り、注文が支払済みになることを確認し、同じ Webhook を再送して二重に発送されないことを確かめます。本番前に、Live で少額を支払ってください。