# BitPal

> BitPal is a non-custodial stablecoin checkout for merchants. Each order gets its own deposit
> address, cryptographically committed to the merchant's payout wallet; the buyer sends USDC,
> USDT or JPYC from any wallet or exchange, and funds settle same-chain, same-token to the
> merchant. BitPal never holds funds. Integrate with the `@bitpal/checkout` SDK or REST API
> (hosted, popup or headless checkout), no-code payment links, or x402 pay-per-call.

BitPal is operated at https://bitpal.io. The API is https://api.bitpal.io. The official
JavaScript/TypeScript SDK is `@bitpal/checkout` on npm (MIT).

## Rules for AI coding assistants

Follow these when writing a BitPal integration:

1. Keep secret API keys (`bp_test_…`, `bp_live_…`) and the webhook secret (`whsec_…`) on the server. Browsers only get the `checkout_url`.
2. Fulfil orders from the `checkout.session.paid` webhook (signature verified) or a server-side session lookup. Never from the redirect to `success_url` or a popup message.
3. Verify webhooks on the raw request body with `X-Webhook-Signature-256` and `X-Webhook-Timestamp`. The SDK's `verifyWebhookSignature` is async — `await` it.
4. Webhooks are delivered at least once and can arrive out of order. Deduplicate on the body `id`; keep the furthest session state.
5. Amounts are strings. Pass `amount` as a plain number string in the line item `currency` (`"29"`); never use floating-point math. `amount_total` is a 6-decimal integer string; deposit amounts use the token's decimals.
6. Session statuses are `created`, `awaiting_deposit`, `deposit_detected`, `paid_confirmed`, `swept`, `expired`, `unresolved_underpaid`, `wrong_token`. Treat `paid_confirmed`/`swept` as paid — there is no `paid` or `settled` status value.
7. The payment window is `expires_in_minutes` (1–60, default 15). A full payment up to 7 days late is still accepted (`late: true` on the webhook) — handle it, or create the session with `late_payments: "refund"` to have late payments refunded automatically (~7 days after the deadline).
8. Test keys accept only testnet chain values; live keys only mainnet. Use CAIP-2 ids or short names (`base`, `arbitrum`, `bnb`, `tron`, `solana`, `polygon`, `kaia`).
9. A self-built (headless) payment UI must call BitPal through the merchant backend (CORS); only the public session endpoint is callable from the browser.
10. Send an `Idempotency-Key` when creating a session (`POST /v1/checkout/sessions`) so retries are safe. Other POST endpoints do not enforce it yet — check whether a first attempt succeeded before retrying.
11. For a test payment without a wallet, use Console → Developers → Sandbox (test mode): it sends the deposit for you and shows the webhook events.
12. There is no refund API (BitPal is non-custodial). Do not generate code that calls one. A completed payment is refunded by the merchant in Console → Sessions → Refund (send from their own wallet, record the tx); listen for `checkout.refund.recorded` and treat unknown `kind` values (e.g. `merchant`) as a refund.
13. The session total (sum of `amount` × `quantity`) must be at least 1.00 in the session currency ($1 USDC/USDT, ¥1 JPYC) or the API returns `400 CHECKOUT_AMOUNT_TOO_LOW`. Tron needs at least $300 (testnet included); smaller totals don't offer Tron.
14. Put your order id in session `metadata` — it comes back in every webhook's `data.metadata`. `checkout.session.deposit_detected` is optional; `paid` can arrive without it. Use `deposit_tx_hash`/`sweep_tx_hash`, not the deprecated `tx_hash`.
15. After `claude mcp add` (or adding the BitPal MCP server to any client), restart the client / start a new session so the tools load.

## Docs

