Skip to content
CowriePay API

Fees, balances and reconciliation

Money questions deserve exact answers. This page covers the three that matter: what will this cost, where is my money right now, and how do I prove my books match CowriePay’s.

How the fee is computed

Section titled “How the fee is computed”
  • Deposits pay a percentage of the gross, with a per-chain minimum fee; whichever is higher applies. The percentage is degressive: it follows your rolling 30-day deposit volume through the fee tiers (withdrawal volume never inflates the tier).
  • Withdrawals pay a flat per-chain fee.
  • A workspace can carry a negotiated override; when one applies, it takes precedence field by field over the tier.
  • Some contracts carry a negotiated monthly minimum commitment. When a calendar month’s billed fees fall short of the agreed floor, a catch-up adjustment for the difference is emitted (prorated on the first and last month) and notified by the COMMITMENT_ADJUSTMENT_EMITTED webhook. It is debited from your available balance only where your contract provides for it, and the debit is clamped to that balance, so it can never take you below zero; anything left uncovered stays payable. Read yours, and the current month’s progress, with GET /v2/commitment (scope fees:read); it answers null fields when none applies. A commitment that has ended stays readable there until everything owed on it is settled, with current_period null and outstanding_total_usdt carrying what is left. Article 9 of the terms and conditions is the contractual text.

You never hard-code any of these numbers: you quote them.

Quote before you act

Section titled “Quote before you act”

POST /v2/fees/quote (scope fees:read) prices a prospective deposit or withdrawal with the exact engine that will settle it, and always answers 200 for valid input:

{ "direction": "deposit", "chain": "TRON", "asset": "USDT_TRON", "amount": "100", "mode": "charge" }

The response carries gross, fee, net, the applied_rate and applied_min_fee that produced them, and effective_rate (fee over gross, which is higher than the nominal rate when the minimum fee dominates a small amount). Two modes:

  • charge (default): amount is the gross; net is what lands after fees.
  • gross_up: amount is the target net; gross is what must be sent so you net it.

A quote can be non-viable instead of failing: for an amount too small to survive the fee, you still get 200, with viable: false, net: null and a warnings[] entry naming why (the amount too small, the amount below the consolidation minimum, a minimum fee dominating, a negotiated override expiring within 24 h). Read the warnings; do not treat them as errors.

Quotes are indicative, settlement is binding. Between quote and settlement your 30-day volume can cross a tier boundary or an override can expire; the settled figures are the ones in the DEPOSIT_SWEPT payload and the fee_record.

The three balance states

Section titled “The three balance states”

GET /v2/transactions/balances returns, per asset, the three numbers that describe where your money is (scoped to your key’s network; mainnet and testnet never commingle):

Field Meaning
available Spendable now: credited net of fees, withdrawable
pending Detected deposits not yet consolidated: safe, but not spendable yet
locked Reserved by in-flight withdrawals: returns to available if they fail or are cancelled

The movements between them are exactly the status tables of Collect deposits and Send withdrawals: pending fills at DETECTED, converts to available (net) at SWEPT; locked fills at withdrawal creation and empties at the terminal state.

Reconcile to the cent

Section titled “Reconcile to the cent”

Everything you need to tie your books to CowriePay’s arrives on its own:

  • Per deposit: the DEPOSIT_SWEPT webhook carries the fee object (gross_amount, fee_amount, net_amount, applied_rate, applied_min_fee), and the same figures persist on the deposit’s fee_record (GET /v2/transactions/deposits), null until swept.
  • Per withdrawal: WITHDRAWAL_CONFIRMED carries the same fee object; the estimates you saw at creation become final here.
  • Reconcile per record, not per total. On a schedule, walk GET /v2/transactions (the combined feed) and check that every swept deposit’s net_amount and every terminal withdrawal is mirrored in your books, carrying in-flight records (pending deposits, locked withdrawals) as their own open lines. A record your system cannot explain is the finding; the deposits reconciliation habit is how you chase it.

What next

Section titled “What next”