Skip to main content
API docs by Redocly

Manatee On-Chain Payment API Reference (0.4.0)

Download OpenAPI specification:Download

License: LicenseRef-Proprietary

Accept non-custodial BTC and BCH payments with confirmation tracking, network-scoped API keys, and signed webhooks.

payments

Create and query BTC on-chain payments

Create a new payment

Creates a payment and returns a Bitcoin address. Provide exactly one amount mode: amount_sats, or fiat_amount with fiat_currency. Fiat-created payments return the converted amount_sats and quote metadata.

Authorizations:
bearerAuth
header Parameters
Idempotency-Key
string

Idempotency key for safe retries

Request Body schema: application/json
required
One of
amount_sats
required
integer >= 1

Amount in satoshis. Provide either amount_sats or fiat_amount with fiat_currency, but not both.

fiat_amount
string^[0-9]+(\.[0-9]+)?$

Fiat amount to convert into a fixed satoshi amount for this payment. Must be provided together with fiat_currency and cannot be combined with amount_sats.

fiat_currency
string

Fiat currency code used for fiat_amount. Supported currencies depend on the server-side pricing provider configuration.

underpayment_tolerance_ppm
integer [ 0 .. 10000 ]
Default: 0

Optional downward payment tolerance in parts per million. 1000 ppm allows a 0.1% underpayment.

webhook_url
string <uri>

Optional webhook endpoint URL. By default, localhost, private, link-local, and carrier-grade NAT addresses are rejected. Local development and integration-test environments can explicitly allow them with ALLOW_LOCAL_WEBHOOK_URLS=true. The endpoint must accept server-to-server HTTP requests; bypass Cloudflare/WAF/bot challenges for the webhook path and verify requests with the X-Manatee-Signature HMAC header.

destination_address
string

Optional custom destination address. If omitted, the API derives an address from the API key's receive descriptor. If provided, the API key must allow customer-provided addresses, the address must match the key network, and the same address cannot already have another active payment.

required_confirmations
integer [ 1 .. 6 ]
Default: 3

Number of block confirmations required before the payment is confirmed. Defaults to 3.

expires_in
integer [ 300 .. 86400 ]
Default: 3600

Payment expiry in seconds. Only pending payments expire. Defaults to 3600 (1 hour).

reference
string

Optional external reference ID for reconciliation (e.g. order ID)

Responses

Request samples

Content type
application/json
{
  • "amount_sats": 10000,
  • "fiat_amount": "51.00",
  • "fiat_currency": "EUR",
  • "underpayment_tolerance_ppm": 0,
  • "webhook_url": "https://yourapp.com/webhooks/btc",
  • "destination_address": "string",
  • "required_confirmations": 1,
  • "expires_in": 900,
  • "reference": "order-123"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "address": "string",
  • "txid": "string",
  • "amount_sats": 1,
  • "fiat_amount": "51.00",
  • "fiat_currency": "EUR",
  • "exchange_rate": "60000",
  • "exchange_rate_timestamp": "2019-08-24T14:15:22Z",
  • "pricing_source": "coinbase",
  • "underpayment_tolerance_ppm": 10000,
  • "received_sats": 0,
  • "status": "pending",
  • "confirmations": 0,
  • "required_confirmations": 1,
  • "webhook_url": "http://example.com",
  • "asset": "btc",
  • "network": "testnet",
  • "created_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "reference": "string"
}

Get List of payments by time range

Authorizations:
bearerAuth
query Parameters
from
required
integer
Examples: from=1744675200

Start of time range

to
required
integer
Examples: to=1744675900

End of time range

filter
string
Default: "all"
Enum: "all" "verified" "unverified"

Filter by confirmation status.

  • all: all payments
  • verified: only confirmed payments
  • unverified: payments not yet confirmed (pending, detected, expired, cancelled)
limit
integer [ 1 .. 100 ]
Default: 50

Maximum number of payments to return

offset
integer >= 0
Default: 0

Number of payments to skip

Responses

Request samples 

curl -X GET "https://api.manatee-api.io/v1/btc/payments?from=1744675200&to=1744675900&filter=all&limit=50&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Get a payment by ID

Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Request samples 

