Introduction The Balances API provides real-time access to customer account balances and a unified transaction history that consolidates all activity: trades, Pix payments, and on-chain transfers.
BRL Brazilian Real - via Pix
USDT Tether USD - stablecoin
Balance types Each asset has two balance components:
Type Description availableFunds available for withdrawal or trading pendingFunds awaiting confirmation (deposits, pending trades)
Total balance = available + pendingThe balance object All amounts are represented as string-encoded integers in the asset’s smallest unit.
{ "customer_id" : "cus_a1b2c3d4e5f6" , "balances" : { "BRL" : { "available" : "150000" , "pending" : "0" , "asset" : "BRL" , "decimals" : 2 }, "USDT" : { "available" : "245670000" , "pending" : "100000000" , "asset" : "USDT" , "decimals" : 6 }, "BTC" : { "available" : "5234567" , "pending" : "1000000" , "asset" : "BTC" , "decimals" : 8 } }, "updated_at" : "2024-01-15T10:30:00Z" }
Balance attributes Attribute Type Description availablestring Available balance (smallest unit) pendingstring Pending balance (smallest unit) assetstring Asset code decimalsinteger Decimal places for the asset
Asset precision Asset Decimals Smallest unit Example BRL 2 1 centavo "150000" = R$ 1,500.00USDT 6 0.000001 USDT "100000000" = 100 USDTBTC 8 1 satoshi "5234567" = 0.05234567 BTC
Transaction history The transactions endpoint returns the full underlying objects for each balance-affecting operation. Each object includes a type field that indicates what kind of transaction it is:
Type ID prefix Description quotequote_Executed quote (trade) - full quote object pix_inboundpix_Incoming Pix payment - full Pix object pix_outboundpix_Outgoing Pix payout - full Pix object onchain_inboundtxn_Incoming on-chain transfer - full transfer object onchain_outboundtxn_Outgoing on-chain transfer - full transfer object
The id field always contains the actual object identifier (e.g., quote_abc123, pix_def456, txn_ghi789), not an internal ledger transaction ID.
Example: Quote transaction When a quote is executed, the full quote object is returned:
{ "type" : "quote" , "id" : "quote_abc123xyz" , "customer_id" : "cus_a1b2c3d4e5f6" , "status" : "executed" , "from_asset" : "BRL" , "to_asset" : "BTC" , "from_amount" : "100000" , "to_amount" : "24628" , "from_decimals" : 2 , "to_decimals" : 8 , "price" : "40200000" , "price_decimals" : 2 , "fees" : { "total" : "1000" , "total_bps" : 100 , "partner" : "500" , "partner_bps" : 50 , "bipa" : "500" , "bipa_bps" : 50 }, "created_at" : "2024-01-15T10:30:00Z" , "executed_at" : "2024-01-15T10:30:01Z" }
Example: Pix inbound transaction { "type" : "pix_inbound" , "id" : "pix_abc123" , "customer_id" : "cus_a1b2c3d4e5f6" , "direction" : "inbound" , "amount" : "150000" , "fee" : "0" , "decimals" : 2 , "status" : "completed" , "counterparty" : { "name" : "João Silva" , "document" : "***123***" , "bank_account" : { "ispb_code" : "00000000" , "branch_number" : "0001" , "account_number" : "12345678" , "account_type" : "checking" } }, "end_to_end_id" : "E00000000202401150930abc123def456" , "qr_code_id" : "pix_static_qr_xyz789" , "created_at" : "2024-01-15T09:30:00Z" , "completed_at" : "2024-01-15T09:30:02Z" }
Example: Pix outbound transaction { "type" : "pix_outbound" , "id" : "pix_def456" , "customer_id" : "cus_a1b2c3d4e5f6" , "direction" : "outbound" , "amount" : "50000" , "fee" : "0" , "decimals" : 2 , "status" : "completed" , "counterparty" : { "name" : "Maria Santos" , "document" : "***456***" , "pix_key" : "[email protected] " }, "description" : "Payment for services" , "end_to_end_id" : "E00000000202401151000def456ghi789" , "idempotency_key" : "pay_order_12345" , "created_at" : "2024-01-15T10:00:00Z" , "completed_at" : "2024-01-15T10:00:03Z" }
Example: On-chain inbound transaction { "type" : "onchain_inbound" , "id" : "txn_ghi789" , "customer_id" : "cus_a1b2c3d4e5f6" , "direction" : "inbound" , "asset" : "USDT" , "network" : "polygon" , "amount_gross" : "100000000" , "amount_net" : "100000000" , "fee" : "0" , "decimals" : 6 , "status" : "confirmed" , "address" : "0x1234567890abcdef1234567890abcdef12345678" , "tx_hash" : "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" , "confirmations" : 128 , "confirmations_required" : 128 , "created_at" : "2024-01-14T15:00:00Z" , "confirmed_at" : "2024-01-14T15:05:00Z" }
Example: On-chain outbound transaction { "type" : "onchain_outbound" , "id" : "txn_jkl012" , "customer_id" : "cus_a1b2c3d4e5f6" , "direction" : "outbound" , "asset" : "BTC" , "network" : "bitcoin" , "amount_gross" : "1005000" , "amount_net" : "1000000" , "fee" : "5000" , "decimals" : 8 , "status" : "confirmed" , "destination_address" : "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh" , "tx_hash" : "f4184fc596403b9d638783cf57adfe4c75c605f6356fbc91338530e9831e9e16" , "confirmations" : 6 , "confirmations_required" : 3 , "idempotency_key" : "withdraw_btc_001" , "created_at" : "2024-01-13T12:00:00Z" , "confirmed_at" : "2024-01-13T12:45:00Z" }
Endpoints Balance updates Balances update in real-time when:
Use webhooks to react to balance changes without polling. 
