Consumer Balance — GET /api/consumer/balance

The balance endpoint returns the authenticated consumer’s USDC balance in USDC (6-decimal) units. The balance is read live from the Arc Mainnet ERC-20 USDC contract (0x3600000000000000000000000000000000000000) for the consumer’s wallet address — no cached or ledger value is involved.

Endpoint

GET https://flarehq.xyz/api/consumer/balance

Request

Headers

Header	Value
`Cookie`	`consumer_token=...` — required

This is a browser route authenticated by the consumer_token cookie set at POST /api/consumer/session. The wallet address is resolved from the cookie’s JWT payload.

Response

boolean

true on success.

string

The consumer’s USDC balance formatted with 6 decimal places, as a decimal string (e.g. "125.750000").

string

The wallet address the balance was read for.

Examples

curl https://flarehq.xyz/api/consumer/balance \
  -b cookies.txt

const res = await fetch('https://flarehq.xyz/api/consumer/balance', {
  credentials: 'include', // sends the consumer_token cookie
});

const { success, balance, walletAddress } = await res.json();

Success Response

{
  "success": true,
  "balance": "125.750000",
  "walletAddress": "0x4a2F1b9c7dE03A6b8C5f2e9D1a4c7B6e3F9d2A8"
}

Error Responses

{
  "success": false,
  "error": "Sign in required."
}

{
  "success": false,
  "error": "Arc RPC/USDC address not configured."
}

{
  "success": false,
  "error": "internal error message"
}

Notes

The endpoint requires the ARC_USDC_ADDRESS and ARC_TESTNET_RPC environment variables to be configured server-side. If either is missing it returns HTTP 500 with "Arc RPC/USDC address not configured."

The balance reflects on-chain holdings at the wallet address from the consumer session. For Circle-managed consumer wallets this is the Circle-provisioned address; for external wallets it is the connected address. It is read in real time and will not include in-flight (unconfirmed) transfers.

Overview

Payments

Escrow

Streaming

CCTP Bridge

Checkout

x402

Agents

Jobs

Merchant

Consumer

Payroll

Consumer Balance — GET /api/consumer/balance

Endpoint

Request

Headers

Response

Examples

Success Response

Error Responses

Notes

​Endpoint

​Request

​Headers

​Response

​Examples

​Success Response

​Error Responses

​Notes

Endpoint

Request

Headers

Response

Examples

Success Response

Error Responses

Notes