> ## Documentation Index > Fetch the complete documentation index at: https://docs.crypto.westminister.tech/llms.txt > Use this file to discover all available pages before exploring further. # Get Aggregated USDT, USDC, And Native Balances For All User Wallets > Returns aggregated **USDT**, **USDC**, and **native** balances (TRX/ETH) per wallet for the user. Custodial wallets provisioned by **POST /wallets** or **POST /wallets/for-owner** include **USDT** and **USDC** ledger rows on the wallet network. This summary endpoint now exposes both stablecoins through **`total_usdt`**, **`total_usdc`**, **`usdt_balance`**, and **`usdc_balance`**. Supports network filtering and optional force refresh from blockchain. **Balance Sources:** - By default, it returns cached balances from database - If `refresh=true`, it fetches directly from blockchain - If balance is not in the DB, it automatically fetches from blockchain as fallback **Network Filtering:** - Use `networks` parameter to filter by specific blockchain networks - Supports: `tron`, `ethereum`, or `tron,ethereum` - If omitted, returns balances for all networks **Response Fields:** - `total_usdt`: Sum of all **USDT** balances across all wallets - `total_usdc`: Sum of all **USDC** balances across all wallets - `balances[]`: Per-wallet **USDT**, **USDC**, and **native** (TRX/ETH) amounts - `is_cached`: Indicates if balance came from DB cache or blockchain - `last_synced`: Timestamp when balance was last updated in DB ## OpenAPI ````yaml /openapi.yaml get /api/v1/auth/balances/user/{user_id} openapi: 3.1.0 info: title: EmaalCoin API description: > EmaalCoin API reference. These APIs power cryptocurrency exchange between USDT and Fiat trading. - **On-Ramp**: Buy USDT with fiat (KES) via mobile money (STK Push for Kenya) - **Off-Ramp**: Sell USDT for KES with mobile money payout (Kenya) - **Ethereum, TRON, and Solana**: Multi-chain wallet support - **Merchant Offers**: Create and manage trading offers - **OTC Flows**: Bank and mobile money deposits/withdrawals for merchants - **Pricing engine**: FX quotes and fee profiles for quote-backed orders and transfers - **P2P/B2B transfers**: Internal and external stablecoin sends (USDT/USDC) with optional pricing snapshots - **Stablecoin swaps**: Treasury-backed two-leg USDT ↔ USDC conversion with BitGo confirmation, inventory reservation, and automatic refunds - **Multisig**: Collaborative and platform-managed multisig flows for high-value B2B version: 1.1.0 servers: - url: https://crypto.westminister.tech description: Production API (requires DNS for this hostname). - url: http://13.42.110.185:8080 description: >- UAT on EC2 (direct). Use this base when building proof PDF URLs if the production hostname does not resolve. security: [] tags: - name: Pricing description: >- Commercial pricing profiles and FX rate quotes (admin). Used with orders and transfers for auditable snapshots. - name: Transfers description: >- P2P and B2B stablecoin transfers (USDT/USDC). Optional fiat-equivalent pricing fields. B2B multisig behavior depends on wallet registration (synchronous completion vs proposal flow). - name: Stablecoin Swaps description: >- Treasury-backed USDT ↔ USDC conversions for BitGo provider-managed wallets on `tron`, `ethereum`, or `solana`. Collection confirms before treasury payout starts. Completion requires both legs and dual-asset balance synchronization. - name: Multisig description: >- Multisig wallet registration and TRON proposal/confirm flows (vendor/admin). - name: Escrow Wallets description: Escrow pool wallet metadata for off-ramp and operations. - name: Users description: >- User-related operations (registration, lookup, updates, counts, status changes) - name: Wallets-Users description: User wallet operations (create, manage, query balances) - name: Offers description: Offer operations (create, read, list, counts) - name: Orders description: Order operations (create, update, list, counts, stats) - name: Payment description: Payment initiation operations - name: Merchants description: > Merchant (vendor) onboarding and hierarchy operations. USE **GET /API/V1/AUTH/MERCHANTS** WITH **PAGE_ID** AND **PAGE_SIZE** TO PAGE MASTER VENDORS. USE **GET /API/V1/AUTH/MERCHANTS/{MERCHANT_ID}** FOR ONE MASTER VENDOR, **MERCHANT_WALLETS**, AND ALL **SUBVENDOR** ROWS WITH **WALLETS** (FULL TREE). - name: OTC Deposits description: > OTC fiat-to-crypto deposits (bank or mobile money). Rows live in **`otc_deposits`**. Merchants create drafts or one-shot deposits. **admin**, **otc_officer**, or **treasury** list all deposits. B2B bank flow uses draft, quote, submit, proof, assign, claim, settlement, and audit. **`credited_to_address`** is the merchant on-chain wallet treasury credits (resolved from the default wallet for **`requested_network`** on the master merchant ledger user or any **sub-vendor** under that merchant). **`GET /api/v1/auth/otc/deposits`** backfills missing **`credited_to_address`**/**`to_wallet_id`** when a wallet can be resolved. One-shot **`POST /api/v1/auth/otc/deposits`** persists the payout address when **`requested_network`** is sent. Bank proof PDFs upload via `POST .../proof` and are viewed at **`GET /otc-deposits-proof/{deposit_id}/{file}.pdf`** (relative **`proof_url`**/**`file_url`** plus API base URL). Merchants may edit tab-1 draft fields with **`PATCH /api/v1/auth/otc/deposits/{id}/draft`** while **`status`** is **`draft`**. - name: OTC Withdrawals description: >- OTC crypto-to-fiat withdrawals (bank or mobile money). Merchants create. Admin approves and executes. - name: OTC Config description: OTC display config (bank details, mobile money paybill) for merchant UI - name: Fiat Currencies description: > Shared platform **fiat_currencies** catalog. **GET /api/v1/auth/fiat-currencies** lists active rows for UI pickers. **GET /api/v1/auth/fiat-currencies/admin** lists all rows including inactive (admin). Admin manages rows with **GET /api/v1/auth/fiat-currencies/{id}**, **POST /api/v1/auth/fiat-currencies**, **PATCH /api/v1/auth/fiat-currencies/{id}**, and **DELETE /api/v1/auth/fiat-currencies/{id}**. Use for OTC, pricing, orders, remittance, and backoffice — not under **`/otc/...`**. Prefer **PATCH** with **`is_active: false`** over delete when a currency is referenced. - name: Countries description: >- Shared platform **countries** catalog. Public **GET /api/v1/countries** lists active rows for pickers. Auth **GET /api/v1/auth/countries** returns the same active catalog. Admin manages rows with **GET /api/v1/auth/countries/admin**, **GET /api/v1/auth/countries/{id}**, **POST /api/v1/auth/countries**, **PATCH /api/v1/auth/countries/{id}**, and **DELETE /api/v1/auth/countries/{id}**. - name: Files description: Authenticated file uploads for OTC receipts and proof artifacts. paths: /api/v1/auth/balances/user/{user_id}: get: tags: - Wallets-Users summary: Get Aggregated USDT, USDC, And Native Balances For All User Wallets description: > Returns aggregated **USDT**, **USDC**, and **native** balances (TRX/ETH) per wallet for the user. Custodial wallets provisioned by **POST /wallets** or **POST /wallets/for-owner** include **USDT** and **USDC** ledger rows on the wallet network. This summary endpoint now exposes both stablecoins through **`total_usdt`**, **`total_usdc`**, **`usdt_balance`**, and **`usdc_balance`**. Supports network filtering and optional force refresh from blockchain. **Balance Sources:** - By default, it returns cached balances from database - If `refresh=true`, it fetches directly from blockchain - If balance is not in the DB, it automatically fetches from blockchain as fallback **Network Filtering:** - Use `networks` parameter to filter by specific blockchain networks - Supports: `tron`, `ethereum`, or `tron,ethereum` - If omitted, returns balances for all networks **Response Fields:** - `total_usdt`: Sum of all **USDT** balances across all wallets - `total_usdc`: Sum of all **USDC** balances across all wallets - `balances[]`: Per-wallet **USDT**, **USDC**, and **native** (TRX/ETH) amounts - `is_cached`: Indicates if balance came from DB cache or blockchain - `last_synced`: Timestamp when balance was last updated in DB parameters: - name: user_id in: path required: true schema: type: string format: uuid description: User ID to fetch balances for example: 5c81c005-1c52-4e0d-85e2-862ee1cdd4d0 - name: networks in: query required: false schema: type: string description: >- Comma-separated list of networks to filter by (tron, ethereum). If omitted, returns all networks. example: tron,ethereum - name: refresh in: query required: false schema: type: string enum: - 'true' - 'false' description: >- Force refresh from blockchain. If true, fetches directly from blockchain instead of using DB cache. example: 'false' - name: include_pending in: query required: false schema: type: string enum: - 'true' - 'false' description: Include pending transactions (reserved for future use) example: 'false' responses: '200': description: Balances retrieved successfully content: application/json: schema: type: object properties: user_id: type: string format: uuid description: User ID example: 5c81c005-1c52-4e0d-85e2-862ee1cdd4d0 total_usdt: type: string description: Aggregated USDT balance across all wallets example: '977.00000000' total_usdc: type: string description: Aggregated USDC balance across all wallets example: '125.50000000' balances: type: array description: Array of wallet balances items: type: object properties: wallet_id: type: string format: uuid description: Wallet ID example: fae48f4b-9aa3-44db-9011-c4f6b91aeb0e wallet_address: type: string description: Wallet address on blockchain example: TAVFvX9tToo1UJ2h7j47jVkgQjZa8LarY8 network: type: string enum: - tron - ethereum description: Blockchain network example: tron usdt_balance: type: string description: USDT balance for this wallet example: '977.00000000' usdc_balance: type: string description: USDC balance for this wallet example: '125.50000000' native_balance: type: string description: >- Native currency balance (TRX for Tron, ETH for Ethereum) example: '1993.89360000' last_synced: type: string format: date-time nullable: true description: >- Timestamp when balance was last synced to database (if cached) example: '2026-01-16T09:20:58Z' is_cached: type: boolean description: >- Whether this balance came from database cache (true) or blockchain (false) example: false synced_at: type: string format: date-time description: Timestamp when this response was generated example: '2026-01-16T09:20:58Z' examples: default_response: summary: Default Response (Cached Balances) value: user_id: 5c81c005-1c52-4e0d-85e2-862ee1cdd4d0 total_usdt: '977.00000000' total_usdc: '125.50000000' balances: - wallet_id: fae48f4b-9aa3-44db-9011-c4f6b91aeb0e wallet_address: TAVFvX9tToo1UJ2h7j47jVkgQjZa8LarY8 network: tron usdt_balance: '977.00000000' usdc_balance: '125.50000000' native_balance: '1993.89360000' last_synced: '2026-01-16T09:15:30Z' is_cached: true - wallet_id: de755c09-27e0-41cd-a791-41c5c858459c wallet_address: '0x17F4552b0c47F24F88B9569E6305413c5ff5370d' network: ethereum usdt_balance: '0.00000000' usdc_balance: '0.00000000' native_balance: '0.00000000' last_synced: '2026-01-16T09:15:30Z' is_cached: true synced_at: '2026-01-16T09:20:58Z' refreshed_response: summary: Response With Refresh=true (From Blockchain) value: user_id: 5c81c005-1c52-4e0d-85e2-862ee1cdd4d0 total_usdt: '977.00000000' total_usdc: '125.50000000' balances: - wallet_id: fae48f4b-9aa3-44db-9011-c4f6b91aeb0e wallet_address: TAVFvX9tToo1UJ2h7j47jVkgQjZa8LarY8 network: tron usdt_balance: '977.00000000' usdc_balance: '125.50000000' native_balance: '1993.89360000' is_cached: false - wallet_id: de755c09-27e0-41cd-a791-41c5c858459c wallet_address: '0x17F4552b0c47F24F88B9569E6305413c5ff5370d' network: ethereum usdt_balance: '0.00000000' usdc_balance: '0.00000000' native_balance: '0.00000000' is_cached: false synced_at: '2026-01-16T09:20:58Z' filtered_response: summary: Response Filtered By Network (TRON Only) value: user_id: 5c81c005-1c52-4e0d-85e2-862ee1cdd4d0 total_usdt: '977.00000000' total_usdc: '125.50000000' balances: - wallet_id: fae48f4b-9aa3-44db-9011-c4f6b91aeb0e wallet_address: TAVFvX9tToo1UJ2h7j47jVkgQjZa8LarY8 network: tron usdt_balance: '977.00000000' usdc_balance: '125.50000000' native_balance: '1993.89360000' is_cached: false synced_at: '2026-01-16T09:20:58Z' '400': description: Bad request (invalid user ID format) '404': description: User not found or no wallets found '500': description: >- Internal server error (blockchain fetch failed, database error, etc.) security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: PASETO ````