Skip to main content

Bitcoin payment API

A non-custodial Bitcoin payment API for developers.

Create an on-chain Bitcoin payment, expose only the returned payment instructions to checkout, and drive order state from verifiable events.

Payments go directly to your wallet. Manatee handles monitoring and signed webhooks; your application controls checkout and refunds. Review the free beta access and usage limits before integrating.

Explore API referenceCreate test API key
POST /v1/btc/paymentsapplication/json
Requestcurl
curl -X POST /v1/btc/payments \
  -H "Authorization: Bearer $MANATEE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-10042" \
  -d '{
    "fiat_amount": "51.00",
    "fiat_currency": "EUR",
    "reference": "order-10042",
    "required_confirmations": 1
  }'
Response200 OK
{
  "id": "pay_abc123",
  "status": "pending",
  "amount_sats": 85000,
  "address": "tb1q...",
  "expires_at": "2026-07-20T18:30:00Z"
}

State model

Four states. One fulfilment decision.

Use payment state as an explicit contract instead of inferring success from a browser redirect.
  1. pending

    Instructions issued

    Show the exact address, satoshi amount, and expiry returned by the API.

  2. detected

    Transaction seen

    A matching transaction is visible, but has not reached your confirmation policy.

  3. confirmed

    Ready to fulfil

    The required confirmation threshold is met and a signed event is delivered.

  4. expired / cancelled

    Capacity released

    Closed payment attempts stop consuming webhook-enabled payment capacity.

Read the complete payment lifecycle

Integration contract

The production details are part of the interface.

Authentication, retries, event verification, and reconciliation are documented behavior, not assumptions hidden behind an SDK.
Authentication
Environment-scoped bearer keysKeep test and mainnet credentials separate and server-side.
Safe retries
Idempotency-Key per operationRepeat a timed-out create request without creating a second payment.
Order updates
HMAC-signed webhook eventsVerify the raw request body before changing fulfilment state.
Reconciliation
Explicit status transitionsHandle underpayment, expiry, cancellation, and late transactions deliberately.

Start without moving real Bitcoin

Run the full integration on Testnet4 first.

Environment-scoped Test API keySigned webhook verificationDashboard usage visibility
Create test API keyOpen Quickstart