GET
/
balances
/
evm
/
{address}
curl --request GET \
  --url https://token-api.thegraph.com/balances/evm/{address} \
  --header 'Authorization: Bearer <token>'
{
  "data": [
    {
      "block_num": 21764208,
      "timestamp": 1738564283,
      "date": "2025-02-03",
      "contract": "0xc944e90c64b2c07662a292be6244bdf05cda44a7",
      "amount": "339640316263000000000000000",
      "decimals": 18,
      "symbol": "GRT",
      "network_id": "mainnet",
      "price_usd": 0.10426804866144047,
      "value_usd": 35413633.023497514
    }
  ]
}

​
Endpoint Overview

Method: GET

Path: /balances/evm/{address}

Retrieves a list of tokens along with the respective balances for the given wallet address.

​
Request Parameters

ParameterTypeDescriptionNotes
address(string, required)The wallet address to query for token balances.Must be a valid hexadecimal address. Example: 0x1234abcd…
network_id(string, optional)Specifies the blockchain network to query.Use this parameter when you need data from a specific EVM-compatible network.
limit(number, optional)The maximum number of records to return.Useful for controlling response size and paginating results.
offset(number, optional)The number of records to skip before returning results.Use together with limit for pagination.
contract(string, optional)The contract from which results are returnedUse to filter for specific token contracts.

​
Response Parameters

ParameterTypeDescriptionNotes
block_num(number)The block number of the most recent balance change for the data queried.Block numbers will differ between blockchains.
timestamp(number)The Unix timestamp, in seconds, of the most recent balance change for the data queried.Equals the number of seconds elapsed since January 1, 1970, 00:00:00 UTC.
date(string)The date of the block from which data was queried.In the format “YYYY-MM-DD”.
contract(string)The contract for the returned token balance.Returned in hexadecimal. Example: 0x1234abcd…
amount(string)The amount of tokens held by the address.Returned as an integer, in the smallest divisible units of the token.
decimals(number)The number of decimal places of precision for the specified token.Use together with amount to determine token amount.
symbol(string)The number of records to skip before returning results.Use together with limit for pagination.
network_id(string)The number of records to skip before returning results.Use together with limit for pagination.

​
Additional Notes:

The field amount returns an integer number. This is the number of smallest divisible units of the token that is held by the address. Use the decimals field to determine how many of those digits are to the right of the decimal point.

For example, the token for Ethereum has 18 decimal places, and the smallest unit of Ether is one Wei. The amount field will return the number of Wei, not the number of Ether. To determine the number of Ether, you would use decimals to determine how far from the last digit the decimal is placed, in this case 18 digits.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

​
address
string
required

EVM wallet address to query

Example:

"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"

Query Parameters

​
network_id
enum<string>
default:mainnet

The Graph Network ID https://thegraph.com/networks

Available options:
mainnet,
arbitrum-one,
base,
bsc,
matic,
optimism
Example:

"mainnet"

​
contract
string
​
limit
integer
default:10

The maximum number of items returned in a single request.

Required range: 1 <= x <= 500
​
page
integer
default:1

The page number of the results to return.

Required range: x >= 1

Response

200 - application/json
Successful Response
​
data
object[]
required
​
statistics
object