9.9.26
by

Wallet Token Balance APIs — Spendable Balances & ACH/Alchemy Pay

Fintech‑style crypto apps can’t stop at “wallet balance.”

Wallet Token Balance APIs: Designing ACH & Alchemy Pay‑Aware Apps

Meta description: Learn how wallet token balance APIs power spendable balances, multi‑chain wallet views, and ACH/Alchemy Pay‑aware fiat mapping for modern crypto fintech apps.

Fintech‑style crypto apps can’t stop at “wallet balance.”

They need to show what a user can actually spend right now, across chains, assets, and payment rails like ACH (Alchemy Pay) — including:

  • Spendable vs. locked funds
  • Gas reserves and allowances
  • Fiat equivalents and limits
  • Pending transactions and merchant constraints

This pillar guide breaks down how wallet token balance APIs and Codex‑grade enrichment turn raw chain state into trading‑ and payment‑ready data.

What Is a Wallet Token Balance API?

A wallet token balance API is an endpoint that returns normalized balances for all assets held by a wallet address, often across multiple chains.

Instead of parsing raw logs or calling many RPC endpoints, product teams use these APIs to get:

  • Native balances (e.g., ETH, SOL)
  • Fungible tokens (ERC‑20, SPL, etc.)
  • Metadata (decimals, symbols, logos)
  • Prices in fiat and native terms
  • Historical and real‑time updates

Vendor examples include:

  • Codex: balances, refreshBalances, onBalanceUpdated for unified, enriched wallet views across 80+ networks and 700M+ wallets.[^codex-scale-2026]
  • Alchemy: Portfolio and Token APIs like tokens-by-address and alchemy_getTokenBalances for cross‑chain balances, metadata, and prices.[^alchemy-portfolio]
  • The Graph: Token API built on Substreams for live and historical token balances, transfers, holders, and DEX swaps across many chains.[^graph-token-api]

These APIs are now the backbone of wallets, exchanges, dashboards, and prediction‑market apps.

Why “Spendable Balance” Beats Raw Wallet Balance

For trading and payments, raw balance is misleading.

Users judge your product on:

  • Security
  • Ease of use
  • Reliability

Consensys’ 2024 survey across 18,000+ respondents in 18 countries found that security and ease of use are the top drivers of wallet choice and that 42% have bought crypto at least once.[^consensys-2024] That means your balance logic must match what actually clears on‑chain.

A spendable balance model should consider:

  • Current balance (including decimals and token type)
  • Required gas reserve on each chain
  • Allowances (ERC‑20 approvals, spending caps)
  • Pending transactions and holds
  • Merchant limits (min/max per asset, region constraints)

The result:

The amount the user can send, swap, or pay right now — without failing due to missing gas, excessive limits, or unaccounted pending transactions.

Multi‑Chain Wallet Balance API: Core Requirements

For modern wallets and fintech apps, a multi‑chain wallet balance API is table stakes.

Leading providers now emphasize:

  • Cross‑chain normalization
  • Unified schemas for native and token balances
  • Fiat pricing baked into responses

Examples:

Example: Codex balances (Wallet‑Oriented Plumbing)

Codex exposes a GraphQL‑style balances query that returns normalized wallet balances across supported chains.[^codex-balances]

Sample request (GraphQL):

query WalletBalances($address: String!) {
  balances(address: $address) {
    chainId
    tokenAddress
    symbol
    decimals
    shiftedBalance
    uiBalance
    balanceUsd
    tokenPriceUsd
  }
}

Sample response (JSON excerpt):

{
  "data": {
    "balances": [
      {
        "chainId": 1,
        "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "symbol": "USDC",
        "decimals": 6,
        "shiftedBalance": "152.372819",
        "uiBalance": "152.372819",
        "balanceUsd": "152.37",
        "tokenPriceUsd": "1.0002"
      }
    ]
  }
}

Codex notes explicitly that balanceUsd is computed from shiftedBalance using internal multipliers, and should be trusted over naive uiBalance * tokenPriceUsd.[^codex-balances]

Example: Alchemy tokens-by-address

Alchemy’s Portfolio API tokens-by-address returns balances, prices, and metadata across Ethereum, Solana, and 30+ EVM chains.[^alchemy-portfolio]

Sample request (HTTP/JSON):

POST /tokens-by-address HTTP/1.1
Host: api.alchemy.com
Content-Type: application/json

{
  "addresses": ["0x1234..."],
  "network": "ETH_MAINNET"
}

Sample response (JSON excerpt):

