> ## Documentation Index > Fetch the complete documentation index at: https://docs.prosperavest.com/llms.txt > Use this file to discover all available pages before exploring further. # Read on-chain balance > Balance of a whitelisted asset (ENSC, USDC, USDT, CELO) for an account on a chain of the key environment. Response body is a SealedResponseEnvelope whose plaintext is BalanceResponse. Send X-ENSC-Key-Id to pick the recipient signing key when more than one is active. ## OpenAPI ````yaml /openapi/ensc-2026-09-15.json get /v1/balance openapi: 3.1.0 info: title: ENSC API version: '2026-09-15' description: >- The ENSC stablecoin platform API: conversions through the ENSC converter (pair token or Naira in, ENSC out, and back), ENSC transfers, balances, bank directory and account resolution. **Versioning**: URL major (`/v1`) + date-pinned header (`X-ENSC-API-Version: 2026-09-15`). Version 2026-09-15 introduces mandatory payload encryption. **Authentication**: API key (Bearer) + mandatory IP allowlist on live keys. **Request encryption**: every mutating merchant-key call carries an ENSC-ENC-V1 envelope (AES-256-GCM under the merchant encryption key, request-bound AAD). Plaintext bodies are refused. **Request signing**: Ed25519 over a canonical string that includes the SHA-256 of the envelope bytes, a timestamp (300s window) and a one-time nonce. **Sealed responses**: every 2xx body to a merchant sk/rk key is an ENSC-RESP-V1 envelope (HPKE RFC 9180, X25519 + ChaCha20-Poly1305) sealed to the merchant signing key and signed by ENSC. **Error envelope** (never encrypted): `{ "error": { "code": "ENSC_...", "message": "...", "requestId": "req_..." } }`. **Amounts**: every amount you send is a decimal string in the asset's own units (`"0.1"` CELO, `"100"` USDC, `"1000.00"` NGN; fiat amounts take at most 2 decimals). Every amount the API returns is a base-unit integer string (`amountIn`, `amountOut`, `balance`) with a decimal twin (`amountInFormatted`, `amountOutFormatted`, `formatted`) already divided by the asset's decimals: ENSC 18, CELO 18, USDC and USDT 6, NGN legs 18 (stored as ENSC units). Never do arithmetic on the formatted strings; use the base units with a big-integer type. **Unsigned transactions**: `{ from, to, data, value: "0", chainId }`. ENSC never holds a wallet key and never broadcasts. Sign with the wallet named in `from` (the conversion's wallet), on the chain named in `chainId`, and estimate gas with an explicit limit before sending. For a voucher, send `approvalTransaction` first when it is present, then `transaction`, then report the hash on `/v1/conversions/{reference}/events`. **Webhooks**: register a public https endpoint on your backend (`POST /v1/webhook-endpoints` or the dashboard). Every delivery is signed with ENSC's Ed25519 key (`ENSC-WH-V1` over the webhook id, the timestamp and the SHA-256 of the raw body; key published at `/v1/.well-known/ensc-public-keys.json`), retried after 1 min, 5 min, 15 min, 1 h, 2 h, 4 h and 8 h (8 attempts in total over about 15 hours) when your endpoint does not answer 2xx within 15 s, and delivered at least once; de-duplicate on the event `id`. Ordering is not guaranteed: act on the status carried by the event. contact: name: ENSC Support license: name: Proprietary servers: - url: https://api.ensc.prosperavest.com description: >- ENSC API (Sandbox and Live share one host; the key prefix selects the environment) security: [] tags: - name: Health - name: Banks - name: Balance - name: Conversions - name: Transfer - name: Webhooks - name: Events - name: Test Data - name: API Keys - name: Signing Keys - name: Encryption Keys - name: Origins paths: /v1/balance: get: tags: - Balance summary: Read on-chain balance description: >- Balance of a whitelisted asset (ENSC, USDC, USDT, CELO) for an account on a chain of the key environment. Response body is a SealedResponseEnvelope whose plaintext is BalanceResponse. Send X-ENSC-Key-Id to pick the recipient signing key when more than one is active. parameters: - schema: type: string example: 0xAbC... required: true name: account in: query - schema: type: string enum: - ENSC - USDC - USDT - CELO required: false name: asset in: query - schema: type: string example: 0xF50FFf... required: false name: contractAddress in: query - schema: type: string example: celo required: true name: chain in: query - schema: type: string example: sig_01HXY... required: false name: X-ENSC-Key-Id in: header responses: '200': description: Sealed response headers: X-ENSC-Request-Id: schema: type: string example: req_01HXY... required: true X-ENSC-API-Version: schema: type: string example: '2026-09-15' required: true X-ENSC-Signature: schema: type: string example: ed25519= description: ENSC signature over the sealed body. required: true description: ENSC signature over the sealed body. X-ENSC-Key-Id: schema: type: string description: >- Which ENSC key signed; see /v1/.well-known/ensc-public-keys.json. required: true description: >- Which ENSC key signed; see /v1/.well-known/ensc-public-keys.json. X-ENSC-Timestamp: schema: type: string example: '1714579200' required: true content: application/json: schema: $ref: '#/components/schemas/SealedResponseEnvelope' '400': description: Validation failed content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: Authenticated but lacks scope/permission content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limit exceeded headers: Retry-After: schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '500': description: Internal error content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - ApiKeyAuth: [] x-codeSamples: - lang: typescript label: '@ensc/sdk' source: >- const b = await ensc.balance.get({ account: wallet, chain: 'celo', asset: 'ENSC' }); // b.balance (base units), b.formatted components: schemas: SealedResponseEnvelope: type: object properties: v: type: number enum: - 1 enc: type: string pattern: ^[A-Za-z0-9_-]{43}$ ciphertext: type: string pattern: ^[A-Za-z0-9_-]{22,}$ required: - v - enc - ciphertext additionalProperties: false description: >- ENSC-RESP-V1. HPKE (RFC 9180; DHKEM(X25519, HKDF-SHA256), HKDF-SHA256, ChaCha20-Poly1305) seal of the plaintext JSON response to the merchant signing key named by X-ENSC-Key-Id (Ed25519 key converted to X25519). info = "ENSC-RESP-V1\n{requestId}". The body is signed by ENSC: X-ENSC-Signature over "ENSC-RESP-V1\n{requestId}\n{timestamp}\n{sha256(body)}". Returned for sk/rk merchant keys only. ErrorEnvelope: type: object properties: error: type: object properties: code: type: string example: ENSC_VALIDATION_FAILED message: type: string requestId: type: string details: type: object additionalProperties: {} required: - code - message required: - error securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: ENSC API key (ensc_{env}_{kind}_) description: >- Your secret key, generated in the ProsperaVest dashboard (Sandbox or Live). Send as: Authorization: Bearer ensc_live_sk_... ````