Managing Stablecoin Balances & Wallets

This guide covers creating and holding usd_stable and COPco balances, and provisioning self-custodian wallets to receive stablecoins on-chain (usd_stable only — COPco is closed loop and does not use wallets).

Creating a Stablecoin Balance

A stablecoin balance is created through the Create a Cobre Balance API using the provider pr_stable_omnibus_cobre. The same provider supports two currencies, selected via metadata.currency:

`metadata.currency`	Balance	On-chain wallets	Payins / Payouts	Rewards
`usd_stable`	USD stablecoin	Yes	Yes	No
`copco`	COPco (closed loop)	No	No	Yes

The account is created asynchronously: the initial response returns connectivity.status: connecting, and clients should poll the account until it reaches connected.

Only usd_stable balances support self-custodian wallets and on-chain payins/payouts. copco balances only support on/off-ramp with COP fiat and daily rewards — see Stablecoin Funding and COPco Rewards.

Provisioning a Self-Custodian Wallet

To receive stablecoins on-chain, create an Account Reference of type self_custodian_wallet on a usd_stable balance via the Create an Account Reference API, specifying the network in metadata.chain:

`metadata.chain`	Networks covered	Supported tokens
`evm_compatible`	Ethereum, Polygon (single wallet address)	USDC, USDT
`tron`	Tron	USDT
`stellar`	Stellar	USDC

Wallet creation is asynchronous: the wallet starts in connectivity.status: processing with an empty value, and transitions to enabled once the address is provisioned by the wallet infrastructure provider.

Self-custodian wallets are not supported on copco balances — they are closed loop in the current phase.

Key Terms

Stable Balance: A Cobre Balance created with provider_id: pr_stable_omnibus_cobre, holding either usd_stable or copco.

Self-Custodian Wallet: An Account Reference of type self_custodian_wallet, representing an on-chain address that receives stablecoins on behalf of a balance.

Chain: The blockchain network a wallet operates on (evm_compatible, tron, stellar).

Allowed Actions on Stablecoin Balances & Wallets

🔑 Create Balance

🔍 Retrieve Balance

🔑 Create Wallet

🔍 Retrieve Wallet

Description: Creates a stablecoin balance (usd_stable or copco).
What to expect after the action: A balance object in connecting status, transitioning to connected once provisioned.
📘 Learn more:

🔗 Create or Connect an Account

How to Get Started

Decide which currency you need

Choose usd_stable if you need on-chain payins/payouts and wallets, or copco if you only need to hold COP-denominated value and earn rewards.

Choose a network for your wallet (usd_stable only)

Pick evm_compatible, tron, or stellar based on where your counterparties or senders operate.

Implement Webhooks to track provisioning

Both balances and wallets are provisioned asynchronously. Subscribe to the relevant events to track when they reach their final status instead of polling.

See Notifications & Subscriptions for more details.

What to expect after using this API

Balance reaches connected status

Once provisioning completes, the balance is ready to receive on/off-ramp transfers and, for usd_stable, payins and payouts.

Wallet reaches enabled status with an address

Once the wallet is provisioned, value contains the real on-chain address. Share this address with senders to start receiving stablecoin payins — see Stablecoin Payins.

Managing Stablecoin Balances & Wallets

Creating a Stablecoin Balance#

Provisioning a Self-Custodian Wallet#

Key Terms#

Allowed Actions on Stablecoin Balances & Wallets#

How to Get Started#

What to expect after using this API#

Creating a Stablecoin Balance

Provisioning a Self-Custodian Wallet

Key Terms

Allowed Actions on Stablecoin Balances & Wallets

How to Get Started

What to expect after using this API