Get historical token balances for address

GoldRush SDK

import { GoldRushClient } from "@covalenthq/client-sdk";

const ApiServices = async () => {
    const client = new GoldRushClient("YOUR_API_KEY");
    const resp = await client.BalanceService.getHistoricalTokenBalancesForWalletAddress({chainName: "chainName", walletAddress: "walletAddress"});
    console.log(resp.data);
};

ApiServices();

{
  "address": "<string>",
  "updated_at": "2023-11-07T05:31:56Z",
  "quote_currency": "<string>",
  "chain_id": 123,
  "chain_name": "<string>",
  "chain_tip_height": 123,
  "chain_tip_signed_at": "2023-11-07T05:31:56Z",
  "items": [
    {
      "contract_decimals": 123,
      "contract_name": "<string>",
      "contract_ticker_symbol": "<string>",
      "contract_address": "<string>",
      "supports_erc": [
        "<string>"
      ],
      "logo_url": "<string>",
      "block_height": 123,
      "last_transferred_block_height": 123,
      "contract_display_name": "<string>",
      "last_transferred_at": "2023-11-07T05:31:56Z",
      "native_token": true,
      "type": "<string>",
      "is_spam": true,
      "balance": "<string>",
      "quote_rate": 123,
      "quote": 123,
      "pretty_quote": "<string>",
      "protocol_metadata": {
        "protocol_name": "<string>"
      },
      "nft_data": [
        {
          "token_id": "<string>",
          "token_balance": "<string>",
          "token_url": "<string>",
          "supports_erc": [
            "<string>"
          ],
          "token_price_wei": "<string>",
          "token_quote_rate_eth": "<string>",
          "original_owner": "<string>",
          "external_data": {
            "name": "<string>",
            "description": "<string>",
            "image": "<string>",
            "image_256": "<string>",
            "image_512": "<string>",
            "image_1024": "<string>",
            "animation_url": "<string>",
            "external_url": "<string>",
            "attributes": [
              {
                "trait_type": "<string>",
                "value": "<string>"
              }
            ],
            "thumbnails": {
              "image_256": "<string>",
              "image_512": "<string>",
              "image_1024": "<string>",
              "image_opengraph_url": "<string>",
              "thumbhash": "<string>"
            },
            "image_preview": "<string>",
            "asset_properties": {
              "asset_width": 123,
              "asset_height": 123,
              "dominant_color": "<string>"
            },
            "owner": "<string>"
          },
          "owner": "<string>",
          "owner_address": "<string>",
          "burned": true
        }
      ]
    }
  ]
}

GET

{chainName}

address

{walletAddress}

historical_balances

GoldRush SDK

import { GoldRushClient } from "@covalenthq/client-sdk";

const ApiServices = async () => {
    const client = new GoldRushClient("YOUR_API_KEY");
    const resp = await client.BalanceService.getHistoricalTokenBalancesForWalletAddress({chainName: "chainName", walletAddress: "walletAddress"});
    console.log(resp.data);
};

ApiServices();

{
  "address": "<string>",
  "updated_at": "2023-11-07T05:31:56Z",
  "quote_currency": "<string>",
  "chain_id": 123,
  "chain_name": "<string>",
  "chain_tip_height": 123,
  "chain_tip_signed_at": "2023-11-07T05:31:56Z",
  "items": [
    {
      "contract_decimals": 123,
      "contract_name": "<string>",
      "contract_ticker_symbol": "<string>",
      "contract_address": "<string>",
      "supports_erc": [
        "<string>"
      ],
      "logo_url": "<string>",
      "block_height": 123,
      "last_transferred_block_height": 123,
      "contract_display_name": "<string>",
      "last_transferred_at": "2023-11-07T05:31:56Z",
      "native_token": true,
      "type": "<string>",
      "is_spam": true,
      "balance": "<string>",
      "quote_rate": 123,
      "quote": 123,
      "pretty_quote": "<string>",
      "protocol_metadata": {
        "protocol_name": "<string>"
      },
      "nft_data": [
        {
          "token_id": "<string>",
          "token_balance": "<string>",
          "token_url": "<string>",
          "supports_erc": [
            "<string>"
          ],
          "token_price_wei": "<string>",
          "token_quote_rate_eth": "<string>",
          "original_owner": "<string>",
          "external_data": {
            "name": "<string>",
            "description": "<string>",
            "image": "<string>",
            "image_256": "<string>",
            "image_512": "<string>",
            "image_1024": "<string>",
            "animation_url": "<string>",
            "external_url": "<string>",
            "attributes": [
              {
                "trait_type": "<string>",
                "value": "<string>"
              }
            ],
            "thumbnails": {
              "image_256": "<string>",
              "image_512": "<string>",
              "image_1024": "<string>",
              "image_opengraph_url": "<string>",
              "thumbhash": "<string>"
            },
            "image_preview": "<string>",
            "asset_properties": {
              "asset_width": 123,
              "asset_height": 123,
              "dominant_color": "<string>"
            },
            "owner": "<string>"
          },
          "owner": "<string>",
          "owner_address": "<string>",
          "burned": true
        }
      ]
    }
  ]
}

Credit Cost

1 per call

Processing

Realtime

Supported on all Foundational Chains.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form: Bearer <token>, where <token> is your GoldRush API Key.

Path Parameters

chainName

string

required

