> ## Documentation Index
> Fetch the complete documentation index at: https://rain-sandbox-trial.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 |

<CodeGroup>
  ```swift iOS theme={null}
  // 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")
  }
  ```

  ```kotlin Android theme={null}
  // One token
  val usdc = client.getBalance(
      RainChain.BASE_MAINNET,
      Token.contract("0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"),
  )
  val eth = client.getBalance(RainChain.BASE_MAINNET, Token.Native)

  // Everything on a chain
  val onBase = client.getTokenBalances(RainChain.BASE_MAINNET)

  // Everything, everywhere
  val all = client.getAllBalances()
  all.filter { it.rawAmount.signum() > 0 }.forEach { b ->
      println("${b.chainId} ${b.formatted} ${b.symbol ?: "native"}")
  }
  ```
</CodeGroup>

### 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.

<CodeGroup>
  ```swift iOS theme={null}
  // 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)
  ```

  ```kotlin Android theme={null}
  // First page, newest first
  val page1 = client.getTransactions(RainChain.BASE_MAINNET, limit = 20, offset = 0, order = RainTransactionOrder.DESC)
  // Next page
  val page2 = client.getTransactions(RainChain.BASE_MAINNET, limit = 20, offset = 20, order = RainTransactionOrder.DESC)
  // Oldest first
  val fromStart = client.getTransactions(RainChain.BASE_MAINNET, limit = 20, offset = 0, order = RainTransactionOrder.ASC)
  // Defaults (10 rows, newest first)
  val recent = client.getTransactions(RainChain.BASE_MAINNET)
  ```
</CodeGroup>

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](/sdks/embedded-wallets/features#blockchain-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](/docs/embedded-wallets/card-funding-and-settlement).

## What's next

<Columns cols={2}>
  <Card title="Transaction webhooks and history" icon="webhook" href="/docs/embedded-wallets/transaction-webhooks">
    Server-side views of the same activity, and what's coming at GA.
  </Card>

  <Card title="Receiving funds" icon="arrow-down-to-bracket" href="/docs/embedded-wallets/receiving-funds">
    Detecting deposits with these calls.
  </Card>
</Columns>