Pockets & networks
title: "Pockets & networks" description: "How BchainPay organizes your funds: one pocket per Network/Coin pair, withdrawable on demand." section: "Concepts" order: 2 updated: "2026-04-18" sourcePath: "content/docs/concepts/pockets.mdx"
A pocket is a balance scoped to a single (Network, Coin) pair — for example USDC · polygon or ETH · ethereum. Every confirmed payment is credited to the matching pocket. Pockets live in BchainPay's custodial vault; you withdraw from them whenever you want.
Why pockets exist
Mixing chains in a single balance creates ambiguity at withdrawal time — 1 USDC on Polygon is not interchangeable with 1 USDC on Solana. Pockets keep each Network/Coin balance separate so withdrawals are always unambiguous.
Pocket lifecycle
- The first time you accept a payment in a given
(Network, Coin), BchainPay provisions the pocket automatically. - Subsequent confirmed payments accrue into the existing pocket.
- You list, retrieve, and withdraw pockets via the API or the dashboard.
- Pockets are never auto-swept; balances persist until you withdraw.
Pocket object
| Field | Type | Required | Description |
|---|---|---|---|
| id | string | required | Unique identifier, e.g. pkt_usdc_polygon. |
| network | string | required | One of ethereum, polygon, solana, tron, bnb. |
| coin | string | required | Asset symbol, e.g. USDC, USDT, ETH. |
| balance_cents | integer | required | Spendable balance in minor units of the coin (USDC cents = 1e-2 USDC). |
| pending_cents | integer | required | Balance from payments seen on-chain but not yet finalized. |
| updated_at | string | required | ISO-8601 timestamp of the last credit or debit. |
Listing your pockets
curl https://api.bchainpay.com/v1/pockets \
-H "Authorization: Bearer $BCHAINPAY_API_KEY"{
"data": [
{ "id": "pkt_usdc_polygon", "network": "polygon", "coin": "USDC", "balance_cents": 124900, "pending_cents": 0, "updated_at": "2026-04-18T10:11:02Z" },
{ "id": "pkt_eth_ethereum", "network": "ethereum", "coin": "ETH", "balance_cents": 3200, "pending_cents": 0, "updated_at": "2026-04-17T22:04:55Z" },
{ "id": "pkt_usdt_tron", "network": "tron", "coin": "USDT", "balance_cents": 800000, "pending_cents": 0, "updated_at": "2026-04-18T09:30:11Z" }
]
}