◈ UTXO PAYMENTS
DEVELOPER DOCUMENTATION

One API.
Full visibility.

Use a scoped API key as a Bearer token. Production access is pending release approval. All examples target your local development API.

Create a payment

POST /v1/payments
Authorization: Bearer up_…
Idempotency-Key: unique-order-key-0001
Content-Type: application/json

{"walletId":"…","amountSats":"100000","reference":"ORDER-1"}

Use either amountSats or amountUsd. USD quotes require a rate source. Repeating the same key and body returns the same checkout; changing the body returns 409.

Webhook verification

Verify HMAC-SHA256 over the exact timestamp, a period, and the raw JSON body. Read X-Utxo-Timestamp and X-Utxo-Signature. Reject timestamps more than five minutes away, deduplicate X-Utxo-Event-Id, and fetch the payment before updating fulfillment.

HMAC_SHA256(secret, timestamp + "." + rawBody)

Settlement

Three confirmations are required. A payment.confirmed event concerns an incoming output; query GET /v1/payments/:id and check state.confirmed before fulfilling the order. Late payments and reorganizations can change payment status.

Version 0.1 boundaries

Native SegWit and single-key Taproot public descriptors are supported. Historical monitoring, live rates and production tax documents require further integration. See the repository release checklist before deployment.