Skip to main content

BCH Release and Migration Notes

The BCH integration extends the existing v1 API without replacing BTC routes or issuing separate asset-specific credentials. Bitcoin Cash payments and receive-wallet configuration are available on testnet and mainnet.

Existing BTC integrations​

Existing BTC records are backfilled automatically and /v1/btc behavior remains compatible. No wallet re-import or API-key replacement is required.

Review these additive response changes:

  • Payment responses explicitly contain asset and network.
  • Payment webhooks explicitly contain asset and network.
  • Dashboard usage is grouped by network and asset.
  • API-key overviews expose available scopes, but never raw credentials or receive descriptors.

Webhook event types, headers, retry behavior, and signature calculation are unchanged. Consumers that reject unknown JSON fields must allow the new fields before deployment.

Adding BCH to an API key​

Use the existing API key and webhook secret for the network you want to accept. Add a separate BCH receive configuration in the dashboard using an account-level extended public key from m/44'/145'/0'. Use an xpub for mainnet and a tpub for testnet. Manatee derives /0/index P2PKH addresses and returns canonical bitcoincash: or bchtest: CashAddr for the selected network.

Use /v1/bch/payments instead of /v1/btc/payments. Keep separate payment IDs and order metadata, and route webhook processing by both asset and network. The legacy field name amount_sats represents BCH satoshis on BCH routes.

BTC and BCH payments on one network key share active-webhook capacity. Confirmed mainnet usage is account-wide across assets; testnet and regtest do not consume that monthly production allowance.

Database migration behavior​

Migrations 00028 through 00031:

  • add and backfill the payment asset field with btc;
  • add script_pub_key for format-independent output matching;
  • move receive configuration into per-asset rows while preserving existing BTC settings;
  • add asset/network indexes and usage dimensions.

Apply migrations through the normal API startup process before starting updated workers. A down migration intentionally refuses to remove asset-aware tables when BCH receive configurations or payments exist. Do not use rollback as a way to discard BCH production data.

Release validation​

The completed BCH release validation covers:

  • BCH xpub and tpub validation and saving through the dashboard;
  • canonical bitcoincash: and bchtest: derivation and normalization of prefixless and supported legacy inputs;
  • fixed-satoshi and fiat-priced payment creation;
  • pending to detected to confirmed progression using an actual BCH testnet transaction;
  • signed detected and confirmed webhooks, replay-safe event handling, and webhook-event lookup;
  • pending cancellation and expiry behavior;
  • cross-asset route rejection, usage grouping, and shared plan limits;
  • healthy BCH node/listener dashboards, block activity, RPC latency, and alert delivery.

Deployment model​

BCH processing uses isolated listeners and separately configured node connections for fault isolation. Mainnet and testnet credentials, receive configurations, addresses, and payments remain separate even though both scopes are available through the same API contract. Node RPC and ZMQ ports are internal infrastructure and must not be exposed publicly.

For a safe first integration, follow the BCH Testnet Quickstart. For wallet formats and mainnet configuration, see Receive Descriptors and Extended Public Keys.

Last updated on