The chain name eg: eth-mainnet.

walletAddress

string

required

The requested address. Passing in an ENS, RNS, Lens Handle, or an Unstoppable Domain resolves automatically.

Query Parameters

quote-currency

string

The currency to convert. Supports USD, CAD, EUR, SGD, INR, JPY, VND, CNY, KRW, RUB, TRY, NGN, ARS, AUD, CHF, and GBP.

no-spam

boolean

If true, the suspected spam tokens are removed. Supported on all Foundational Chains.

block-height

integer

Ending block to define a block range. Omitting this parameter defaults to the latest block height.

date

string

Ending date to define a block range (YYYY-MM-DD). Omitting this parameter defaults to the current date.

Response

200 - application/json

Successful response

address

string

The requested address.

updated_at

string<date-time>

The timestamp when the response was generated. Useful to show data staleness to users.

quote_currency

string

The requested quote currency eg: USD.

chain_id

integer

The requested chain ID eg: 1.

chain_name

string

The requested chain name eg: eth-mainnet.

chain_tip_height

integer

The latest block height of the blockchain at the time this response was provided.

chain_tip_signed_at

string<date-time>

The timestamp of the latest signed block at the time this response was provided.

items

object[]

List of response items.

Show child attributes

items.contract_decimals

integer

Use contract decimals to format the token balance for display purposes - divide the balance by 10^{contract_decimals}.

items.contract_name

string

The string returned by the name() method.

items.contract_ticker_symbol

string

The ticker symbol for this contract. This field is set by a developer and non-unique across a network.

items.contract_address

string

Use the relevant contract_address to lookup prices, logos, token transfers, etc.

items.supports_erc

string[]

A list of supported standard ERC interfaces, eg: ERC20 and ERC721.

items.logo_url

string

The contract logo URL.

items.block_height

integer<int64>

The height of the block.

items.last_transferred_block_height

integer<int64>

The block height when the token was last transferred.

items.contract_display_name

string

items.last_transferred_at

string<date-time>

The timestamp when the token was transferred.

items.native_token

boolean

Indicates if a token is the chain's native gas token, eg: ETH on Ethereum.

items.type

string

One of cryptocurrency, stablecoin, nft or dust.

items.is_spam

boolean

Denotes whether the token is suspected spam.

items.balance

string

b;The asset balance. Use contract_decimals to scale this balance for display purposes.

items.quote_rate

number<double>

The exchange rate for the requested quote currency.

items.quote

number<double>

The current balance converted to fiat in quote-currency.

items.pretty_quote

string

A prettier version of the quote for rendering purposes.

items.protocol_metadata

object

The protocol metadata.

Show child attributes

items.protocol_metadata.protocol_name

string

The name of the protocol.

items.nft_data

object[]

NFT-specific data.

Show child attributes

items.nft_data.token_id

string

b;The token's id.

items.nft_data.token_balance

string

b;The count of the number of NFTs with this ID.

items.nft_data.token_url

string

External URL for additional metadata.

items.nft_data.supports_erc

string[]

A list of supported standard ERC interfaces, eg: ERC20 and ERC721.

items.nft_data.token_price_wei

string

b;The latest price value on chain of the token ID.

items.nft_data.token_quote_rate_eth

string

The latest quote_rate of the token ID denominated in unscaled ETH.

items.nft_data.original_owner

string

The address of the original owner of this NFT.

items.nft_data.external_data

object

Show child attributes

items.nft_data.external_data.name

string

items.nft_data.external_data.description

string

items.nft_data.external_data.image

string

items.nft_data.external_data.image_256

string

items.nft_data.external_data.image_512

string

items.nft_data.external_data.image_1024

string

items.nft_data.external_data.animation_url

string

items.nft_data.external_data.external_url

string

items.nft_data.external_data.attributes

object[]

Show child attributes

items.nft_data.external_data.attributes.trait_type

string

items.nft_data.external_data.attributes.value

string

items.nft_data.external_data.thumbnails

object

Various thumbnails of the asset.

Show child attributes

items.nft_data.external_data.thumbnails.image_256

string

Resized 256x256 image of the asset.

items.nft_data.external_data.thumbnails.image_512

string

Resized 512x512 image of the asset.

items.nft_data.external_data.thumbnails.image_1024

string

Resized 1024x1024 image of the asset.

items.nft_data.external_data.thumbnails.image_opengraph_url

string

Resized image of the asset for OpenGraph.

items.nft_data.external_data.thumbnails.thumbhash

string

Base64 encoded hash of the thumbnail.

items.nft_data.external_data.image_preview

string

The image preview URL.

items.nft_data.external_data.asset_properties

object

The asset properties.

Show child attributes

items.nft_data.external_data.asset_properties.asset_width

integer

The width of the asset.

items.nft_data.external_data.asset_properties.asset_height

integer

The height of the asset.

items.nft_data.external_data.asset_properties.dominant_color

string

The dominant color of the asset.

items.nft_data.external_data.owner

string

items.nft_data.owner

string

The current owner of this NFT.

items.nft_data.owner_address

string

The address of the current owner of this NFT.

items.nft_data.burned

boolean

When set to true, this NFT has been Burned.

Get token balances for address Get native token balance for address

⌘I

GoldRush Foundational API

API Reference

Resources

Credit Cost

Processing

Authorizations

Path Parameters

Query Parameters

Response