Glossary

Every term the API and this documentation rely on, defined once. Terms are also introduced inline the first time a guide uses them; this page is the reference you come back to.

Accounts and money movement

Term	Definition
workspace	Your account on CowriePay. Every resource (wallets, deposits, withdrawals, keys, webhooks) belongs to a workspace. It never appears in URLs: it is resolved from the API key you sign with.
wallet	A dedicated deposit address derived for your workspace on one chain. It is not a client-side wallet holding keys: CowriePay keeps custody, and a wallet is simply where your users send funds.
customer	An optional sub-account that attributes wallets to one of your own end-users. Attribution only: balances stay at the workspace level.
deposit	Funds received on one of your wallets. Lifecycle: DETECTED, CONFIRMING, CONFIRMED, then SWEPT once consolidated (or FLAGGED when held for compliance review).
withdrawal	Funds sent out of your workspace balance to an external address, subject to the withdrawal security controls below.
balance: available / pending / locked	available is spendable now. pending is deposits detected but not yet consolidated. locked is reserved by an in-flight withdrawal and returns to available if it fails or is cancelled.
sweep (consolidation)	The internal move of confirmed deposits from their deposit address to CowriePay custody. Signalled by DEPOSIT_SWEPT; your net amount is credited then, with the fee breakdown in the webhook payload.
custody	CowriePay holds the private keys and signs every on-chain move on your behalf. You never handle keys, addresses’ seeds or gas.
fee: gross / fee / net	gross is what arrived on-chain, fee is what CowriePay charges when the deposit is consolidated, net is what your balance is credited. Quote it in advance with the fee quote endpoint.

Security controls

Term	Definition
scope	The fine-grained permission an API key carries, written resource:action (for example wallets:write). An endpoint refuses a key lacking its scope with 403 INSUFFICIENT_SCOPE.
allowlist	The list of approved destination addresses for withdrawals. ON by default on a live workspace: a withdrawal to an address not on it is refused.
beneficiary	An external address added to the allowlist. It becomes usable only after the cooling-off delay.
cooling-off delay	The waiting period before a newly added beneficiary becomes usable, and before a protection-weakening change (like disabling the allowlist) takes effect. It is what makes a compromised account unable to drain funds immediately.
four-eyes approval	A withdrawal above the configured threshold is held until a second member approves it. The member who created it can never be its approver.
HMAC signature	Every API request and every webhook delivery is signed with HMAC-SHA256. Verifying the webhook signature is the only thing that proves a delivery came from CowriePay.
idempotency key	The Idempotency-Key header on mutating POSTs. Retrying with the same key and body returns the original response instead of executing twice.

Environments

Term	Definition
Sandbox / Live	The two modes of your workspace. Same host, same code path: the prefix of the key you sign with decides, cpk_test_ for Sandbox and cpk_live_ for Live.
testnet / mainnet	The real public test networks (TRON Nile, BSC testnet, Ethereum Hoodi) versus the real-value networks. The Sandbox IS the testnet: there is no simulator, every test exercises the real on-chain path.
faucet	The built-in Sandbox tool that pre-funds one of your sandbox wallets with test assets, so you can exercise deposits end-to-end without hunting public faucets.

On-chain vocabulary

Term	Definition
confirmation	One block mined on top of the block carrying a transaction. A deposit is credited at CONFIRMED; read the threshold off the deposit’s required_confirmations, never hard-code it.
canonical chain / reorganisation	The chain the network agrees on. A block can stop belonging to it (a reorganisation), which is why a DETECTED deposit can still disappear and why crediting waits for CONFIRMED.
gas	The network fee every on-chain transaction pays. CowriePay pays the gas for consolidations and withdrawals; it is covered by the service fee, and you never need to hold native currency for it.