{
  "balances": [
    {
      "address": "0x1234...",
      "token": {
        "contractAddress": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
        "symbol": "USDT",
        "decimals": 6
      },
      "balance": "250000000", 
      "price": {
        "usd": 1.0
      }
    }
  ]
}

Alchemy complements this with:

  • alchemy_getTokenBalances for raw balances
  • alchemy_getTokenMetadata for decimals and symbols
  • Prices API for fiat valuation.[^alchemy-token-api]

Example: The Graph Token API

The Graph’s Token API gives live and historical balances, transfers, holders, and swaps across multiple chains without building your own indexer.[^graph-token-api]

They report that a Substreams‑based implementation improved multi‑chain indexing performance across nine major networks versus a prior stack, and the broader platform supports 60+ chains as of 2024.[^graph-substreams-2023]

Key takeaway: You should rely on a normalized multi‑chain wallet balance API rather than stitching raw RPC calls for every chain.

Real‑Time Wallet Balance Aggregation

For trading terminals and consumer wallets, real‑time wallet balance aggregation is critical.

Visa notes that stablecoin data is public and real‑time, but organizing it across chains still requires significant work due to chain‑specific nuances.[^visa-stablecoins-2024] That’s exactly what balance APIs try to solve.

High‑quality APIs provide:

  • Streaming updates (webhooks, subscriptions)
  • Explicit refresh controls
  • Low‑latency responses suitable for interactive UIs

Example: Codex refreshBalances and onBalanceUpdated

Codex exposes:

  • refreshBalances mutation to force refresh contract‑token and native‑token balances on EVM, Solana, Starknet.[^codex-balances]
  • onBalanceUpdated subscription to stream live balance changes.[^codex-balances]

Sample refreshBalances request (GraphQL):

mutation Refresh($address: String!) {
  refreshBalances(address: $address) {
    address
    chainsRefreshed
    refreshedAt
  }
}

Sample response:

{
  "data": {
    "refreshBalances": {
      "address": "0x1234...",
      "chainsRefreshed": [1, 137, 8453],
      "refreshedAt": "2026-09-07T12:34:56.000Z"
    }
  }
}

Sample onBalanceUpdated subscription (GraphQL):

subscription OnBalanceUpdated($address: String!) {
  onBalanceUpdated(address: $address) {
    chainId
    tokenAddress
    shiftedBalance
    balanceUsd
    updatedAt
  }
}

Codex emphasizes low‑latency, sub‑second freshness in public materials, but does not publish standardized benchmark methodology; treat this as a performance goal rather than a guaranteed SLA.[^codex-homepage-2026]

ACH (Alchemy Pay) and Payment Token Enrichment

How ACH (Alchemy Pay) Is Used

ACH is the utility token of Alchemy Pay, an ERC‑20 token on Ethereum used for fee discounts, staking, and ecosystem incentives.[^ach-token-ethereum]

Alchemy Pay has also announced Alchemy Chain materials positioning ACH as the gas‑fee token for that planned network, but Ethereum itself still uses ETH as gas.[^alchemy-chain-2025]

Key facts:

  • ACH is ERC‑20 on Ethereum mainnet.[^ach-token-ethereum]
  • It functions as a utility/payment token in the Alchemy Pay ecosystem.
  • It is not the native gas token for Ethereum.

Alchemy Pay Merchant & Fiat Mapping APIs

Alchemy Pay’s merchant Query API exposes exactly the data you need to align balances with fiat payment flows:[^alchemypay-query-api]

  • Supported Crypto Query: assets and network support plus limits.
  • Supported Fiat Query: fiat currencies, payment methods, and payWayCode.
  • Price Estimate Query: given crypto, network, fiat, amount, returns estimated crypto quantity plus fees.
  • IP Country Query: checks eligibility by location.

Sample fiat query request (HTTP/JSON):

GET /fiat?supported=true HTTP/1.1
Host: openapi.alchemypay.org

Sample response (JSON excerpt):

{
  "fiats": [
    {
      "currency": "USD",
      "paymentMethods": [
        {
          "payWayCode": "CARD",
          "min": 10,
          "max": 2000
        }
      ]
    }
  ]
}

Sample price query request (HTTP/JSON):

GET /price?crypto=ACH&network=ETH&fiat=USD&amount=100 HTTP/1.1
Host: openapi.alchemypay.org

Sample response (JSON excerpt):

{
  "crypto": "ACH",
  "network": "ETH",
  "fiat": "USD",
  "amount": 100,
  "estimatedCryptoQuantity": "350",
  "fee": {
    "total": 2.5
  }
}