curl -X GET "https://api.manatee-api.io/v1/btc/payments/abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response samples

Content type
application/json
{
  • "id": "string",
  • "address": "string",
  • "txid": "string",
  • "amount_sats": 1,
  • "fiat_amount": "51.00",
  • "fiat_currency": "EUR",
  • "exchange_rate": "60000",
  • "exchange_rate_timestamp": "2019-08-24T14:15:22Z",
  • "pricing_source": "coinbase",
  • "underpayment_tolerance_ppm": 10000,
  • "received_sats": 0,
  • "status": "pending",
  • "confirmations": 0,
  • "required_confirmations": 1,
  • "webhook_url": "http://example.com",
  • "asset": "btc",
  • "network": "testnet",
  • "created_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "reference": "string"
}

Cancel a pending payment

Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Request samples 

curl -X POST "https://api.manatee-api.io/v1/btc/payments/abc123/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response samples

Content type
application/json
{
  • "id": "string",
  • "address": "string",
  • "txid": "string",
  • "amount_sats": 1,
  • "fiat_amount": "51.00",
  • "fiat_currency": "EUR",
  • "exchange_rate": "60000",
  • "exchange_rate_timestamp": "2019-08-24T14:15:22Z",
  • "pricing_source": "coinbase",
  • "underpayment_tolerance_ppm": 10000,
  • "received_sats": 0,
  • "status": "pending",
  • "confirmations": 0,
  • "required_confirmations": 1,
  • "webhook_url": "http://example.com",
  • "asset": "btc",
  • "network": "testnet",
  • "created_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "reference": "string"
}

bch-payments

Create and query BCH on-chain payments

Create a new BCH payment

Creates a BCH payment and returns a canonical, network-specific CashAddr. Provide exactly one amount mode: amount_sats, or fiat_amount with fiat_currency. Fiat-created payments return the converted amount_sats and quote metadata. If destination_address is omitted, a BCH receive xpub must be configured for the API key.

Authorizations:
bearerAuth
header Parameters
Idempotency-Key
string

Idempotency key for safe retries. Idempotency is scoped to the API key, HTTP method, and BCH route.

Request Body schema: application/json
required
One of
amount_sats
required
integer >= 1

Amount in BCH satoshis. Provide either amount_sats or fiat_amount with fiat_currency, but not both.

fiat_amount
string^[0-9]+(\.[0-9]+)?$

Fiat amount to convert into a fixed BCH satoshi amount. Must be provided together with fiat_currency and cannot be combined with amount_sats.

fiat_currency
string

Fiat currency code used for fiat_amount. Supported BCH/fiat pairs depend on the server-side pricing provider configuration.

underpayment_tolerance_ppm
integer [ 0 .. 10000 ]
Default: 0

Optional downward payment tolerance in parts per million. 1000 ppm allows a 0.1% underpayment.

webhook_url
string <uri>

Optional webhook endpoint that receives signed payment.detected and payment.confirmed events.

destination_address
string

Optional BCH destination address. Prefixed, prefixless, and supported legacy addresses are normalized to canonical CashAddr. The API key must allow customer-provided addresses.

required_confirmations
integer [ 1 .. 6 ]
Default: 3

Number of confirmations required before the payment is confirmed. Defaults to the configured BCH confirmation target.

expires_in
integer [ 300 .. 86400 ]
Default: 3600

Payment expiry in seconds. Only pending payments expire.

reference
string

Optional external reference ID for reconciliation.

Responses

Request samples

Content type
application/json
Example
{}

Response samples

Content type
application/json
{
  • "id": "payment_bch_123",
  • "address": "bchreg:qr95sy3j9xwd2ap32xkykttr4cvcu7as4y3w7lzdc7",
  • "amount_sats": 10000000,
  • "fiat_amount": "45.00",
  • "fiat_currency": "EUR",
  • "exchange_rate": "450",
  • "exchange_rate_timestamp": "2026-08-05T12:00:00Z",
  • "pricing_source": "coinbase",
  • "underpayment_tolerance_ppm": 0,
  • "status": "pending",
  • "confirmations": 0,
  • "required_confirmations": 2,
  • "asset": "bch",
  • "network": "regtest",
  • "reference": "order-bch-123",
  • "created_at": "2026-08-05T12:00:00Z",
  • "expires_at": "2026-08-05T13:00:00Z"
}

