Get Historical Token Balance

Get a wallet’s balance of a specific token or native SOL at a past timestamp, datetime, or slot.

GET /v1/wallet/{wallet}/balance-at

Get historical balance

cURL

curl --request GET \
  --url 'https://api.helius.xyz/v1/wallet/{wallet}/balance-at?api-key='

200

{
  "wallet": "5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9",
  "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "isNative": false,
  "balance": "284961463.392936",
  "balanceRaw": "284961463392936",
  "decimals": 6,
  "requested": {
    "time": 1736536800,
    "slot": null,
    "datetime": null
  },
  "asOf": {
    "slot": 313000000,
    "signature": "5Cyy7Mh9nVgFq3T8wJp2sKxR4dE6bA1uZoNcLrXmYqUpon",
    "blockTime": 1736536794
  }
}

Each request costs 100 credits.

Request Parameters

wallet · string · required

Solana wallet address (base58 encoded)

mint · string · required

Token mint address. For native SOL, use So11111111111111111111111111111111111111111.

time · number

Unix timestamp in seconds. Returns the balance as of this time. Provide exactly one of time, datetime, or slot.

datetime · string

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

Slot number. Returns the balance as of this slot. Exact and deterministic. Provide exactly one of time, datetime, or slot.

Authorizations

ApiKeyQueryApiKeyHeader

api-key · string · query · required

API key passed as query parameter

Path Parameters

wallet · string · required

Solana wallet address (base58 encoded)

Pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$

Query Parameters

mint · string · required

Token mint address. For native SOL, use So11111111111111111111111111111111111111111.

time · integer

Unix timestamp in seconds. Returns the balance as of this time. Provide exactly one of time, datetime, or slot.

Required range: x >= 0

datetime · string

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 · integer

Slot number. Returns the balance as of this slot. Exact and deterministic. Provide exactly one of time, datetime, or slot.

Required range: x >= 0

Response

200

application/json

Historical balance retrieved successfully

wallet · string · required

Echo of the queried wallet address

Example:

"5tzFkiKscXHK5ZXCGbXZxdw7gTjjD1mBwuoFbhUvuAi9"

mint · string · required

Echo of the queried mint (the SOL pseudo-mint when native)

Example:

"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"

isNative · boolean · required

Whether the result is native SOL

Example:

false

balance · string · required

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 · string · required

Exact amount in the smallest unit (lamports for SOL), as a string

Example:

"284961463392936"

decimals · integer · required

Token decimals (9 for SOL)

Example:

6

requested · object · required

Echo of the query. When datetime is used, time is also populated with the resolved epoch seconds so the UTC interpretation is visible.

Show child attributes

asOf · object · required

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.

Show child attributes