GET/v1/partner/end_users/{external_id}/wallet-balance

Get wallet balance

Returns the current on-chain token balance for the end user's provisioned wallet. This is a real-time read from the blockchain — not a cached value. Use this to display how much USDC a user has available to deposit. Supports both Entra token + user token.

The response always includes the token metadata (symbol, address, decimals) alongside the balance, so you can format the amount correctly without a separate lookup.

Path parameters

external_idstringrequired

Your stable identifier for the end user.

Headers

Authorizationstringrequired

Entra M2M access token. Format: Bearer <token>. See Entra authentication.

X-User-Tokenstringoptional

Partner-minted JWT for the end user. Required in user-scoped. The sub claim must equal external_id. See User authentication.

Query parameters

chain_idstringoptional

Chain to query. Numeric string. Default: "84532" (Base Sepolia). Currently only Base Sepolia is supported.

Example request

const baseUrl = process.env.YIELDFORCE_API_BASE_URL ?? 'https://yieldforce.io/api';
 
const res = await fetch(
  `${baseUrl}/v1/partner/end_users/alice-bunq-id/wallet-balance`,
  {
    headers: {
      Authorization: `Bearer ${entraToken}`,
      'X-User-Token': partnerJwt,
    },
  }
);
const data = await res.json();

Response

200 Current on-chain wallet balance

{
  "wallet_address": "0xabc123...def456",
  "chain_id": "84532",
  "chain_name": "Base Sepolia",
  "token": {
    "symbol": "USDC",
    "address": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
    "decimals": 6
  },
  "balance": "25000000",
  "as_of": "2026-05-20T10:01:30.000Z"
}

The balance field is a string in token minor units. For USDC (6 decimals), "25000000" = 25 USDC. The as_of timestamp reflects when the on-chain read was made.

This is a live RPC call

Each request reads the chain in real time. Response times may vary (typically 200–800 ms) depending on RPC latency. Do not poll this endpoint more frequently than needed — call it when the user navigates to a deposit screen, not on a polling interval.

Errors

401 token_missing — No Authorization: Bearer header on the request.

401 invalid_entra_token — Token is expired, malformed, or has an unexpected audience.

401 invalid_user_token — The X-User-Token failed signature verification or is expired.

403 sub_url_mismatch — The sub claim in X-User-Token does not match external_id in the URL.

404 end_user_not_found — No user with this external_id exists in your tenant.

502 rpc_error — The on-chain read failed due to a node RPC error. Retry with exponential backoff.