Balances and History

Read one token’s balance, every token on a chain, or every chain at once, and page through transaction history in either order.

Balance data comes from the RPC endpoints configured for each chain. Transaction history comes from Rain’s wallet infrastructure and can include transfers that did not originate from your application.

Read balances

Use the balance method that matches the scope you need:v

Method	Returns	Use it for
getBalance(chainId, token)	One Balance	A specific asset on a specific chain
getTokenBalances(chainId)	[Balance]: the native balance, always, plus every non-zero token balance	A per-chain asset list
getAllBalances()	[Balance] across every chain you registered, fetched in parallel	A portfolio view

iOS

// One token
let usdc = try await client.getBalance(
    chainId: RainChain.baseMainnet,
    token: .contract(address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913")
)
let eth = try await client.getBalance(chainId: RainChain.baseMainnet, token: .native)

// Everything on a chain
let onBase = try await client.getTokenBalances(chainId: RainChain.baseMainnet)

// Everything, everywhere
let all = try await client.getAllBalances()
for b in all where b.rawAmount > 0 {
    print(b.chainId, b.formatted, b.symbol ?? b.token.normalizedAddress ?? "native")
}

The Balance object

Field	Description
token	.native or .contract(address)
chainId	The chain the balance belongs to
rawAmount	The exact onchain integer amount
decimals	The token’s decimals, used to scale rawAmount
decimalAmount	rawAmount converted using the token’s decimals
formatted	A display ready string with trailing zeros removed
symbol, name	Token metadata from Rain’s registry, your registered tokens, or the token contract when available

Use rawAmount or decimalAmount for calculations. Use formatted with symbol for display.

Where balances come from

Balance retrieval varies by chain and method.

• getBalance reads directly from the RPC endpoint configured for the chain, so results reflect the latest state returned by that node.

• On Ethereum, Base, and Polygon, including supported testnets, getTokenBalances uses Rain’s wallet infrastructure to discover the tokens held by the wallet.

• On other EVM chains, getTokenBalances checks tokens in Rain’s registry plus any tokens you registered with registerTokens. Tokens outside those lists will not appear until they are registered.

• On Solana, token accounts are discovered directly from the chain, so every token account held by the wallet can appear. Tokens the wallet has never received return a zero balance.

Unknown Solana mints may not include a symbol. Register them with registerTokens to provide consistent metadata.

If no RPC endpoint is configured for a chain, balance requests return RAIN_102.

Transaction history

Use getTransactions to retrieve wallet transfers for a specific chain. Results are returned newest first by default and support offset pagination.

iOS

// First page, newest first
let page1 = try await client.getTransactions(chainId: RainChain.baseMainnet, limit: 20, offset: 0, order: .DESC)
// Next page
let page2 = try await client.getTransactions(chainId: RainChain.baseMainnet, limit: 20, offset: 20, order: .DESC)
// Oldest first
let fromStart = try await client.getTransactions(chainId: RainChain.baseMainnet, limit: 20, offset: 0, order: .ASC)
// Defaults (10 rows, newest first)
let recent = try await client.getTransactions(chainId: RainChain.baseMainnet)

Each request can return up to 100 transactions. Paginate using limit and offset, and stop when a page returns fewer results than requested.

Transaction history is scoped to a single chain. To build a cross chain activity feed, query each chain separately and merge the results by timestamp.

The RainTransaction object

Field	Description
hash	Transaction hash or Solana signature
chainId	The chain where the transaction occurred
from, to	Sender and recipient addresses
value, decimals, rawValue	Transaction amount in display and raw units
asset, tokenAddress	Asset symbol when known and token contract or mint address
category	.external for native asset transfers and .token for token transfers
timestamp, blockNumber	When and where the transaction was confirmed
metadata	Additional provider data when available

To determine direction, compare the wallet address with from and to.

What transaction history includes

Rain wallet history includes incoming and outgoing transfers on supported chains, including transactions that were initiated outside your application, on the chains listed under chain support. Solana history is available on mainnet and devnet.

New transactions may take a short time to appear in history after broadcast. When your application initiates a send, use the returned transaction hash to show the transfer immediately, then reconcile it with getTransactions.

Wallet balance vs card spending power

A wallet balance is not the same as the amount available to spend on a Rain card.

For Rain managed programs, card spending power comes from the user or company’s collateral contract. Retrieve card funding and available spending information from the Rain API.

A card funding experience will typically show both:

1. Wallet balance from the embedded wallet SDK
2. Available card spending power from the Rain API

See Card funding and settlement.

What’s next

Transaction webhooks and history

Server-side views of the same activity, and what’s coming at GA.

Receiving funds

Detecting deposits with these calls.