Skip to main content

Bitcoin wallet setup

BTC Testnet4 BTC Mainnet supported

Before you start​

  • A Manatee account with a Test API key
  • A dedicated Testnet4 wallet or account
  • A public HTTPS webhook URL
  • curl and a way to inspect incoming webhook requests
important

Submit only read-only wallet information. Never share a seed phrase, private key, or wallet password.

What you'll do​

Configure a receive source, create an exact BTC payment, send a synthetic webhook, and verify the normal pending → detected → confirmed lifecycle.

Step 1 — Create a dedicated Testnet4 wallet​

Create a new wallet account in a Testnet4-compatible wallet such as Sparrow. Keep the seed offline and record the first receiving address.

Expected result
Your wallet shows a Testnet4 receive address beginning with a test-network prefix such as tb1.

Step 2 — Export read-only receive information​

Prefer a ranged receive descriptor such as:

wpkh([FINGERPRINT/84h/1h/0h]tpub.../0/*)

An account-level tpub, upub, or vpub is also read-only, but choose the matching address type in the dashboard.

note

Public wallet data cannot spend funds, but it can reveal all receiving addresses and incoming history for that account. Use a dedicated payment account.

Step 3 — Configure Bitcoin in the dashboard​

Open Dashboard → Wallets → Test → Bitcoin, enter the descriptor or extended public key, verify the first derived address against your wallet, and save.

Expected result
The dashboard marks the BTC Test receive configuration as ready.

Step 4 — Create a test payment​

curl https://api.manatee-api.io/v1/btc/payments \
  -H "Authorization: Bearer <TEST_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-btc" \
  -d '{
    "amount_sats": 25000,
    "reference": "order-1042",
    "webhook_url": "https://shop.example/webhooks/manatee",
    "confirmations_required": 1
  }'

Store the returned id, address, amount_sats, network, and expires_at with the order.

Expected result
The response reports asset: "btc", network: "testnet", and status: "pending".

Step 5 — Verify webhook handling​

Use Dashboard → Webhooks → Send test event, or call the test-webhook endpoint documented in Webhooks. Verify the timestamp and HMAC signature against the raw request body before changing an order.

warning

Do not treat the browser redirect or customer screenshot as payment proof. Only a verified webhook or authenticated API lookup should update payment state.

Step 6 — Complete a Testnet4 transfer​

Send the exact amount to the returned address. Observe payment.detected, then payment.confirmed after the configured threshold.

Expected result
Your order stores each event ID once and reaches its paid state only after the confirmed event.

Failure and recovery​

  • invalid_receive_config: confirm descriptor checksum, network, derivation branch, and address type.
  • idempotency_conflict: reuse an idempotency key only with an identical request.
  • Missing webhook: query GET /v1/btc/payments/{id}, then inspect delivery attempts.
  • Wrong address: stop and compare the first dashboard-derived address with the wallet before using Mainnet.
Next steps
Read Going to production, then configure a separate Mainnet wallet and API key. Do not reuse Testnet wallet material.
Last updated on