# Integrate with AI · blockwallets

> Add blockwallets crypto payments without writing code yourself: pick your site and your AI tool, copy the generated prompt into Claude Code, Codex, Cursor or ChatGPT, and it integrates from the docs and checks its own work.
>
> HTML: https://blockwallets.io/docs/ai?lang=en · 中文: https://blockwallets.io/docs/ai.md

## Universal prompt

```text
Help me accept crypto payments on my website with blockwallets (customers pay in USDT, USDC, BTC and more; I’m credited in US dollars).

1. Read the docs first instead of guessing the API: https://blockwallets.io/llms-full.txt (full docs) and https://blockwallets.io/agents.md (integration rules, common mistakes, acceptance checklist). Tell me if you can’t open them.
2. Look at my project, tell me what it’s built with and how you plan to integrate, and wait for my OK.
3. Default to “create a bill and redirect to the payment page + webhook”. Always verify webhook signatures, and deduplicate webhooks because the same one can arrive twice.
4. Keep the merchant ID and API key in environment variables, and get it working with the Test credentials on testnets first.
5. When done, go through the acceptance checklist in agents.md item by item and tell me each result.

I’m not a programmer: for every step, tell me what you changed and what I need to do.
```

## Tell us about your site.

Not sure? Pick “Other / not sure” and the AI will look at your project first.

- What your site is built with: WordPress / WooCommerce · PHP · Node.js / Next.js · Python · Go · Java · Other / not sure
- How you want to get paid:
  - Redirect to a payment page: Create a bill at checkout, we notify your server when it’s paid. Orders ship on their own.
  - A fixed deposit address per user: Each user gets a permanent address and tops up any amount, any time.
  - Payment link (no code): Create a link in the dashboard and share it. AI only adds a button.

Payment links need no code: dashboard → “Payments › Payment links” → enter an amount → create, then share the link. The AI only puts a button on your site.

## Which AI do you use?

- **Claude Code / Codex**: AI that edits your code and runs commands. The easiest.
  - Open a terminal in your website’s project folder and save the integration rules as AGENTS.md:
  - `curl -fsSL https://blockwallets.io/agents.md -o AGENTS.md`
  - Codex reads AGENTS.md on its own. For Claude Code, also run:
  - `echo '@AGENTS.md' >> CLAUDE.md`
  - Then paste the prompt from step 3.
  - You can also install the blockwallets MCP server so the AI can search the docs and create test bills directly. https://blockwallets.io/docs/mcp?lang=en
- **Cursor / Windsurf / Copilot**: AI inside your code editor.
  - Put AGENTS.md in the project root too (Cursor picks it up automatically):
  - `curl -fsSL https://blockwallets.io/agents.md -o AGENTS.md`
  - Switch to Agent mode and paste the prompt.
  - You can also install the blockwallets MCP server so the AI can search the docs and create test bills directly. https://blockwallets.io/docs/mcp?lang=en
- **ChatGPT / Claude (web)**: Chat only. You paste the code into your site yourself.
  - Paste the prompt into a new chat, or use “Open in ChatGPT / Claude” below.
  - If it says it can’t open links, open https://blockwallets.io/llms-full.txt, select all, copy and paste it in as well.
  - It will give you complete code and where to put it; follow it step by step. A tool that edits code for you (Claude Code, Codex, Cursor) saves a lot of copying.
- **Another AI**: Gemini, Copilot chat and others.
  - Paste the prompt. If it can’t open web pages, paste the contents of llms-full.txt as well.

## Copy the prompt.

It updates as you choose above and carries the docs links, the usual pitfalls and an acceptance checklist.

Example: Other / not sure + redirect to a payment page + Claude Code / Codex

```text
You are my developer. Help me accept crypto payments on my website with blockwallets (customers pay in USDT, USDC, BTC and 14 other coins; I’m credited in US dollars).

## About me
- My site is built with: I’m not sure. Look at my project first, tell me what it is built with, then start.
- How I want to get paid: Create a bill at checkout and redirect the customer to the blockwallets payment page; when the money arrives, blockwallets calls my server and I mark the order as paid and ship it.
- I’m not a programmer. For every step, tell me which files you changed and what I need to do (for example where to put environment variables). Don’t change too much at once.
- AGENTS.md in the project root holds the blockwallets integration rules; read it first, and read https://blockwallets.io/llms-full.txt for details.

## Read the docs first; don’t guess the API from memory
- Full integration docs (Markdown): https://blockwallets.io/llms-full.txt
- Integration rules and common mistakes: https://blockwallets.io/agents.md
- If the site already uses Cryptomus, NOWPayments or Coinbase Commerce, switch it to the matching compatible API instead of rewriting: https://blockwallets.io/docs/migrate.md?lang=en
- If you can’t open a link, tell me and I’ll paste the content.

## Key points (where integrations usually go wrong)
1. Every endpoint is POST + JSON on https://blockwallets.io. Headers: merchant = the merchant UUID, sign = md5(base64(request body) + API key). Sign the exact JSON string you send; do not re-serialize after signing.
2. Create a bill with POST /v1/payment. Required: amount (a string with up to two decimals, e.g. "42.00"), currency ("USD"), order_id (my order number: letters, digits, - and _, up to 100 characters). Also pass url_callback (the webhook URL) and url_success (where the customer returns after paying). Redirect the customer to result.url.
3. Calling again with the same order_id returns the same bill, so retries are safe and never create a second bill.
4. Webhook signatures must be verified: parse the webhook JSON, drop the sign field, re-encode the rest the way PHP json_encode does (compact, non-ASCII kept, / escaped as \/), then md5(base64(encoded) + API key) must equal sign. Forgetting to escape / is the most common mistake.
5. Mark the order paid only when status is paid or paid_over, using payment_amount_usd. The same webhook can arrive more than once: deduplicate by uuid + status. Reply with a 2xx status once handled.
6. Keep the merchant ID and API key in environment variables (e.g. BW_MERCHANT, BW_API_KEY); never hard-code them or commit them. Add the domain of the webhook URL under “Website domains” on the dashboard’s “Developers › Integration & keys” page first.
7. Get everything working with the Test credentials first (testnets, no real money); switch to Live only after I confirm.

## When you’re done, check each item and tell me the result
- [ ] Create a test bill with the Test credentials and get the payment page link (result.url)
- [ ] Open the payment page and click “Simulate payment” → full amount
- [ ] My server receives a webhook with status paid and the signature verifies
- [ ] The matching order is marked as paid
- [ ] The same webhook arriving again (resend it from the dashboard’s “Developers › Webhook log”, or POST /v1/payment/resend) does not ship twice

If any item fails, tell me where it’s stuck and the exact error message before changing anything else.
```

