API documentationBETA

The API works, but it is still in beta: we may change it and we do not yet promise support. Donation pages and alerts are not affected.

Who needs this. If you are a streamer and simply accept donations, you will not need the API, everything is in your account. This page is for people embedding payments into their own site or bot.

How it works

You create an invoice and we hand back an address and a link to the payment page. From there we watch the blockchain ourselves and, once the payment reaches the required number of confirmations, we send you a webhook. The money goes straight to your wallet: we never hold it and cannot delay it.

Authentication

The key is created in your account and shown once. Pass it in a header:

X-Api-Key: pk_xxxx.yyyy

The key grants the right to create invoices on your behalf. Keep it on your server. Do not put it in page code, in a mobile app or in a public repository. If it leaks, revoke it in your account and the old key stops working immediately.

Create an invoice

POST /v1/invoices
X-Api-Key: pk_xxxx.yyyy
Content-Type: application/json

{
  "currency": "BTC",
  "type": "order",
  "expected_amount": "150000",
  "order_id": "order-42"
}

Amounts are always strings in minimal units (satoshi for BTC, litoshi for LTC). Not floating point numbers: in most languages 0.1 + 0.2 is not 0.3, and with money that is unacceptable.

The Idempotency-Key header protects you from duplicates: repeating the same request returns the same invoice instead of creating a second one. A unique order_id does the same thing.

Webhook

Sent to your endpoint on the events invoice.confirmed, invoice.expired, invoice.underpaid and invoice.late_payment. Signed with HMAC-SHA256 using your secret.

Verify the signature against the raw request body, before parsing the JSON. If you parse first and re-serialise afterwards, the bytes change and the signature will not match. A working example with signature verification and replay protection lives in the repository: examples/webhook-receiver.mjs.

The pending status is deliberately never sent as a webhook: it is not money yet, only a transaction we noticed. For live updates there is an SSE stream on the payment page.

Full specification

A machine-readable OpenAPI 3.0 schema with every route, field and error code:

openapi.yaml - the specification file. You can open it in Swagger Editor, Postman or Insomnia, or feed it to a client generator for your language.

If you open that link in a browser you will see plain YAML text, and that is expected: it is a format for tools, not for reading by eye.