​
Overview

Wallets are multi-asset custodial digital asset wallets. They let you receive on-chain deposits, hold balances across several assets and networks, and send on-chain transfers — all behind the same authenticated Customer API you use for fiat accounts. Balansas is the provider of record for these wallets; under the hood they are powered by Utila, our wallet technology provider, but that detail never surfaces in the API: every wallet is returned with provider: "balansas". All wallet responses use internal local UUIDs only (local_id). Vendor wallet identifiers stay server-side and are never exposed to the caller.
Browse the Wallets API Reference for the full request/response schemas and a live request playground.

​
Authentication & scopes

Wallet endpoints follow the same auth model as the rest of the API (see Authentication):
  • read:wallets — required for the GET routes.
  • write:wallets — required for every POST. Writes also require the X-CSRF-Token header and, for the customer, that Wallets are enabled on the account.
  • Money-moving POST routes accept an Idempotency-Key header. Repeating a call with the same key replays the original stored response — success or failure — so a flaky network can never double-send. See Idempotency.

​
Listing wallets

GET /wallets returns every wallet you own. Balansas wallets are multi-asset, so they have no single currency or deposit_address — addresses are generated per asset and network. 
curl https://stagingapi.balansas.com/functions/v1/customer-api/wallets \
  -H "x-api-key: sk_test_xxxxxxxxxxxxxxxxxxxx"

​
Wallet balances

GET /wallets/{walletId}/balances returns per-network balances for a single wallet, each grouped with its chain receive address. Use this on a wallet detail view.

​
Creating a wallet

POST /wallets provisions a new Balansas wallet and returns 201. The body is optional — you may bind the wallet to an end user or an umbrella link, but no fields are required.
​
endUserId
string
UUID. Bind the wallet to an end user.
​
umbrellaLinkId
string
UUID. Bind the wallet to a PPA Mode umbrella link. See PPA Mode.
curl -X POST https://stagingapi.balansas.com/functions/v1/customer-api/wallets \
  -H "x-api-key: sk_test_xxxxxxxxxxxxxxxxxxxx" \
  -H "X-CSRF-Token: <64-char-hex>" \
  -H "Idempotency-Key: 3f9c2a7e-1b4d-4c8a-9e21-7d5f0b6a1c33" \
  -H "Content-Type: application/json" \
  -d '{}'
A new wallet starts in pending and flips to active once provisioning completes and the wallet.created event fires.

​
Receive addresses

To receive funds, generate a receive address for a specific asset and network. POST /wallets/{walletId}/addresses creates a fresh address and returns 201.
​
asset
string
required
Asset symbol, e.g. USDC.
​
network
string
required
Network, e.g. ethereum.
Supported (asset, network) pairs at launch:
AssetNetwork
BTCbitcoin
ETHethereum
USDCethereum
USDTethereum
USDCpolygon
USDTtron
The specific pairs available to your account are configured by your account manager; requesting a pair that is not enabled returns 403. 
curl -X POST https://stagingapi.balansas.com/functions/v1/customer-api/wallets/{walletId}/addresses \
  -H "x-api-key: sk_test_xxxxxxxxxxxxxxxxxxxx" \
  -H "X-CSRF-Token: <64-char-hex>" \
  -H "Idempotency-Key: 7d5f0b6a-1c33-4c8a-9e21-3f9c2a7e1b4d" \
  -H "Content-Type: application/json" \
  -d '{ "asset": "USDC", "network": "ethereum" }'
GET /wallets/{walletId}/addresses lists all addresses generated for a wallet.

​
Sending from a wallet

POST /wallets/{walletId}/transfers initiates an on-chain transfer to an external destination address and returns 201.
​
asset
string
required
Asset symbol, e.g. USDC.
​
network
string
required
Network, e.g. ethereum.
​
amount
string
required
Positive decimal string to preserve precision (e.g. "125.50").
​
destination
string
required
External on-chain destination address.
​
note
string
Optional free-text note (max 500 characters).
Sends move money. Always supply a unique Idempotency-Key per logical send. A retry with the same key returns the original result instead of broadcasting a second transaction. See Idempotency.
curl -X POST https://stagingapi.balansas.com/functions/v1/customer-api/wallets/{walletId}/transfers \
  -H "x-api-key: sk_test_xxxxxxxxxxxxxxxxxxxx" \
  -H "X-CSRF-Token: <64-char-hex>" \
  -H "Idempotency-Key: 1c33-7d5f-0b6a-4c8a-9e21-3f9c2a7e1b4d" \
  -H "Content-Type: application/json" \
  -d '{
        "asset": "USDC",
        "network": "ethereum",
        "amount": "125.50",
        "destination": "0xdef..."
      }'

​
Webhook events

Subscribe to these events from the Webhooks surface. All payloads use local wallet_id / transaction_id UUIDs only.
  • wallet.created — wallet provisioned and ready.
  • wallet.incoming_transaction — an on-chain deposit was detected.
  • wallet.outgoing_transaction — an on-chain withdrawal was broadcast.
  • wallet_transaction.confirming — first network confirmations seen.
  • wallet_transaction.confirmed — required confirmations reached.
  • wallet_transaction.failed — transaction failed or was dropped.
  • wallet_transaction.quarantined — AML screening returned DENY; the transaction is held and will not credit the wallet.