List BCH payments by time range

Authorizations:
bearerAuth
query Parameters
from
required
integer
Examples: from=1744675200

Start of time range as a Unix timestamp

to
required
integer
Examples: to=1744675900

End of time range as a Unix timestamp

filter
string
Default: "all"
Enum: "all" "verified" "unverified"

Filter BCH payments by confirmation status

limit
integer [ 1 .. 100 ]
Default: 50

Maximum number of payments to return

offset
integer >= 0
Default: 0

Number of payments to skip

Responses

Request samples 

curl -X GET "https://api.manatee-api.io/v1/bch/payments?from=1744675200&to=1744675900&filter=all&limit=50&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Get a BCH payment by ID

Authorizations:
bearerAuth
path Parameters
id
required
string

BCH payment ID

Responses

Request samples 

curl -X GET "https://api.manatee-api.io/v1/bch/payments/payment_bch_123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response samples

Content type
application/json
{
  • "id": "string",
  • "address": "string",
  • "txid": "string",
  • "amount_sats": 1,
  • "fiat_amount": "51.00",
  • "fiat_currency": "EUR",
  • "exchange_rate": "60000",
  • "exchange_rate_timestamp": "2019-08-24T14:15:22Z",
  • "pricing_source": "coinbase",
  • "underpayment_tolerance_ppm": 10000,
  • "received_sats": 0,
  • "status": "pending",
  • "confirmations": 0,
  • "required_confirmations": 1,
  • "webhook_url": "http://example.com",
  • "asset": "btc",
  • "network": "testnet",
  • "created_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "reference": "string"
}

Cancel a pending BCH payment

Authorizations:
bearerAuth
path Parameters
id
required
string

BCH payment ID

Responses

Request samples 

curl -X POST "https://api.manatee-api.io/v1/bch/payments/payment_bch_123/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response samples

Content type
application/json
{
  • "id": "string",
  • "address": "string",
  • "txid": "string",
  • "amount_sats": 1,
  • "fiat_amount": "51.00",
  • "fiat_currency": "EUR",
  • "exchange_rate": "60000",
  • "exchange_rate_timestamp": "2019-08-24T14:15:22Z",
  • "pricing_source": "coinbase",
  • "underpayment_tolerance_ppm": 10000,
  • "received_sats": 0,
  • "status": "pending",
  • "confirmations": 0,
  • "required_confirmations": 1,
  • "webhook_url": "http://example.com",
  • "asset": "btc",
  • "network": "testnet",
  • "created_at": "2019-08-24T14:15:22Z",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "reference": "string"
}

usage

Account usage and plan limits

Get current account usage

Returns current monthly usage, plan-counted mainnet usage, plan limits, and counters grouped by network and asset for the account associated with the authenticated API key.

Authorizations:
bearerAuth

Responses

Request samples 

curl -X GET "https://api.manatee-api.io/v1/usage" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response samples

Content type
application/json
{
  • "period": {
    },
  • "plan": "beta",
  • "usage": {
    },
  • "plan_usage": {
    },
  • "limits": {
    },
  • "networks": {
    },
  • "scopes": {
    },
  • "active_payments_with_webhook": {
    },
  • "active_payments_by_scope": {
    }
}

webhooks

Outbound HTTP callbacks sent to your server

Payment detected Webhook

Sent to the webhook_url specified during payment creation once an incoming transaction is detected in the mempool.

Signature verification

Every request includes an HMAC-SHA256 signature in the X-Manatee-Signature header. Verify it by computing HMAC-SHA256(secret, X-Manatee-Timestamp + "." + raw_body) using your webhook signing secret and comparing the result to the sha256=<hex> value in the header. Reject requests whose X-Manatee-Timestamp is outside your allowed clock-skew window; five minutes is a good default.

header Parameters
X-Manatee-Event-Id
required
string

Unique identifier for this event delivery

X-Manatee-Event-Type
required
string
Examples: payment.detected

Event type

X-Manatee-Timestamp
required
string
Examples: 1710000000

Unix timestamp in seconds used in signature verification

