> ## Documentation Index
> Fetch the complete documentation index at: https://www.helius.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Historical Token Balance
> Get a wallet's balance of a specific token or native SOL at a past timestamp, datetime, or slot.
Each request costs **100 credits**.
## Request Parameters
Solana wallet address (base58 encoded)
Token mint address. For native SOL, use `So11111111111111111111111111111111111111111`.
Unix timestamp in **seconds**. Returns the balance as of this time. Provide exactly one of `time`, `datetime`, or `slot`.
Datetime string. Accepted formats: `2025-01-10` (UTC midnight), `2025-01-10 19:20:00`,
`2025-01-10T19:20:00` (seconds optional), or with an explicit timezone
(`2025-01-10T19:20:00Z`, `...+02:00`). **Interpreted as UTC unless an explicit
timezone is included.** Provide exactly one of `time`, `datetime`, or `slot`.
Slot number. Returns the balance as of this slot. Exact and deterministic. Provide exactly one of `time`, `datetime`, or `slot`.
## OpenAPI
````yaml openapi/wallet-api/openapi.yaml GET /v1/wallet/{wallet}/balance-at
openapi: 3.0.3
info:
title: Wallet API
description: >
A high-performance REST API for querying Solana wallet data including
balances, transaction history, transfers, and identity information.
## Authentication
All requests require an API key passed either as:
- Query parameter: `?api-key=YOUR_API_KEY`
- Header: `X-Api-Key: YOUR_API_KEY`
version: 1.0.0
contact:
name: API Support
url: https://helius.dev
servers:
- url: https://api.helius.xyz
description: Production server
security:
- ApiKeyQuery: []
- ApiKeyHeader: []
tags:
- name: Identity
description: Lookup wallet identities and known addresses
- name: Balances
description: Query token and NFT balances
- name: History
description: Transaction history and balance changes
- name: Transfers
description: Token transfer activity
- name: Funding
description: Wallet funding information
paths:
/v1/wallet/{wallet}/balance-at:
get:
tags:
- Balances
summary: Get historical balance
description: >
Retrieve a wallet's balance of a specific token (or native SOL) at a
point in the past,
specified as a Unix timestamp, a datetime string, or a slot number.
The balance is read from the wallet's most recent transaction involving
the token **at or
before** the requested point in time — its post-transaction balance,
which by definition
held until the wallet's next transaction. This is an exact value, not an
estimate.
**Exactly one** of `time`, `datetime`, or `slot` must be provided.
`datetime` values
without an explicit timezone are interpreted as **UTC**. For exact,
deterministic results
use `slot` — block times reported by validators can drift by a few
seconds.
For native SOL, pass the pseudo-mint
`So11111111111111111111111111111111111111111` as `mint`.
A wallet with no matching activity at or before the requested point is
**not** an error —
the endpoint returns `200` with `balance: "0"` and `asOf: null`.
`balance` and `balanceRaw` are returned as **strings** to avoid
precision loss on large values.
operationId: getWalletBalanceAt
parameters:
- $ref: '#/components/parameters/WalletAddress'
- name: mint
in: query
required: true
description: >-
Token mint address. For native SOL, use
`So11111111111111111111111111111111111111111`.
schema:
type: string
example: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
- name: time
in: query
description: >-
Unix timestamp in **seconds**. Returns the balance as of this time.
Provide exactly one of `time`, `datetime`, or `slot`.
schema:
type: integer
minimum: 0
example: 1736536800
- name: datetime
in: query
description: >
Datetime string. Accepted formats: `2025-01-10` (UTC midnight),
`2025-01-10 19:20:00`,
`2025-01-10T19:20:00` (seconds optional), or with an explicit
timezone
(`2025-01-10T19:20:00Z`, `...+02:00`). **Interpreted as UTC unless
an explicit
timezone is included.** Provide exactly one of `time`, `datetime`,
or `slot`.
schema:
type: string
example: '2025-01-10 19:20:00'
- name: slot
in: query
description: >-
Slot number. Returns the balance as of this slot. Exact and
deterministic. Provide exactly one of `time`, `datetime`, or `slot`.
schema:
type: integer
minimum: 0
example: 313000000
responses:
'200':
description: Historical balance retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/BalanceAtResponse'
'400':
description: >-
Missing `mint`; invalid mint; zero or more than one of
`time`/`datetime`/`slot`; non-integer `time`/`slot`; or unparseable
`datetime`
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Exactly one of time, datetime, or slot must be provided
code: 400
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Invalid wallet address in the path
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
'502':
description: Upstream RPC error or timeout. Retryable with exponential backoff.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: UPSTREAM_ERROR
code: 502
details: Upstream RPC request failed. Please retry.
components:
parameters:
WalletAddress:
name: wallet
in: path
required: true
description: Solana wallet address (base58 encoded)
schema:
type: string
pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
example: GQUtvPx89ZNCwmvQqFmH59bJcU8fW8siETpaxod7Aydz
schemas:
BalanceAtResponse:
type: object
properties:
wallet:
type: string
description: Echo of the queried wallet address
example: 5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9
mint:
type: string
description: Echo of the queried mint (the SOL pseudo-mint when native)
example: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
isNative:
type: boolean
description: Whether the result is native SOL
example: false
balance:
type: string
description: >-
Human-readable amount as a decimal **string** (not a number, so
large balances don't lose precision). Trailing zeros are trimmed.
example: '284961463.392936'
balanceRaw:
type: string
description: Exact amount in the smallest unit (lamports for SOL), as a string
example: '284961463392936'
decimals:
type: integer
description: Token decimals (9 for SOL)
example: 6
requested:
type: object
description: >-
Echo of the query. When `datetime` is used, `time` is also populated
with the resolved epoch seconds so the UTC interpretation is
visible.
properties:
time:
type: integer
nullable: true
description: >-
Requested time as epoch seconds (also set when `datetime` was
used)
example: 1736536800
slot:
type: integer
nullable: true
description: Requested slot, when `slot` was used
example: null
datetime:
type: string
nullable: true
description: The original datetime string, when `datetime` was used
example: null
required:
- time
- slot
- datetime
asOf:
type: object
nullable: true
description: >-
The transaction the balance was read from. **`null` when the wallet
had no matching transaction at or before the requested point** —
meaning the balance is genuinely `0` (the wallet had not held the
token by then), not an error.
properties:
slot:
type: integer
description: Slot of the transaction
example: 313000000
blockTime:
type: integer
nullable: true
description: Block time of the transaction in Unix seconds (may be null)
example: 1736536794
signature:
type: string
description: Transaction signature
example: 5Cyy7Mh9nVgFq3T8wJp2sKxR4dE6bA1uZoNcLrXmYqUpon
required:
- slot
- signature
required:
- wallet
- mint
- isNative
- balance
- balanceRaw
- decimals
- requested
- asOf
Error:
type: object
properties:
error:
type: string
description: Error message
example: Invalid wallet address
code:
type: integer
description: HTTP status code
example: 400
details:
type: string
description: Additional error details
example: '''invalid-address'' is not a valid Solana address'
required:
- error
- code
responses:
Unauthorized:
description: Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: API key required. Pass via ?api-key=xxx or X-Api-Key header
code: 401
RateLimited:
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: RATE_LIMIT_EXCEEDED
code: 429
details: Too many requests. Retry after 2 seconds.
InternalError:
description: Transient server error. Retryable with exponential backoff.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: INTERNAL_ERROR
code: 500
details: An unexpected error occurred. Please retry.
securitySchemes:
ApiKeyQuery:
type: apiKey
in: query
name: api-key
description: API key passed as query parameter
ApiKeyHeader:
type: apiKey
in: header
name: X-Api-Key
description: API key passed in request header
````