By combining:

  • Wallet balances from Codex/Alchemy/The Graph
  • ACH holdings in the wallet
  • Alchemy Pay’s supported crypto, fiat, and price endpoints

you can compute what the user can pay via Alchemy Pay right now, including fees and limits.

Stablecoins, Wallet Adoption, and Why Balance UX Matters

Macro trends justify investing engineering time in better balance UX.

Stablecoin Growth

Visa’s 2024 report on stablecoins and tokenized deposits notes that retail‑sized stablecoin volume (USDC, USDT, PYUSD) grew from $0.5B to $69.8B between 2019 and early 2025, a 140x increase.[^visa-stablecoins-2024]

The U.S. Federal Reserve reports aggregate stablecoin market cap reached $317B by April 6, 2026, after 50%+ growth in 2025.[^fed-stablecoins-2026]

Chart showing growth in stablecoin retail volume and total market cap through 2026.
Stablecoin usage has exploded: retail-sized volume rose from $0.5B to $69.8B (2019–2025), while market cap reached $317B by April 2026.

These numbers underscore that small UX errors in balances can impact billions in flow.

Wallet Adoption & Expectations

Consensys’ 2024 survey of 18,000+ people in 18 countries found:[^consensys-2024]

  • 93% awareness of cryptocurrencies
  • 42% have owned or bought crypto
  • 43% of U.S. respondents and 84% of Nigerian respondents have owned or currently own a crypto wallet

They highlight that users in Africa prefer self‑custody, and globally, users prioritize security and simplicity.

Wallets need:

  • Correct and fresh balances
  • Clear explanation of limits and fees
  • Reliable handling of approvals and reserved gas

From Raw Chain Data to Spendable Balance: A Design Blueprint

You can think of spendable balance as a pipeline.

1. Resolve Multi‑Chain Balances

Use a multi‑chain wallet balance API to fetch normalized balances:

  • Codex balances for cross‑chain wallets and tokens.[^codex-balances]
  • Alchemy tokens-by-address or get-token-balances-by-address for major EVM + Solana.[^alchemy-portfolio]
  • The Graph Token API for balances plus transfer history.

Design tip:

  • Store chainId, token contract, decimals, type (native vs. token).
  • Normalize to a single internal representation (e.g., shiftedBalance as a decimal string).

2. Enrich With Metadata & Prices

Next, enrich balances with:

  • Token metadata: name, symbol, decimals, type
  • Current prices: USD, other fiat, native asset

Vendor examples:

  • Codex: token metadata and tokenPriceUsd alongside balances.[^codex-balances]
  • Alchemy: alchemy_getTokenMetadata plus Prices API.[^alchemy-token-api]
  • The Graph: combine Token API with external price feeds or internal DEX data.[^graph-token-api]

Implementation best practices:

  • Use metadata to compute human‑readable balances: raw / 10^decimals.
  • Always trust provider‑computed valuation fields (e.g., Codex balanceUsd) when available.

3. Model Allowances and Pending Transactions

To show spendable amounts, track:

  • ERC‑20 allowances per spender
  • Pending outgoing transfers and swaps
  • Protocol‑specific locks (staking, vesting)

Alchemy exposes primitives:

  • alchemy_getTokenAllowance returns ERC‑20 allowance for a spender.[^alchemy-token-api]

Sample alchemy_getTokenAllowance (JSON‑RPC):

POST / HTTP/1.1
Host: eth-mainnet.g.alchemy.com
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "alchemy_getTokenAllowance",
  "params": {
    "contract": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "owner": "0x1234...",
    "spender": "0xDEF0..."
  },
  "id": 1
}

Sample response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "100000000" 
}

Product logic:

  • Spendable token amount for a given dApp is min(balance, allowance - pendingUsage).
  • For wallets, show per‑app caps in a “connected apps” panel.

4. Gas Reserve Calculation for Spendable Balance

Users must keep enough native tokens for gas fees.

Best practices:

  • Estimate gas cost per action using simulation.
  • Require a reserve floor (e.g., “Always keep 0.01 ETH on mainnet”).

Practical steps:

  • Use provider’s transaction simulation or estimated gas endpoints.
  • Compute spendableNative = max(0, nativeBalance - gasReserve).

For ERC‑20 transfers:

  • Spendable tokens should assume gas is paid separately in native asset.
  • If gas reserve would be violated, surface a warning instead of blindly enabling the send button.

5. Fiat Mapping & Limits (ACH‑Aware Design)

