The signature never verifies
Paste the raw webhook body into the signature checker. It shows every intermediate step and marks the first difference; tell your AI exactly what differs.
No coding needed. Pick your site and your AI tool, hand it the prompt we generate, and it integrates from our docs, then checks its own work item by item.
Universal prompt · no choices needed
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.
Opening copies the full prompt to your clipboard; the link carries only a short opener. Paste once it opens.
Step 1
Not sure? Pick “Other / not sure” and the AI will look at your project first.
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.
Open the dashboardStep 2
Each tool reads docs differently; follow the matching steps.
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.mdCodex reads AGENTS.md on its own. For Claude Code, also run:
echo '@AGENTS.md' >> CLAUDE.mdThen 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.MCP setup →
Put AGENTS.md in the project root too (Cursor picks it up automatically):
curl -fsSL https://blockwallets.io/agents.md -o AGENTS.mdSwitch 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.MCP setup →
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.
Paste the prompt. If it can’t open web pages, paste the contents of llms-full.txt as well.
Step 3
It updates as you choose above and carries the docs links, the usual pitfalls and an acceptance checklist.
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.
Have the AI report each result. Switch to Live only when all pass.
Stuck?
Most problems are signatures. Raw text helps the AI far more than a description.
Paste the raw webhook body into the signature checker. It shows every intermediate step and marks the first difference; tell your AI exactly what differs.
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.
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.
Safety
The Test merchant ID and API key run on testnets; even if they leak, no money can move.
Put the Live API key into your server’s environment variables yourself. Never paste it into a chat or commit it to a repository.
Commit (git commit) or copy your site’s files before the AI starts, so you can roll back.
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.
Rules file
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.
curl -fsSL https://blockwallets.io/agents.md -o AGENTS.mdecho '@AGENTS.md' >> CLAUDE.mdFiles for AI
FAQ
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.
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.
Only the Test credentials, and in an environment file rather than the chat. Put the Live API key on your server yourself.
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.
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.