Wallets and Balances

Before You Start

Read the following guides before proceeding:

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:

{
  "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"
        }
      ]
    }
  ]
}

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

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.

Wallet Type

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

const response = await fetch(`${baseUrl}/api/v1/wallets`, {
  headers: { 'Authorization': `Bearer ${corporationToken}` }
});
const { data: wallets } = await response.json();

response = requests.get(
    f"{base_url}/api/v1/wallets",
    headers={"Authorization": f"Bearer {corporation_token}"},
)
wallets = response.json()["data"]

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.

Both are listed by GET /api/v1/config/tokens — see
Token Types.

Why It Matters

The distinction is invisible until an operation demands one family specifically:

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.

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.

Funding the Corporation

Funds arrive at the corporation wallet in four ways:

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.

Error Handling

{
  "error_reason": "ErrorGeneral",
  "error_description": "Failed to read corporation wallets",
  "error_category": {
    "category": "CategoryInternalFailure",
    "http_status_code": 500
  }
}

Server Errors (500)