Frequently Asked Questions
General
What is the Manatee API?
Manatee API monitors on-chain Bitcoin payments for a checkout backend. Your application creates a payment through the REST API; Manatee watches the assigned address and sends a webhook when the transaction is detected and confirmed.
What does "hosted in Europe" cover?
Manatee is built and operated from Europe, and its core application and API infrastructure is hosted in Europe. The public website and security edge use Cloudflare's globally distributed network, so an individual request may be processed at an edge location outside Europe. See Hosted in Europe and the Privacy Policy for the scope and provider details.
Do I need to know how Bitcoin works?
You do not need to run a Bitcoin node, but you should understand wallet backups, testnet versus mainnet, confirmation policy, and how your business handles refunds. The integration itself requires a receiving wallet and basic REST API knowledge. Manatee handles address monitoring, confirmation tracking, optional address derivation, and webhook retries.
Is this a custodial service?
No. Funds never pass through our systems. You provide the wallet address, or a read-only receive descriptor/extended-public-key setup, where payments should be received. Bitcoin goes directly there. We only process the payment events.
That also means Manatee cannot refund, reverse, freeze, or spend customer funds. Refunds, if your business offers them, are sent from your own wallet.
See Custodial vs. Non-Custodial Bitcoin Payments for a detailed comparison of fund control, wallet data, refunds, and merchant responsibilities.
Does Manatee support Lightning payments?
Not during the beta. The public beta is focused on on-chain Bitcoin payments with address monitoring, confirmations, and signed webhooks. Lightning support is not exposed in the public API right now.
Which cryptocurrencies does Manatee support?
Manatee currently supports on-chain Bitcoin (BTC). Bitcoin Cash (BCH) is planned as the next asset but is not available in the public API yet. Other cryptocurrencies are evaluated individually, with direct settlement to a merchant-controlled wallet and a non-custodial integration as core requirements. See Supported Assets and Non-Custodial Scope for the complete rationale and current roadmap status.
Are testnet and mainnet payments separate?
Yes. API keys are scoped to one network. Manatee uses Bitcoin Testnet4 for testing and reports it as testnet in the API. Use a mainnet key only for real Bitcoin. Testnet coins have no real value, and Testnet4 addresses cannot be used for mainnet BTC.
Wallet Addresses & Receive Descriptors
What is the difference between a wallet address and a receive descriptor?
A wallet address (e.g. bc1q...) is one concrete Bitcoin receiving address. If you reuse the same address for many payment requests, it is technically functional but not ideal for privacy or accounting because it becomes obvious on the blockchain that multiple payments went to the same recipient.
A receive descriptor is read-only wallet data that tells Bitcoin Core how to derive receiving addresses for one wallet account. It often contains an extended public key internally. From that setup, the API can derive a fresh, unique Bitcoin address for every payment request automatically. This means:
- Each invoice gets its own address
- Payments are unambiguously linked to a specific order or customer
- Your privacy is significantly improved on-chain
How do I get the wallet data for address derivation?
Most Bitcoin wallets (Sparrow, Electrum, BlueWallet, Ledger, Trezor) expose account-level public wallet data under "Wallet Details", "Account Info", or "Advanced" settings. Depending on the wallet and network, you may see a descriptor or an extended public key.
On mainnet, extended public keys commonly start with xpub, ypub, or zpub. In Sparrow Wallet's Testnet4 mode, the same concept can appear as tpub, upub, or vpub. For example, a native SegWit testnet/Testnet4 wallet may show vpub where a comparable mainnet wallet would show zpub.
Important: This data is read-only — nobody can spend your Bitcoin with it. However, it can expose the transaction history for that wallet account. Treat it as sensitive and never share it publicly.
For production, use a dedicated wallet account for Manatee payments instead of exporting public wallet data from a personal or treasury wallet.
Is it safe to share my extended public key with Manatee API?
An extended public key is appropriate for read-only address derivation, but it should still be handled as sensitive wallet metadata.
What an extended public key can do
An extended public key (xpub, ypub, zpub, tpub, upub, or vpub) on its own cannot sign transactions or spend Bitcoin. Anyone who holds it can derive receiving addresses and observe incoming transactions for that account. Do not expose it publicly, and never combine it with exported child private keys or other private wallet material.
This is precisely why descriptor/extended-public-key-based payment infrastructure is viable: Manatee API uses read-only wallet data to derive a fresh address per payment request. We never hold private keys, seed phrases, or any credential that could authorize a spend.
The privacy tradeoff
The one real consideration is on-chain privacy. Because an extended public key encodes the relationship between all addresses derived from it, anyone who holds it can:
- See all receiving addresses associated with that account
- Observe incoming transaction history for those addresses
This is an inherent property of HD wallets (defined in BIP-32) and applies to any service that uses extended-public-key-based address derivation — not just Manatee API.
Practical recommendation
Use a dedicated wallet or account exclusively for API payments, separate from your personal or treasury holdings. This limits the on-chain data exposed to the payment account only, which is normal practice for any business accepting Bitcoin.
References
Which wallet export format should I use?
Manatee's backend stores a Bitcoin Core receive descriptor for address derivation. If your wallet can export a ranged receive descriptor, that is the cleanest option.
Some wallets export account public keys instead, commonly shown as xpub, ypub, or zpub on mainnet and tpub, upub, or vpub on testnet/Testnet4. The y/u and z/v prefixes usually encode the address style your wallet expects. Plain xpub/tpub keys are generic BIP32 public keys, so the address type must come from the descriptor or from the address type you choose in the dashboard.
| Prefix | Network | Address style |
|---|---|---|
xpub / tpub | Mainnet / testnet | Generic extended public key; address style depends on descriptor or selected address type |
ypub / upub | Mainnet / testnet | Wrapped SegWit, usually 3... or 2... addresses |
zpub / vpub | Mainnet / testnet | Native SegWit, usually bc1q... or tb1... addresses |
Native SegWit addresses (bc1q... on mainnet, tb1... on testnet) are recommended for lower fees. In Sparrow Testnet4, seeing vpub for a native SegWit wallet is normal. If Sparrow shows a full receive descriptor such as wpkh(...tpub.../0/*), use that descriptor; it is more explicit than copying only the tpub.
If you are unsure which export to use, create a dedicated payment wallet/account and ask support to configure the matching receive descriptor for your API key.
Can I reuse the same Bitcoin address?
Manatee can monitor a customer-provided destination_address, but a single address cannot have two active payments at the same time. If another pending or detected payment already uses that address, payment creation returns a conflict.
For production checkout flows, use a receive descriptor or extended public key so Manatee can derive a fresh address for each payment. This is better for privacy, accounting, and order reconciliation.
Payments & Webhooks
Why does payment creation return plan_limit_exceeded?
The active_webhooks limit protects the number of concurrent payments that Manatee monitors with a webhook_url. It is counted separately for each API key. A payment occupies one slot while its status is pending or detected, and releases that slot when it becomes confirmed, expired, or cancelled.
Beta accounts can have up to three concurrent payments with webhooks per API key. A failed webhook delivery is different: delivery retries do not change the payment status and do not occupy an additional slot.
When all slots are in use, payment creation returns HTTP 402 with the current usage and allowance:
{
"error": "plan_limit_exceeded",
"limit": "active_webhooks",
"plan": "beta",
"current": 3,
"allowed": 3,
"message": "This API key already has 3 active payments with webhooks. A slot is released when a payment becomes confirmed, expired, or cancelled."
}
A pending payment can be cancelled manually if the related checkout or order was abandoned:
curl -sS -X POST "$MANATEE_API_URL/v1/btc/payments/pay_abc123/cancel" \
-H "Authorization: Bearer $MANATEE_API_KEY"
A detected payment cannot be cancelled because a matching Bitcoin transaction has already been seen. Manatee continues tracking it until it reaches the required confirmation count.
How does payment detection work?
When a payment is created, we begin monitoring the Bitcoin mempool and blockchain for incoming transactions to the specified address. Your webhook is notified at two stages:
payment.detected— transaction seen in the mempool (unconfirmed, typically within seconds)payment.confirmed— transaction has reached the required number of block confirmations
When should I expect webhook delivery?
Payment detection is event-driven through Bitcoin Core ZMQ. In normal operation, payment.detected is queued shortly after the transaction appears in the mempool.
Webhook events are processed by an internal queue that is checked about every 500 ms. Most successful webhook deliveries should arrive within a few seconds after detection or confirmation.
If your endpoint is unavailable or returns a non-2xx response, Manatee retries delivery with this schedule:
| Attempt | Delay before retry |
|---|---|
| 1 | 1 minute |
| 2 | 5 minutes |
| 3 | 30 minutes |
| 4 | 2 hours |
| 5 | 6 hours |
| 6+ | 24 hours |
Webhook delivery is attempted up to 10 times.
Pending payments are checked for expiry every 30 seconds. Only pending payments expire. If a transaction was already detected before expires_at, Manatee continues tracking its confirmations instead of changing the payment to expired.
What happens if the customer sends slightly too little?
By default, payments require the full amount_sats. When creating a payment, you can set underpayment_tolerance_ppm to allow a small downward tolerance. The value is parts per million: 1000 means 0.1%.
Payments below the accepted minimum remain pending until they expire.
How many confirmations should I require?
required_confirmations can be set from 1 to 6 and defaults to 3. Lower values are faster but carry more settlement risk. Higher values are slower but safer for higher-value orders.
For testing and low-risk digital checkout flows, 1 confirmation is usually enough. For production, choose the threshold based on the value of the order and your risk policy.
What happens if a payment is never made?
Once expired, the status changes to expired. If the payment used descriptor-based address derivation, Manatee does not derive that same address for a later payment. Expiry only applies while the payment is still pending; if a matching transaction was already detected, Manatee continues tracking confirmations instead of expiring it.
Can I cancel a payment?
Yes. You can cancel a payment while it is still pending by calling POST /v1/btc/payments/{id}/cancel. A detected or confirmed payment cannot be cancelled, because Manatee has already seen a matching Bitcoin transaction.
How do I verify that a webhook came from Manatee API?
Every webhook request includes an X-Manatee-Signature header, an X-Manatee-Timestamp header, and an X-Manatee-Event-Id header. The signature is an HMAC-SHA256 value over timestamp + "." + raw request body using your webhook secret. Always verify this signature before processing a payment event.
You can find the webhook signing secret in the dashboard under Wallet & API-Key. Each API key has its own secret, so use the secret for the same network and API key that created the payment.
The signature is calculated over the timestamp and raw request body. Verify it before JSON parsing or keep a raw-body copy in your web framework. Reject requests whose timestamp is outside your allowed clock-skew window; five minutes is a good default.
See Verify Webhook Signatures for a complete example.
Can I test without real Bitcoin?
Yes. You can use POST /v1/webhooks/test to send a synthetic payment.confirmed event to your webhook endpoint without creating a Bitcoin transaction.
For a full end-to-end payment test, use your Testnet API key and send testnet Bitcoin to the address returned by POST /v1/btc/payments.
Does Manatee calculate fiat prices?
For supported currencies, yes. You can create a payment with fiat_amount and fiat_currency; Manatee returns the fixed amount_sats the customer should pay plus quote metadata such as exchange rate, timestamp, and pricing source. Pricing providers, fallback providers, and provider API keys are configured server-side by Manatee. You can also keep doing your own conversion and send amount_sats directly. Manatee does not custody fiat, exchange funds, or handle refunds.
Should I use an idempotency key when creating payments?
Yes. Send an Idempotency-Key header when creating a payment, especially if your backend may retry after a timeout. Use a stable value tied to your order, such as order-123-create-payment, so retries do not accidentally create multiple payment requests.
What does the customer see during checkout?
Most integrations show the customer the Bitcoin amount, the receiving address, a QR code, and the expiry time. Your backend creates the Manatee payment, displays the returned address to the customer, and waits for payment.confirmed before fulfilling the order.
What does Manatee not do?
Manatee does not provide a wallet, custody funds, hold fiat balances, exchange funds, send refunds, or move Bitcoin on your behalf. It monitors addresses, tracks payment status, and sends signed webhook events to your application.
What should my backend do when it receives a webhook?
Verify the signature and store the X-Manatee-Event-Id. Then update your order using the payment_id from the webhook and the payment_id -> order_id mapping you saved when creating the payment. If needed, fetch the payment by ID to read its reference. Webhook delivery is at-least-once, so your handler should safely ignore an event ID it has already processed.
For most checkout flows, mark the order as paid on payment.confirmed. You can show payment.detected to the customer as "payment seen" or "waiting for confirmations".
Does the webhook payload include my reference?
No. Webhook payloads contain the Manatee payment_id, transaction data, amount data, confirmations, and the webhook URL. Store the payment_id returned by POST /v1/btc/payments next to your own order ID. If you need the original reference, fetch the payment by ID.
Pricing & Plans
Beta
There are no costs and no purchasable upgrades while Manatee is in beta. Accounts still have a technical plan assignment and safety limits for confirmed payments, active webhook monitors, and API requests; the dashboard shows the limits that apply to your account. See Beta Pricing and Limits for the current standard allowances and active-monitor behavior. If you are reaching a beta limit, contact us at [email protected].
How is pricing structured?
During beta, billing is not active. The planned model is monthly flat-rate billing with plan-specific usage limits. Final production plan details will be published before paid plans launch.
Is there a free plan?
Beta access currently covers development and low-volume testing. Production plan details will be published before paid plans launch.
Is KYC or business verification required?
No KYC document check is required for beta testing. Account registration can still require basic contact and account details. If paid production plans require business verification later, the requirements will be documented before those plans launch.