- [Quickstart](https://bitpal.io/docs/md/quickstart.md): One test payment end to end — payout wallet, test key, create a session (SDK and curl), pay on a testnet, receive and verify the webhook, go live.
- [SDK](https://bitpal.io/docs/md/sdk.md): `@bitpal/checkout` setup, amounts, payment options (`allowed_assets`), status polling, method reference.
- [Popup & headless](https://bitpal.io/docs/md/flows.md): Choosing redirect, popup or headless checkout; the popup `postMessage` contract; building your own payment UI with deposit addresses.
- [Payment links](https://bitpal.io/docs/md/links.md): Product → Price → Payment link, from the dashboard or the API.
- [x402](https://bitpal.io/docs/md/x402.md): Charge per API call with HTTP 402 and signed EIP-3009 authorizations.
- [Payment lifecycle](https://bitpal.io/docs/md/lifecycle.md): Session states, amount units, payment window and late payments, automatic refunds and refunding a completed payment from the console.
- [Webhooks](https://bitpal.io/docs/md/webhooks.md): Events, request format and headers, signature verification in Node, Python, Go, PHP and Java, event data, retries and the dead-letter queue.
- [API reference](https://bitpal.io/docs/md/api.md): Every public endpoint — method, path, auth, request fields and an example response — generated from the OpenAPI spec, plus the webhook event list.
- [OpenAPI 3.1 spec](https://bitpal.io/docs/openapi.json): Machine-readable spec of the public API (checkout sessions, products and prices, payment links, x402, webhook endpoints) including webhook events.
- [Errors](https://bitpal.io/docs/md/errors.md): Error response format, HTTP status codes, common error codes and fixes, safe retries.
- [Chains & contracts](https://bitpal.io/docs/md/reference.md): Supported networks and tokens, CAIP-2 ids, token decimals, deposit-address contract addresses, refund cases, test mode.
- [Overview](https://bitpal.io/docs/md/overview.md): Integration options, supported assets, how a payment flows.
- [Use with AI](https://bitpal.io/docs/md/ai.md): BitPal MCP server (remote https://mcp.bitpal.io/mcp or `npx -y @bitpal/mcp`), setup for Claude Code, Cursor, VS Code, Windsurf, Claude Desktop and Codex, and AGENTS.md rules.
- [All docs in one file](https://bitpal.io/docs/llms-full.txt)

## SDK

- [@bitpal/checkout on npm](https://www.npmjs.com/package/@bitpal/checkout): Create checkout sessions, issue deposit addresses, poll status, verify webhooks, x402 middleware.
- [SDK source on GitHub](https://github.com/superlabs-x/bitpal-checkout-sdk): MIT licensed.

## Supported assets and networks

Settlement is same-chain and same-token — no bridging or swapping.

- USDC — Base (`eip155:8453`), Arbitrum (`eip155:42161`), Solana (`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`)
- USDT — Tron (`tron:0x2b6653dc`), BNB Smart Chain (`eip155:56`), Solana
- JPYC — Polygon (`eip155:137`), Kaia (`eip155:8217`); priced in JPY, no FX conversion
- Token decimals: 6 for USDC and USDT on Tron and Solana; 18 for USDT on BNB Smart Chain and for JPYC.
- Testnet ids and contract addresses: [Chains & contracts](https://bitpal.io/docs/md/reference.md).

## Product

- [BitPal home](https://bitpal.io/): Merchant checkout overview.
- [BitPal for individuals](https://bitpal.io/personal): Send, request and receive stablecoins with an email address.
- [About BitPal](https://bitpal.io/about)

## Disambiguation

"BitPal" collides with unrelated projects. This file describes only bitpal.io, which is
**not** related to:

- `github.com/bitpal/bitpal` — an unrelated open-source self-hosted crypto payment processor.
- BitPay — an unrelated crypto payment company.
- bit-pal.io — an unrelated site and mobile app.
- bitpal.shop — an unrelated domain.
- Any token, coin or wallet named "BitPal", "BitPals" or "BITPAL".

## Optional

- [Terms of Service](https://bitpal.io/terms)
- [Privacy Policy](https://bitpal.io/privacy)

## Not for indexing

Session-specific, authenticated or non-production surfaces — do not crawl, index, cite or train on:

- `https://bitpal.io/pay/*`, `https://bitpal.io/plink/*`, `https://bitpal.io/r/*`, `https://bitpal.io/claim/*` — single-use payment pages.
- `https://bitpal.io/auth/*`, `https://bitpal.io/onboarding/*`, `https://bitpal.io/consumer/*`, `https://bitpal.io/producer/*` — signed-in application surfaces.
- `https://admin.bitpal.io` — internal administration console.
- `https://dev.bitpal.io` — non-production environment.