On-chain concepts

You do not need to be a blockchain engineer to use CowriePay, but four behaviours of public chains leak into any API built on them. Each one below is what this platform actually does, not what is typical.

Detected is not confirmed

A deposit moves through DETECTED, CONFIRMING, then CONFIRMED. Those are not cosmetic:

• DETECTED means the transaction was seen on-chain and is below the confirmation threshold.
• CONFIRMING means it is accumulating confirmations.
• CONFIRMED means the threshold was reached, and only then is the sweep triggered.

Credit your customer on CONFIRMED, never on DETECTED. A detected transaction can still disappear if the block that carried it stops being part of the canonical chain.

Do not hard-code the threshold. Read it off the deposit. Every deposit carries required_confirmations alongside confirmations, so 7 / 19 is a progress fraction you can render directly.

That field is captured when the deposit is first seen and never changed afterwards. If an operator raises the platform threshold for a chain, deposits already in flight keep the number they started with, so a progress bar can never run backwards. The new value applies to future deposits only.

For orientation, the thresholds currently deployed are 19 on TRON and 12 on BSC and Ethereum, but treat those as today’s values and the field as the contract.

What a chain reorganisation does

If a confirmed deposit’s transaction later stops being on the canonical chain, CowriePay detects it and raises an internal alert. It does not automatically roll back the balance.

That is a deliberate choice: at these confirmation depths a reorg is close to impossible on the chains supported here, and an automatic balance rollback after funds have been credited creates accounting errors worse than the event it tries to repair. A human investigates instead.

What this means for you: reorg handling is not something your integration has to implement, but it also is not instantaneous or silent. If it ever happens on your workspace, you will be contacted.

Dust below the sweep minimum

Sweeping a deposit costs gas. Below a certain amount the gas is too large a share of the value, so the deposit stays on its deposit address instead of being swept. It is not lost, and it is not credited away; it waits until consolidating it is economical.

The floors are per asset, in the asset’s own units, and are higher on Ethereum because Ethereum gas is dear:

Asset	Sweep minimum
USDT_TRON	1
USDT_BSC	1
USDT_ETH	20
USDC_ETH	20
EURC_ETH	20
ETH	0.005
BNB	0.02

These are the deployed defaults and can be overridden per deployment. If your product accepts small payments, design for the case where a payment arrives, confirms, and is not swept yet.

Chains must be open before you can use them

A chain is closed by default and only accepts client wallets and withdrawals once an operator has enabled it. Creating a wallet on a chain that is not enabled returns 422 CHAIN_NOT_ENABLED.

Call List the chains open for new operations before rendering a chain or asset picker, so a customer never selects a chain that will fail at wallet creation.

Sandbox failure simulation is not available yet

There is currently no way to deterministically trigger a failure scenario in the Sandbox. The full statement of what the Sandbox is and is not lives in The sandbox and the faucet.