Custodial vs. Non-Custodial Bitcoin Payments
The difference between a custodial and a non-custodial payment service is primarily about control: who holds the private keys, who can move the funds, and whether customer payments first enter an account controlled by the service provider.
Manatee is designed as non-custodial payment-monitoring infrastructure. A customer pays a Bitcoin address controlled by the merchant. Manatee observes the transaction, tracks its confirmation status, and sends signed webhook events, but cannot spend or return the Bitcoin.
The short comparison
| Question | Custodial service | Non-custodial Manatee integration |
|---|---|---|
| Where does the payment arrive? | A wallet or internal balance controlled by the provider | A wallet address controlled by the merchant |
| Who controls the private keys? | The provider, fully or as part of the service | The merchant or the merchant's chosen wallet provider |
| Who can move the funds? | The provider can generally process withdrawals or transfers | Manatee cannot move the funds |
| Who sends refunds? | The provider may offer a refund or payout workflow | The merchant sends refunds from their own wallet |
| Is there a Manatee balance to withdraw? | Not applicable | No; Manatee does not maintain withdrawable balances |
| What wallet data does Manatee need? | A custodial provider manages the wallet itself | A destination address or read-only receive data, never a seed phrase or private key |
| What happens if the monitoring service is unavailable? | Access to an internal balance may depend on the provider | Funds still arrive in the merchant wallet, but status updates and webhooks may be delayed |
How a custodial payment flow works
In a custodial flow, the provider controls the wallet infrastructure that receives or holds funds on behalf of its users. The provider may credit an internal account balance and later allow the merchant to withdraw, convert, or transfer that balance.
This model can simplify wallet operations, but it means the provider has some degree of control over access to the funds. Availability, withdrawal rules, account restrictions, and the security of the provider's signing infrastructure become part of the merchant's payment risk.
Custodial services can be appropriate for some businesses. They are simply a different product model from Manatee.
How the Manatee flow remains non-custodial
The payment destination belongs to the merchant before a payment request is created. Manatee can work with either:
- A concrete destination address supplied by the merchant
- Read-only wallet information used to derive fresh receiving addresses
The customer then sends Bitcoin directly to that destination. Manatee's nodes observe the Bitcoin network and associate the transaction with the payment request. No intermediate Manatee wallet, pooled receiving account, or later payout is involved.
The API key and webhook signing secret authenticate API and webhook communication. They are not Bitcoin wallet keys and cannot authorize a blockchain transaction.
Read-only wallet data is not a private key
A receive descriptor or extended public key can allow Manatee to derive receiving addresses without gaining spending authority. It cannot sign transactions or reveal the wallet's private keys.
Read-only does not mean public. An extended public key can reveal the addresses and incoming transaction history associated with a wallet account. Treat it as sensitive metadata and use a dedicated business wallet account for payment activity rather than a personal or treasury account.
Never provide Manatee, a plugin, or support personnel with:
- A seed phrase
- A private key
- A wallet backup containing private keys
- A hardware-wallet recovery phrase
- A credential that can sign or approve a transaction
See Receive Descriptors and Extended Public Keys for the supported read-only configuration.
Responsibilities in a non-custodial integration
Manatee is responsible for
- Creating and tracking payment records
- Monitoring destination addresses
- Detecting matching transactions
- Tracking confirmations
- Expiring unpaid pending requests
- Signing and retrying webhook deliveries
- Providing payment status through the API
The merchant is responsible for
- Wallet creation, backups, and recovery procedures
- Protecting private keys and seed phrases
- Verifying that configured receive data belongs to the intended wallet
- Choosing an appropriate confirmation threshold
- Reconciling payments with orders and accounting records
- Deciding when an order is fulfilled
- Sending refunds from the merchant wallet
- Handling overpayments, underpayments, and customer support
Manatee cannot recover a payment sent to an incorrect address, reverse a confirmed transaction, or refund a customer. Those limitations follow from the same separation that prevents Manatee from taking custody.
How to verify the custody boundary
Before using a mainnet API key, verify the complete flow on testnet:
- Configure an address, descriptor, or extended public key from a dedicated merchant wallet account.
- Create a payment and compare the returned address with the next expected receive address in that wallet.
- Send a test payment and verify it independently in the merchant wallet.
- Confirm that the Manatee dashboard shows payment status but offers no transfer or withdrawal function.
- Confirm that refunds are created and signed only in the merchant's wallet.
If an integration asks for spending credentials or directs customer funds to an address that the merchant does not control, stop and verify the configuration before accepting payments.
What non-custodial does not mean
Non-custodial describes control over funds. It does not mean that:
- Wallet security and backups are handled automatically
- Transactions can be reversed
- Every detected transaction is already final
- Webhook verification can be skipped
- No operational or personal data is processed
- The integration is exempt from laws or accounting obligations that apply to the merchant
Manatee's non-custodial design is a technical and operational boundary, not a legal classification of every merchant or use case. Businesses remain responsible for evaluating the rules that apply to their activities and location.