X-Manatee-Signature
required
string
Examples: sha256=a3f1...

HMAC-SHA256 signature of X-Manatee-Timestamp + "." + raw request body

X-Event-ID
string
Deprecated

Legacy event ID header sent temporarily for backwards compatibility

X-Event-Type
string
Deprecated
Examples: payment.detected

Legacy event type header sent temporarily for backwards compatibility

X-Signature
string
Deprecated
Examples: sha256=a3f1...

Legacy body-only HMAC signature sent temporarily for backwards compatibility

Request Body schema: application/json
required
version
required
string

Webhook payload schema version

type
required
string
Enum: "payment.detected" "payment.confirmed"

Event type

required
object (PaymentWebhookData)

Responses

Request samples

Content type
application/json
{
  • "version": "1",
  • "type": "payment.detected",
  • "data": {
    }
}

Payment confirmed Webhook

Sent to the webhook_url specified during payment creation once the payment reaches the required number of confirmations.

Signature verification

Every request includes an HMAC-SHA256 signature in the X-Manatee-Signature header. Verify it by computing HMAC-SHA256(secret, X-Manatee-Timestamp + "." + raw_body) using your webhook signing secret and comparing the result to the sha256=<hex> value in the header. Reject requests whose X-Manatee-Timestamp is outside your allowed clock-skew window; five minutes is a good default.

header Parameters
X-Manatee-Event-Id
required
string

Unique identifier for this event delivery

X-Manatee-Event-Type
required
string
Examples: payment.confirmed

Event type

X-Manatee-Timestamp
required
string
Examples: 1710000000

Unix timestamp in seconds used in signature verification

X-Manatee-Signature
required
string
Examples: sha256=a3f1...

HMAC-SHA256 signature of X-Manatee-Timestamp + "." + raw request body

X-Event-ID
string
Deprecated

Legacy event ID header sent temporarily for backwards compatibility

X-Event-Type
string
Deprecated
Examples: payment.confirmed

Legacy event type header sent temporarily for backwards compatibility

X-Signature
string
Deprecated
Examples: sha256=a3f1...

Legacy body-only HMAC signature sent temporarily for backwards compatibility

Request Body schema: application/json
required
version
required
string

Webhook payload schema version

type
required
string
Enum: "payment.detected" "payment.confirmed"

Event type

required
object (PaymentWebhookData)

Responses

Request samples

Content type
application/json
{
  • "version": "1",
  • "type": "payment.detected",
  • "data": {
    }
}

List webhook delivery events for a payment

Returns stored webhook delivery attempts for a payment that belongs to the authenticated API key.

Authorizations:
bearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List webhook delivery events for a BCH payment

Returns stored webhook delivery attempts for a BCH payment that belongs to the authenticated API key.

Authorizations:
bearerAuth
path Parameters
id
required
string

BCH payment ID

Responses

Request samples 

curl -X GET "https://api.manatee-api.io/v1/bch/payments/payment_bch_123/webhook-events" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response samples

Content type
application/json
[
  • {
    }
]

Send a test webhook

Sends a synthetic payment.confirmed webhook event to the provided webhook_url. Set asset to btc or bch; it defaults to btc. The event network is taken from the authenticated network-scoped API key and cannot be overridden.

Use this endpoint to verify endpoint reachability, request headers, payload parsing, and signature validation without creating an on-chain transaction. The test event is delivered immediately and is not stored as a payment or webhook event.

If the webhook URL is protected by Cloudflare, a WAF, bot protection, captchas, browser challenges, or login redirects, bypass those protections for the webhook path and verify authenticity with the X-Manatee-Signature HMAC header instead.

Authorizations:
bearerAuth
Request Body schema: application/json
required
webhook_url
required
string <uri>

Public webhook endpoint URL that should receive the synthetic test event. The endpoint must accept server-to-server HTTP requests and must not require browser challenges, captchas, or login redirects.

asset
string
Default: "btc"
Enum: "btc" "bch"

Asset represented by the synthetic payment event. Omit this field to test the backwards-compatible BTC payload.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "event_id": "string",
  • "event_type": "payment.confirmed",
  • "asset": "btc",
  • "network": "mainnet",
  • "status": 200,
  • "delivered": true
}