Get Historical Token Balance

GET

wallet

{wallet}

balance-at

Get historical balance

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

const options = {method: 'GET'};

fetch('https://api.helius.xyz/v1/wallet/{wallet}/balance-at?api-key=', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.helius.xyz/v1/wallet/{wallet}/balance-at?api-key=",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.helius.xyz/v1/wallet/{wallet}/balance-at?api-key="

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.helius.xyz/v1/wallet/{wallet}/balance-at?api-key=")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "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
  }
}

{
  "error": "Exactly one of time, datetime, or slot must be provided",
  "code": 400
}

{
  "error": "API key required. Pass via ?api-key=xxx or X-Api-Key header",
  "code": 401
}

{
  "error": "Invalid wallet address",
  "code": 400,
  "details": "'invalid-address' is not a valid Solana address"
}

{
  "error": "RATE_LIMIT_EXCEEDED",
  "code": 429,
  "details": "Too many requests. Retry after 2 seconds."
}

{
  "error": "INTERNAL_ERROR",
  "code": 500,
  "details": "An unexpected error occurred. Please retry."
}

{
  "error": "UPSTREAM_ERROR",
  "code": 502,
  "details": "Upstream RPC request failed. Please retry."
}

Each request costs 100 credits.

Request Parameters

string

default:"GQUtvPx89ZNCwmvQqFmH59bJcU8fW8siETpaxod7Aydz"

required

Solana wallet address (base58 encoded)

string

default:"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"

required

Token mint address. For native SOL, use So11111111111111111111111111111111111111111.

number

default:"1750000000"

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

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.

number

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

Authorizations

api-key

string

query

required

API key passed as query parameter

Path Parameters

wallet

string

default:GQUtvPx89ZNCwmvQqFmH59bJcU8fW8siETpaxod7Aydz

required

Solana wallet address (base58 encoded)

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

Query Parameters

mint

string

default:EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

required

Token mint address. For native SOL, use So11111111111111111111111111111111111111111.

time

integer

default:1750000000

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

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

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

⌘I

Get historical balance

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

const options = {method: 'GET'};

fetch('https://api.helius.xyz/v1/wallet/{wallet}/balance-at?api-key=', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.helius.xyz/v1/wallet/{wallet}/balance-at?api-key=",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.helius.xyz/v1/wallet/{wallet}/balance-at?api-key="

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.helius.xyz/v1/wallet/{wallet}/balance-at?api-key=")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "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
  }
}

{
  "error": "Exactly one of time, datetime, or slot must be provided",
  "code": 400
}

{
  "error": "API key required. Pass via ?api-key=xxx or X-Api-Key header",
  "code": 401
}

{
  "error": "Invalid wallet address",
  "code": 400,
  "details": "'invalid-address' is not a valid Solana address"
}

{
  "error": "RATE_LIMIT_EXCEEDED",
  "code": 429,
  "details": "Too many requests. Retry after 2 seconds."
}

{
  "error": "INTERNAL_ERROR",
  "code": 500,
  "details": "An unexpected error occurred. Please retry."
}

{
  "error": "UPSTREAM_ERROR",
  "code": 502,
  "details": "Upstream RPC request failed. Please retry."
}

Get Started

Trading

Sending Transactions

Account Management

Request Parameters

Authorizations

Path Parameters

Query Parameters

Response

​Request Parameters

Authorizations

Path Parameters

Query Parameters

Response

Request Parameters