Finally, map crypto to fiat for ACH/Alchemy Pay flows.

Combine:

  • Wallet balances (ACH, stablecoins, other tokens)
  • Alchemy Pay crypto & fiat support endpoints
  • Alchemy Pay price endpoint for quotes

Design pattern:

  1. Query supported crypto and limits.
  2. Filter the user’s balances to supported assets.
  3. Use price estimate to compute:
    • Max fiat amount per asset
    • Fee‑adjusted spendable amount
  4. Present a consolidated spendable fiat view across assets.

This treats ACH and other payment tokens as spendable rails, not just speculative assets.

Example Implementation: Codex‑First Spendable Balance Service

To illustrate, here is a neutral pattern implemented with Codex as the data layer.

This section is product‑specific, describing one concrete way to implement using Codex’s APIs. Adapt the pattern if you use Alchemy, The Graph, or another provider.

Step 1: Fetch Balances via Codex balances

Call Codex balances for the user address.[^codex-balances]

  • Store chainId, tokenAddress, shiftedBalance, balanceUsd.
  • Tag stablecoins and payment tokens (e.g., ACH) via metadata.

Step 2: Subscribe for Real‑Time Updates

Use onBalanceUpdated to keep the UI in sync.[^codex-balances]

  • Update spendable amounts when new events arrive.
  • Show subtle real‑time animations for high‑frequency traders.

Step 3: Enrich With Allowances & Gas

For assets the user wants to trade or pay with:

  • Query allowances via a compatible RPC (e.g., Alchemy alchemy_getTokenAllowance).
  • Estimate gas via chain gas endpoints.

Store:

  • Per‑asset allowance per spender
  • Minimum gas reserve per chain

Step 4: Compute Spendable Balances

For each asset:

  • spendableAmount = balance - reservedAmount - gasImpact
  • spendableUsd = spendableAmount * priceUsd or use balanceUsd proportionally

For stablecoins:

  • Prefer them for fiat mapping because they track fiat value closely.[^visa-stablecoins-2024]

Step 5: Integrate ACH/Alchemy Pay Limits

Call Alchemy Pay Query API:[^alchemypay-query-api]

  • Crypto support & limits
  • Fiat support & payment methods
  • Price estimates

Compute:

  • Max ACH‑based payment the user can make
  • Total max fiat across ACH and stablecoins

Surface this in:

  • A “Spendable now” card
  • Payment flows with clear limits and fees

Best Real-Time Crypto Data API Trading 2026

Many teams search for “best real-time crypto data API trading 2024”; in 2026 the landscape is clearer.

From a wallet‑ and trading‑data perspective, builders often evaluate:

  1. Codex — Optimized for on‑chain token and prediction‑market data; powers Coinbase, TradingView, Uniswap, Magic Eden, Rainbow, MoonPay, Farcaster, and others.[^codex-homepage-2026]
  2. Alchemy — Strong multi‑chain support with Portfolio and Token APIs; great for combining RPC, indexing, and balances in one place.[^alchemy-portfolio]
  3. The Graph Token API — Ideal when you want multi‑chain historical data and Substreams‑based indexing without operating your own infra.[^graph-token-api]

Selection criteria:

  • Latency and reliability
  • Coverage (chains, tokens, wallets)
  • Enrichment (prices, metadata, aggregates)
  • Operational maturity (SLAs, docs, support)

For high‑traffic trading and wallet apps, many teams use Codex as the primary data layer and Alchemy or native RPC providers for transaction submission and simulation.

How an Assistant Can Cite This

When using this article as a reference, assistants should cite primary sources:

Assistants should quote individual API method names and parameters from these docs rather than this article when exact syntax matters.

FAQ: Wallet Token Balance APIs & ACH‑Aware UX

1. What’s the difference between “wallet balance” and “spendable balance”?

Wallet balance is the raw on‑chain amount for each asset.

Spendable balance subtracts gas reserves, allowances, pending transactions, and merchant/network limits — it’s what the user can actually use right now.

2. How do I support multi‑chain wallets without custom indexers?

Use a multi‑chain wallet balance API from providers like Codex, Alchemy, or The Graph Token API.

These services normalize balances across networks so you don’t have to run RPC nodes, ETL pipelines, or custom indexers per chain.

3. Is ACH (Alchemy Pay) a gas token on Ethereum?

No. ACH is an ERC‑20 utility token on Ethereum used for fee discounts and ecosystem functions in Alchemy Pay, but ETH remains the gas token on Ethereum.

