curl --request GET \
--url https://api.range.org/v1/address/balance \
--header 'X-API-KEY: <api-key>'import requests
url = "https://api.range.org/v1/address/balance"
headers = {"X-API-KEY": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-KEY': '<api-key>'}};
fetch('https://api.range.org/v1/address/balance', 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.range.org/v1/address/balance",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-KEY: <api-key>"
],
]);
$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.range.org/v1/address/balance"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-KEY", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.range.org/v1/address/balance")
.header("X-API-KEY", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.range.org/v1/address/balance")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-KEY"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"balances": {
"native_tokens": [
{
"amount": 1.234567890123,
"amount_string": "1.234567890123456789",
"denom": "eth",
"decimals": 18,
"base_amount": "1234567890123456789",
"usd": 2000.5,
"usd_string": "2000.5",
"name": "Ether",
"symbol": "ETH",
"price": 2000.5,
"price_string": "2000.5",
"verified": true
}
],
"tokens": [
{
"amount": 1.234567890123,
"amount_string": "1.234567890123456789",
"denom": "eth",
"decimals": 18,
"base_amount": "1234567890123456789",
"usd": 2000.5,
"usd_string": "2000.5",
"name": "Ether",
"symbol": "ETH",
"price": 2000.5,
"price_string": "2000.5",
"verified": true
}
]
},
"lookup_status": "ok",
"reason": {
"code": "provider_timeout",
"display": "Provider timed out"
}
}Get Current Token Balances of an Address
Returns token balances of the given address alongside the lookup outcome (lookup_status, and reason when not ok) on every 200. A failed, partial, or unsupported lookup is reported through lookup_status rather than as an empty balance set left indistinguishable from a genuinely empty address. Each entry carries the legacy amount (a JSON number, kept for backwards compatibility) alongside amount_string — the exact, lossless string rendering of that same quantity. Responses are cached for 60 seconds; send Cache-Control: no-cache to force a fresh lookup.
curl --request GET \
--url https://api.range.org/v1/address/balance \
--header 'X-API-KEY: <api-key>'import requests
url = "https://api.range.org/v1/address/balance"
headers = {"X-API-KEY": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-KEY': '<api-key>'}};
fetch('https://api.range.org/v1/address/balance', 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.range.org/v1/address/balance",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-KEY: <api-key>"
],
]);
$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.range.org/v1/address/balance"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-KEY", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.range.org/v1/address/balance")
.header("X-API-KEY", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.range.org/v1/address/balance")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-KEY"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"balances": {
"native_tokens": [
{
"amount": 1.234567890123,
"amount_string": "1.234567890123456789",
"denom": "eth",
"decimals": 18,
"base_amount": "1234567890123456789",
"usd": 2000.5,
"usd_string": "2000.5",
"name": "Ether",
"symbol": "ETH",
"price": 2000.5,
"price_string": "2000.5",
"verified": true
}
],
"tokens": [
{
"amount": 1.234567890123,
"amount_string": "1.234567890123456789",
"denom": "eth",
"decimals": 18,
"base_amount": "1234567890123456789",
"usd": 2000.5,
"usd_string": "2000.5",
"name": "Ether",
"symbol": "ETH",
"price": 2000.5,
"price_string": "2000.5",
"verified": true
}
]
},
"lookup_status": "ok",
"reason": {
"code": "provider_timeout",
"display": "Provider timed out"
}
}Authorizations
Authorization method required to allow user to access the api endpoints.
Query Parameters
Network of Address
Address to search
network type: evm, solana, cosmos, etc.
Comma separated list of token contract addresses
Workspace id to filter this address's balances by that workspace's token whitelist. Omit for the unfiltered response.
Restores the unfiltered response, ignoring the workspace token whitelist. Only meaningful alongside workspace_id.
Response
Token balances of the given address, plus lookup status.
Always present — never null. An empty set (both arrays empty) when lookup_status is unavailable or unsupported, since there is no genuine answer to serve. Populated (fully, on ok, or partly, on partial) otherwise. See ADR-0013: the lookup outcome always travels on lookup_status/reason rather than by changing the shape of this field.
Show child attributes
Show child attributes
Outcome of this balance lookup. ok: fully resolved. partial: the native balance leg failed but token balances resolved and are included. unavailable: the lookup failed entirely — retry may succeed. unsupported: this chain has no readable balance source, evaluated before any lookup was attempted — retrying will not help. Always present, including on a fully successful lookup.
ok, unsupported, unavailable, partial "ok"
Why the lookup did not return ok. Always present as an explicit null on ok/unsupported; populated on partial/unavailable.
Show child attributes
Show child attributes
Was this page helpful?