### When the AI is done, check these

**Redirect to a payment page**

1. Create a test bill with the Test credentials and get the payment page link (result.url)
2. Open the payment page and click “Simulate payment” → full amount
3. My server receives a webhook with status paid and the signature verifies
4. The matching order is marked as paid
5. The same webhook arriving again (resend it from the dashboard’s “Developers › Webhook log”, or POST /v1/payment/resend) does not ship twice

**A fixed deposit address per user**

1. Open an address for a test user with the Test credentials and get the address and deposit page link
2. Send a sample webhook with POST /v1/test-webhook/wallet
3. My server receives a webhook with type wallet and the signature verifies
4. That user’s balance goes up by payment_amount_usd
5. The same webhook arriving again does not credit the balance twice

**Payment link (no code)**

1. The button looks right on desktop and on a phone
2. The button opens my payment link (use a link created in Test mode first)
3. Clicking “Simulate payment” on the payment page shows the payment under “Payments › Transactions” on the dashboard

## When the AI gets stuck.

- **The signature never verifies**: Paste the raw webhook body into the [signature checker](https://blockwallets.io/docs/sign?lang=en). It shows every intermediate step and marks the first difference; tell your AI exactly what differs.
- **An endpoint returns an error**: Paste the exact request and response (including message) back to your AI. When the signature is wrong, debug.body_base64 in the 401 response is the text we signed; have the AI compare it with its own.
- **Not sure where it’s stuck**: Ask the AI to go through the acceptance checklist from the first item, one at a time, reporting each result. The dashboard’s “Developers › Webhook log” shows every webhook request and your server’s response.

### Four things you keep an eye on.

- **Give the AI Test credentials only**: The Test merchant ID and API key run on testnets; even if they leak, no money can move.
- **Keep the Live API key out of chats**: Put the Live API key into your server’s environment variables yourself. Never paste it into a chat or commit it to a repository.
- **Back up before the AI edits**: Commit (git commit) or copy your site’s files before the AI starts, so you can roll back.
- **Pay once yourself before going live**: After switching to Live, pay a small real amount via “Try a payment” on the dashboard home page and check the order is paid and the balance arrives.

## A rules file for coding agents.

AGENTS.md holds the integration essentials, common mistakes and the acceptance checklist. Put it in your project root: Codex and Cursor read it automatically, Claude Code imports it with @AGENTS.md.

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

- [Integration rules (AGENTS.md)](https://blockwallets.io/agents.md)
- [One-page summary](https://blockwallets.io/llms.txt)
- [Full docs](https://blockwallets.io/llms-full.txt)
- [This page as Markdown](https://blockwallets.io/docs/ai.md?lang=en)
- [Docs as Markdown](https://blockwallets.io/docs.md?lang=en)
- [MCP server](https://blockwallets.io/docs/mcp?lang=en)

## Questions, answered.

### Can I really integrate with AI if I can’t code?

For most sites, yes. The AI writes the bill-creation and signature code from the docs; you put the credentials into environment variables and click through the acceptance checklist in test mode. If you don’t want any code at all, use payment links.

### Which AI tool should I use?

A tool that edits your project and runs commands is easiest: Claude Code, Codex or Cursor. ChatGPT or Claude on the web work too, but you paste the code into your site yourself.

### Should I give my API key to the AI?

Only the Test credentials, and in an environment file rather than the chat. Put the Live API key on your server yourself.

### The webhook signature never verifies. What now?

Drop sign, re-encode the rest the way PHP json_encode does and escape / as \/. Paste the raw webhook body into /docs/sign to compare every step, then tell the AI what differs.

### The AI says it’s done. How do I check?

Run the acceptance checklist: create a test bill, simulate the payment, see the webhook verify, see the order marked paid, and resend the same webhook to confirm nothing ships twice. Pay a small Live amount before going live.