Frequently Asked Questions
General
What is the Manatee API?
Manatee API is a hosted service that lets businesses and developers accept Bitcoin payments without running their own infrastructure. You integrate via a simple REST API — we monitor the Bitcoin network, detect incoming payments, and notify your application via webhook.
Do I need to know how Bitcoin works?
No. You need a Bitcoin wallet to receive funds and a basic understanding of REST APIs. Everything else, including blockchain monitoring, confirmation tracking, address derivation, and webhook retries, is handled by the API.
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.
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.
Are testnet and mainnet payments separate?
Yes. API keys are scoped to one network. Use a testnet key for testnet/Testnet4 payments and a mainnet key only for real Bitcoin. Testnet coins have no real value, and testnet 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?
Yes — with one important nuance you should understand.
What an extended public key can do
An extended public key (xpub, ypub, zpub, tpub, upub, or vpub) is a purely public key. It is mathematically impossible to derive your private key or sign transactions from it. Anyone who holds it can generate your receiving addresses and watch incoming transactions, but they cannot move a single satoshi.
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
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-Signature header — an HMAC-SHA256 signature of the 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 raw request body. Verify it before JSON parsing or keep a raw-body copy in your web framework.
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?
No. Manatee receives the Bitcoin amount as amount_sats. If your shop prices products in EUR, USD, or another fiat currency, your application should calculate the Bitcoin amount before creating the payment and decide how long that quote stays valid.
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, convert fiat currencies, 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-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 paid plans while Manatee is in beta. Beta accounts can still have safety limits for confirmed payments, active webhook monitors, and API requests. If you are reaching a beta limit, contact us at [email protected].
How is pricing structured?
During beta, pricing 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.