--- updatedAt: 2026-08-16T05:54:27.000Z agentTools: projectIndex: https://docs.wirexapp.com/llms.txt --- # Wallets and Balances Read the corporation's wallets and the token balances held on each. ## Before You Start Read the following guides before proceeding: | Guide | Why | | ------------------------------------------------------- | ------------------------------------------ | | [Getting Started](https://docs.wirexapp.com/docs/corporate-getting-started) | Platform overview and setup | | [Api Basics](https://docs.wirexapp.com/docs/corporate-api-basics) | Required headers and request configuration | | [Authentication](https://docs.wirexapp.com/docs/corporate-authentication) | How to obtain the corporation token | | [Wallet Deployment](https://docs.wirexapp.com/docs/corporate-onchain-registration) | Where the primary wallet comes from | *** ## Overview A corporation holds one or more wallets. The primary wallet is the corporation wallet itself — the address created on-chain and recorded as `corporation_address`. It funds every operation: card issuance fees, bank transfers, corridor transfers and FX are all debited from it. Additional wallets can be registered as global wallets to receive deposits from other chains. *** ## Read Wallets and Balances ``` GET /api/v1/wallets ``` Requires a corporation token. No permission is declared. **Response:** ```json { "data": [ { "wallet_address": "0xA7E41d5680dE394EaA2ed417169DFf56840Fb3EE", "wallet_name": "Main Wallet", "wallet_status": "Confirmed", "wallet_type": "Primary", "balances": [ { "token_symbol": "WUSD", "token_address": "0x0774164DC20524Bb239b39D1DC42573C3E4C6976", "balance": 1250.75, "reference_balance": 1250.75, "reference_currency": "USD" }, { "token_symbol": "WEUR", "token_address": "0x5c55F314624718019A326F16a62A05D6C6d8C8A2", "balance": 400.5, "reference_balance": 468.28, "reference_currency": "USD" } ] } ] } ``` | Field | Description | | ------------------------------- | ----------------------------------------------------------------- | | `wallet_address` | The wallet's address | | `wallet_name` | Display name. `Main Wallet` for the primary wallet unless renamed | | `wallet_status` | `Unknown`, `Confirmed` or `Rejected` — see below | | `wallet_type` | `Primary`, `Secondary` or `Global` | | `balances[]` | One entry per token held. Empty when the wallet holds nothing | | `balances[].token_symbol` | Token symbol | | `balances[].token_address` | Token contract address | | `balances[].balance` | Balance in the token's own units | | `balances[].reference_balance` | The same balance converted to the reference currency | | `balances[].reference_currency` | Reference currency. **Always `USD`** on this endpoint | > The schema documents `reference_currency` as determined by the corporation's registration country, > but this endpoint converts every balance against **`USD`**, whatever the corporation's country. Do > not present `reference_balance` as a local-currency figure. ### Wallet Status | Status | Description | | ----------- | ------------------------------------------------------------------------------------------------------- | | `Confirmed` | The wallet is a valid Account Abstraction wallet with the required modules and policy | | `Rejected` | The wallet configuration is invalid or incomplete | | `Unknown` | The wallet has not been verified yet. A newly registered corporation and every global wallet start here | > **Wait for the `Primary` wallet to read `Confirmed` before calling any funded flow.** It is created > asynchronously after registration and starts at `Unknown`; `Confirmed` is what says the platform has > verified its modules and policy. Poll this endpoint after > [Registering a Corporation](https://docs.wirexapp.com/docs/corporate-registration). ### Wallet Type | Type | Description | | ----------- | --------------------------------------------------------------- | | `Primary` | The corporation wallet. Funds every debit the platform performs | | `Secondary` | An additional wallet registered to the corporation | | `Global` | A wallet registered to receive cross-chain deposits | > **A wallet whose balance read fails returns an empty `balances` array rather than an error.** The call > succeeds and that wallet simply appears to hold nothing. Do not treat an empty `balances` array as > proof of a zero balance for a wallet you know is funded — re-read before acting on it. ### Code ```javascript const response = await fetch(`${baseUrl}/api/v1/wallets`, { headers: { 'Authorization': `Bearer ${corporationToken}` } }); const { data: wallets } = await response.json(); ``` ```python response = requests.get( f"{base_url}/api/v1/wallets", headers={"Authorization": f"Bearer {corporation_token}"}, ) wallets = response.json()["data"] ``` ```go req, _ := http.NewRequest("GET", baseURL+"/api/v1/wallets", nil) req.Header.Set("Authorization", "Bearer "+corporationToken) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() var walletsResp struct { Data []WalletResponse `json:"data"` } json.NewDecoder(resp.Body).Decode(&walletsResp) ``` *** ## Unified Tokens A corporation's balance is not held in USDC or EURC directly. When a supported stablecoin arrives, the platform mints an equivalent amount of a **unified token** — `WUSD` for USD value, `WEUR` for EUR — and the underlying stablecoin is held in reserve. Balances, card spending, transfers and settlements all operate on the unified token. | | Unified token | Regular token | | -------------------- | --------------------------------------- | -------------------------------------------- | | Examples | `WUSD`, `WEUR` | `USDC`, `USDT`, `EURC` | | `token_type` | `Synthetic` | `Regular` | | `base_token_address` | Present — the ERC-20 backing it | Absent | | Where it appears | Balances, card spending, most transfers | On-chain movement in and out of the platform | Both are listed by `GET /api/v1/config/tokens` — see [Token Types](https://docs.wirexapp.com/docs/corporate-environments#token-types). ### Why It Matters The distinction is invisible until an operation demands one family specifically: | Operation | Accepts | | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | Card issuance and spending | Either | | [Push-to-card transfer](https://docs.wirexapp.com/docs/corporate-card-transfer) | Unified tokens directly — no unwrap needed | | [FX](https://docs.wirexapp.com/docs/corporate-fx) | **Regular tokens only.** A corporation funding a swap from `WUSD` must unwrap and send the underlying token in the same operation | | On-chain transfer out of the platform | Regular tokens — the unified token is unwrapped first | Wrapping happens automatically on deposit. Unwrapping is an on-chain operation your integration performs; it appears in the activity feed as `SyntheticUnwrap`, and the corresponding mint appears as `SyntheticWrap` — see [Activity History](https://docs.wirexapp.com/docs/corporate-activity-history). *** ## Balance Changes Balance changes are delivered to `POST {your_webhook_base_url}/v2/webhooks/balances`, keyed by `wallet_address`. Resolve the corporation by matching the address against this endpoint's response. See [Webhooks](https://docs.wirexapp.com/docs/corporate-webhooks). *** ## Funding the Corporation Funds arrive at the corporation wallet in four ways: | Route | Guide | | --------------------------------------------- | ---------------------------------------------- | | An on-chain transfer to `corporation_address` | — | | A fiat deposit into a corporate bank account | [Bank Accounts](https://docs.wirexapp.com/docs/corporate-bank-accounts) | | A cross-chain deposit to a global wallet | [Global Wallets](https://docs.wirexapp.com/docs/corporate-global-wallets) | | An FX swap into a different asset | [FX](https://docs.wirexapp.com/docs/corporate-fx) | The Corporate API has no crypto withdrawal endpoint. Outbound crypto movement is performed on-chain from the corporation wallet; pending oracle-executed withdrawals are listed by `GET /api/v1/withdrawal/requests` — see [Withdrawal Requests](https://docs.wirexapp.com/docs/corporate-activity-history). *** ## Error Handling ```json { "error_reason": "ErrorGeneral", "error_description": "Failed to read corporation wallets", "error_category": { "category": "CategoryInternalFailure", "http_status_code": 500 } } ``` ### Server Errors (500) | Error Reason | Description | Resolution | | -------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `ErrorGeneral` | `Failed to get corporation from context` | The corporation token is malformed — log in again | | `ErrorGeneral` | `Failed to read corporation wallets` | The wallet list could not be read. Retry | | `ErrorGeneral` | `Failed to read tokens` | The token catalogue was unavailable. Retry | | `ErrorGeneral` | `Failed to read rates` | Rates were unavailable — the call fails rather than returning balances without `reference_balance`. Retry |