Bitcoin Cash Testnet Quickstart

This guide creates a complete BCH testnet payment without giving Manatee access to private keys. Your customer pays an address controlled by your wallet; Manatee derives or validates that address, observes the transaction, and sends signed status events.

Test before using mainnet

BCH is available on testnet and mainnet. This guide deliberately uses testnet so you can validate wallet configuration, payment detection, confirmations, and webhooks without moving funds that have market value.

1. Prepare a BCH testnet wallet

Create a dedicated Bitcoin Cash testnet wallet or account. For automatic address derivation, export the account-level extended public key from:

m/44'/145'/0'

The testnet key must be a depth-three account tpub. Manatee derives fresh P2PKH receive addresses using /0/index. Never submit an xprv, tprv, seed phrase, or private key.

In the dashboard, open Wallet Settings, select Testnet, then Bitcoin Cash (BCH). Paste the account tpub and save it. Alternatively, enable manual destination addresses and let your backend supply a different BCH testnet address for each payment.

Manatee derives P2PKH addresses and returns BCH testnet addresses as prefixed, lowercase CashAddr beginning with bchtest:. Manual destination addresses may use supported P2PKH or P2SH CashAddr, including prefixless form, or their compatible legacy encoding; all are normalized. BTC SegWit addresses and BCH addresses from another network are rejected.

2. Set test variables

Use the same network-scoped testnet API key that you use for BTC testnet calls:

export MANATEE_API_URL="https://api.manatee-api.io"
export MANATEE_API_KEY="YOUR_TESTNET_API_KEY"
export WEBHOOK_URL="https://your-public-url.example/webhooks/bch"

The API key and webhook signing secret belong to the network, not to an individual asset. Rotating either one affects every enabled asset on that testnet key.

3. Test webhook delivery

Send a synthetic BCH event before moving testnet coins:

curl -sS -X POST "$MANATEE_API_URL/v1/webhooks/test" \
  -H "Authorization: Bearer $MANATEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "'"$WEBHOOK_URL"'",
    "asset": "bch"
  }'

Verify X-Manatee-Signature against the raw request body and store X-Manatee-Event-Id for idempotency. The signature format is identical for BTC and BCH.

4. Create a BCH payment

The v1 contract keeps the field name amount_sats; on a BCH route it means BCH satoshis.

curl -sS -X POST "$MANATEE_API_URL/v1/bch/payments" \
  -H "Authorization: Bearer $MANATEE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-bch-10042" \
  -d '{
    "amount_sats": 25000,
    "webhook_url": "'"$WEBHOOK_URL"'",
    "required_confirmations": 1,
    "expires_in": 3600,
    "reference": "order-bch-10042"
  }'

A successful response includes explicit asset and network information:

{
  "id": "pay_bch_abc123",
  "address": "bchtest:qr95sy3j9xwd2ap32xkykttr4cvcu7as4ytjg7p7mc",
  "amount_sats": 25000,
  "received_sats": 0,
  "status": "pending",
  "confirmations": 0,
  "required_confirmations": 1,
  "asset": "bch",
  "network": "testnet",
  "webhook_url": "https://your-public-url.example/webhooks/bch",
  "reference": "order-bch-10042",
  "created_at": "2026-08-12T10:00:00Z",
  "expires_at": "2026-08-12T11:00:00Z"
}

You can instead provide fiat_amount and fiat_currency, or send an allowed destination_address. Do not combine amount_sats with fiat input.

5. Pay and track the payment

Send BCH testnet coins to the exact returned address. Obtain test coins from a BCH testnet-compatible faucet or wallet; they have no real market value.

The expected lifecycle is:

1. pending: no qualifying transaction has been seen.
2. detected: a matching transaction was observed, but it has fewer than required_confirmations.
3. confirmed: the required confirmation threshold was reached.

detected is not final settlement. An unconfirmed transaction can still be replaced, dropped, conflicted, or affected by a chain reorganisation. Use payment.confirmed as the fulfillment trigger for ordinary production flows.

Retrieve the payment when you need to reconcile state:

curl -sS "$MANATEE_API_URL/v1/bch/payments/pay_bch_abc123" \
  -H "Authorization: Bearer $MANATEE_API_KEY"

BCH v1 routes

Method	Route	Purpose
POST	/v1/bch/payments	Create a payment
GET	/v1/bch/payments	List payments with pagination and filters
GET	/v1/bch/payments/{id}	Retrieve one payment
POST	/v1/bch/payments/{id}/cancel	Cancel a still-pending payment
GET	/v1/bch/payments/{id}/webhook-events	Inspect webhook delivery state

Supported BCH scope

• Account-xpub derivation produces P2PKH addresses. Manual destination addresses support P2PKH and P2SH.
• CashToken-aware addresses and token-bearing transaction outputs are not accepted as native BCH payments.
• Only pending payments can expire or be cancelled. A detected transaction continues through confirmation tracking.
• BCH and BTC routes enforce the asset/network scope. A request cannot use an address or payment belonging to another scope.

See Receive Descriptors and Extended Public Keys, Webhooks, and the generated API Reference for the complete contract.