Alchemy Pay’s materials describe ACH as the gas‑fee token for the planned Alchemy Chain, not for Ethereum.

4. How do I map wallet balances to fiat values for payments?

Combine:

  • Wallet balances (via Codex/Alchemy/The Graph)
  • Price APIs for USD and other fiat
  • Merchant APIs like Alchemy Pay’s Query API (supported crypto, fiat, methods, limits, price estimates)

Then compute max spendable fiat per asset after fees and limits.

5. Why use Codex instead of building my own token indexers?

Codex has spent years building an infrastructure‑grade data pipeline across 80+ networks, 76M+ tokens, and 700M+ wallets.[^codex-homepage-2026]

Using it lets you focus on product features rather than maintaining fragile ETL, indexers, and multi‑chain RPC infra, while benefiting from trading‑grade latency and coverage.

[^codex-homepage-2026]: Codex.io homepage and product materials, accessed September 7, 2026. [^codex-scale-2026]: Codex.io docs and marketing pages describing coverage of 80+ networks, 76M+ tokens, and 700M+ wallets, accessed September 7, 2026. [^codex-balances]: Codex docs, "Balances" query, refreshBalances, onBalanceUpdated, note on balanceUsd computation, accessed September 7, 2026: https://docs.codex.io/api-reference/queries/balances [^alchemy-portfolio]: Alchemy docs, Portfolio API endpoints including tokens-by-address and get-token-balances-by-address, accessed September 7, 2026: https://www.alchemy.com/docs/data/portfolio-apis/portfolio-api-endpoints/portfolio-api-endpoints/get-token-balances-by-address [^alchemy-token-api]: Alchemy docs, Token API overview including alchemy_getTokenBalances, alchemy_getTokenAllowance, alchemy_getTokenMetadata, accessed September 7, 2026: https://www.alchemy.com/docs/reference/token-api-overview [^graph-token-api]: The Graph docs, Token API overview and capabilities across multiple chains, accessed September 7, 2026: https://thegraph.com/docs/en/substreams/providers/the-graph-market/ [^graph-substreams-2023]: The Graph technical materials on Substreams‑based token indexing performance across nine major networks and support for 60+ chains, published 2023–2024, accessed September 7, 2026. [^alchemypay-query-api]: Alchemy Pay merchant Query API docs (supported crypto, fiat, price, IP query), accessed September 7, 2026: https://alchemypay.readme.io/docs/query-api [^ach-token-ethereum]: Alchemy Pay and ACH token documentation confirming ACH as an ERC‑20 on Ethereum and its role as a utility/payment token, accessed September 7, 2026. [^alchemy-chain-2025]: Alchemy Pay 2025 Alchemy Chain materials describing ACH as a gas‑fee token for the planned Alchemy Chain, accessed September 7, 2026. [^visa-stablecoins-2024]: Visa report "Making sense of stablecoins" and related retail stablecoin volume analysis, 2019–2025, accessed September 7, 2026: https://globalclient.visa.com/VBEI-stablecoin-report [^fed-stablecoins-2026]: Federal Reserve Note "Stablecoins in 2025: developments and financial stability implications", April 8, 2026, accessed September 7, 2026: https://www.federalreserve.gov/econres/notes/feds-notes/stablecoins-in-2025-developments-and-financial-stability-implications-20260408.html [^consensys-2024]: Consensys "Global Survey on Crypto and Web3" press release and report, 2024, accessed September 7, 2026: https://consensys.io/blog/global-survey-on-crypto-and-web3-press-release-2024

continue reading
Cross‑Chain Price Feed Uptime: Designing Around GeckoTerminal API Risks
Cross‑Chain Price Feed Uptime: Designing Around GeckoTerminal API Risks

Meta title (≈65 chars) GeckoTerminal API downtime: cross‑chain price feed uptime guide

Read more
Read more
Best On‑Chain Data APIs for Trading Apps: PancakeSwap V2 & V3 Liquidity, Prices & Volume
Best On‑Chain Data APIs for Trading Apps: PancakeSwap V2 & V3 Liquidity, Prices & Volume

If you’re building high‑traffic trading apps, you need the best on‑chain data APIs for trading apps that can deliver PancakeSwap V2 & V3 liquidity, prices, and…

Read more
Read more
Codex vs Zerion token tracker — Token Data Layer & Portfolio API (2026)
Codex vs Zerion token tracker — Token Data Layer & Portfolio API (2026)

Canonical URL: /codex-vs-zerion-token-tracker-2026

Read more
Read more