# Wallet Balance API - GoldRush Tokens, Transactions and NFTs (`nabeelbaghoor/wallet-token-balance-nft-blockchain-api`) Actor

Wallet and blockchain data API for GoldRush (Covalent) across 100+ chains: ERC20 token balances with prices, decoded wallet transactions, NFT holdings, token holders, contract event logs, historical portfolio value and chain list. Ethereum, Base, Polygon, BSC, Arbitrum. Bring your own key.

- **URL**: https://apify.com/nabeelbaghoor/wallet-token-balance-nft-blockchain-api.md
- **Developed by:** [Nabeel Hassan](https://apify.com/nabeelbaghoor) (community)
- **Categories:** Developer tools, Business, Automation
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 wallet or token record returneds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Wallet Balance API - GoldRush Tokens, Transactions and NFTs

Export wallet token balances, decoded transaction history, NFT holdings, token holders, contract event logs and historical portfolio value across 100+ blockchains into an Apify dataset with your own GoldRush API key.

Works with the GoldRush Foundational API from Covalent (api.covalenthq.com/v1). The actor turns a list of wallet, token or contract addresses and a list of chains into clean, deduplicated rows you can download as JSON, CSV or Excel, schedule daily, or feed into portfolio trackers, tax and accounting tools, compliance reviews, dashboards and AI agents. Bring your own API key.

### What it does

- **Token balances for a wallet**: every native and ERC20 token an address holds on Ethereum, Base, Polygon, BNB Smart Chain, Arbitrum, Optimism, Avalanche and 100+ other chains, with spot price, fiat value, 24h change, logo and a spam flag. The raw balance is also scaled by the token's decimals for you.
- **Wallet transactions**: decoded transaction history (transactions v3), newest first or oldest first, with value, gas, fees, explorer links, decoded log events and optional internal transfers.
- **NFT holdings for a wallet**: NFT collections and token IDs a wallet holds, with floor prices, metadata, images and attributes, or a fast IDs-only view.
- **Token holders**: every holder of an ERC20 or NFT token contract with balance and share of supply, at the latest block or at a past block height or date.
- **Contract log events**: decoded event logs (Transfer, Swap, Approval and more) a contract emitted over a block range.
- **Historical portfolio value**: a wallet's daily open, high, low and close balance and fiat value per token over the last N days.
- **Supported chains and chain status**: every chain name and ID GoldRush covers, with sync height and data status.
- **Real filters**: quote currency (USD, EUR, GBP, JPY and 12 more), spam token removal, NFT metadata toggle, transaction order, omit log events, internal transfers, holder snapshot block or date, starting and ending block.
- **Pay only for results**: empty lookups and refusals are recorded as a free row that says why, never charged.

### How to get an API key

Sign up on the GoldRush platform (goldrush.dev/platform). A free 14 day trial includes 25,000 API credits a month; paid plans start with the Vibe Coding tier (10,000 credits a month) and Professional (300,000 credits, 50 requests a second). Copy your key from the API Keys page and paste it into the API key field, or set the `DATA_API_KEY` environment secret. This actor never ships a shared key.

### Input

| Field | Used by | What it does |
| --- | --- | --- |
| `mode` | all | `tokenBalances`, `transactions`, `nfts`, `tokenHolders`, `logEvents`, `portfolio`, `chains` or `chainStatus` |
| `addresses` | address modes | Wallet addresses (or ENS, RNS, Lens and Unstoppable names); token contracts for token holders; contracts for log events |
| `chainNames` | address modes | Chains to read each address on, such as `eth-mainnet`, `base-mainnet`, `matic-mainnet` (default Ethereum) |
| `otherChains` | address modes | Any other GoldRush chain name, one per line |
| `quoteCurrency` | balances, transactions, portfolio | Fiat currency for prices and values (default USD) |
| `noSpam` | balances, NFTs | Remove suspected spam tokens (default on) |
| `noNftMetadata` | NFTs | Collections and token IDs only, no metadata |
| `transactionOrder` | transactions | `newest` (default) or `oldest` first |
| `noLogs`, `withInternal` | transactions | Omit decoded log events; include internal transfers |
| `blockHeight`, `snapshotDate`, `noSnapshot` | token holders | Historical snapshot block or date; bypass the cached snapshot |
| `startingBlock`, `endingBlock` | log events | Block range: a number, a hex block, `earliest` or `latest` |
| `days` | portfolio | Days of history (provider default 30) |
| `maxResults` | all | Row ceiling for the run (default 100) |
| `requestsPerMinute` | all | Pacing to your plan's rate limit (default 120) |
| `apiKey` | all | Your GoldRush API key, stored as a secret |

Each chain and address pair is its own lookup. An endpoint only receives the parameters its documentation lists; an input that belongs to another mode is left off with a warning.

Example input, token balances of one wallet on Ethereum and Base in EUR:

```json
{
    "mode": "tokenBalances",
    "addresses": ["vitalik.eth"],
    "chainNames": ["eth-mainnet", "base-mainnet"],
    "quoteCurrency": "EUR",
    "noSpam": true,
    "maxResults": 200
}
```

### Example output

A token balance row. The common columns come first; every field the API documents for a balance item follows unchanged.

```json
{
    "mode": "tokenBalances",
    "recordType": "tokenBalance",
    "identifier": "eth-mainnet vitalik.eth",
    "found": true,
    "chainName": "eth-mainnet",
    "queriedAddress": "vitalik.eth",
    "id": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "name": "USDC",
    "value": 1520.42,
    "quoteCurrency": "USD",
    "date": "2026-09-30T14:22:11Z",
    "balanceFormatted": "1520.5",
    "contract_decimals": 6,
    "contract_name": "USD Coin",
    "contract_ticker_symbol": "USDC",
    "contract_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "supports_erc": ["erc20"],
    "is_native_token": false,
    "type": "stablecoin",
    "is_spam": false,
    "balance": "1520500000",
    "balance_24h": "1520500000",
    "quote_rate": 0.99995,
    "quote": 1520.42,
    "pretty_quote": "$1,520.42",
    "note": null
}
```

Other modes keep their documented fields the same way: transactions carry `tx_hash`, `block_signed_at`, `from_address`, `to_address`, `provider_value` (the raw value in wei), `value_quote`, `fees_paid`, `gas_quote` and `log_events`; holders carry `address`, `balance`, `total_supply` plus `balanceFormatted` and `shareOfSupply`; log events carry `tx_hash`, `log_offset`, `sender_address`, `raw_log_topics` and `decoded`; portfolio points carry the token fields plus `quoteRate`, `openBalance`, `closeBalance`, `closeQuote` and the rest of the daily range.

### FAQ

#### What is the GoldRush API?

GoldRush is Covalent's blockchain data API. It indexes 100+ chains, including Ethereum, Base, Polygon, BNB Smart Chain, Arbitrum, Optimism, Avalanche, Bitcoin and Solana, and serves wallet balances, transactions, NFTs, token holders and decoded event logs through one REST interface.

#### Do I need my own API key?

Yes. The actor reads the GoldRush API with your own key. A run without a key ends straight away with a message that says where to get one, and nothing is charged.

#### How do I get the token balances of a wallet on several chains?

Use the token balances mode, put the wallet address or ENS name in `addresses` and pick every chain in `chainNames`. Each chain is read separately and every token becomes its own row with price and fiat value.

#### How do I export a wallet's full transaction history?

Use the wallet transactions mode. Newest first starts from the most recent page and walks back; oldest first starts from the wallet's first transaction. Raise `maxResults` to read further, and turn on `noLogs` to halve the provider credit cost when you do not need decoded events.

#### How do I list the holders of a token at a past date?

Use the token holders mode with the token contract in `addresses` and a `snapshotDate` or `blockHeight`. Historical snapshots are served on the GoldRush Foundational Chains (Ethereum, Polygon, BSC, Optimism, Base, Gnosis, Arbitrum, Avalanche and others).

#### Which chain names can I use?

The dropdown covers the most used chains. Run the supported chains mode for every chain name and ID, and put any of them in `otherChains`.

#### What do I pay?

Pay per result: 0.005 USD per token balance, NFT collection, token holder, portfolio point or chain record, and 0.008 USD per decoded transaction or log event. Empty lookups and refusals are never charged. Your GoldRush plan's own API credits are used separately.

#### What happens if my key is wrong or my credits run out?

A rejected key (HTTP 401) or spent credits end the run cleanly with a status message that explains what to change. Rate limits (HTTP 429) are waited out and retried. A chain or address the API refuses (HTTP 400 or 404) becomes a free row with the API's own words, and the run moves on.

### Keyword map

wallet balance API, token balances API, ERC20 balance checker, crypto portfolio tracker, wallet transaction history export, decoded transactions, NFT holdings API, NFT wallet API, token holders list, token holder snapshot, contract event logs, decoded event logs, historical portfolio value, multichain blockchain data API, Ethereum, Base, Polygon, BNB Smart Chain, Arbitrum, Optimism data, Covalent API, GoldRush API.

### Terms and data use

Use of the GoldRush API is governed by Covalent's API Terms and GoldRush Terms of Use. They grant a limited, non-exclusive, non-transferable and revocable licence to use the API in your own applications, and they forbid using the API to build a similar or competitive product, reselling or sublicensing access to the service, providing data to a competitor of Covalent, and abusive request volumes. Covalent keeps all rights in its technology and data. Keep the datasets for your own use, and check your GoldRush order form or contact GoldRush sales before redistributing the data. This actor is not affiliated with or endorsed by Covalent.

# Actor input Schema

## `mode` (type: `string`):

Token balances lists every native and ERC20 token a wallet holds with spot prices and fiat value. Wallet transactions reads decoded transaction history (newest or oldest first) with log events and gas. NFT holdings lists the NFT collections and token IDs a wallet holds with metadata. Token holders lists every holder of a token contract with balances, at the latest block or a past block or date. Contract log events reads decoded event logs a contract emitted. Historical portfolio value gives a wallet's daily balance and fiat value per token. Supported chains and Chain status list every chain the API covers.

## `addresses` (type: `array`):

Wallet addresses for token balances, transactions, NFTs and portfolio; token contract addresses for token holders; contract addresses for log events. ENS, RNS, Lens handles and Unstoppable Domains resolve automatically. One per line; each is read on every chain you pick.

## `chainNames` (type: `array`):

The chains to read each address on. Each chain and address pair is its own lookup. Defaults to Ethereum.

## `otherChains` (type: `array`):

Any other GoldRush chain name not in the list above, one per line, such as celo-mainnet or fantom-mainnet. The supported chains mode lists every name.

## `quoteCurrency` (type: `string`):

Fiat currency for prices and values. Token balances, transactions and historical portfolio only.

## `noSpam` (type: `boolean`):

Token balances and NFT holdings only. Drops suspected spam tokens and NFTs (supported on the Foundational Chains).

## `noNftMetadata` (type: `boolean`):

NFT holdings only. Returns just collections and token IDs, without metadata and images. Faster for wallets holding many NFTs.

## `transactionOrder` (type: `string`):

Wallet transactions only. Newest first starts from the most recent page and walks back; oldest first starts from the wallet's first transactions.

## `noLogs` (type: `boolean`):

Wallet transactions only. Leaves out the decoded log events, which halves the provider's credit cost per transaction.

## `withInternal` (type: `boolean`):

Wallet transactions only. Adds internal transfers (traces) on the EVM chains that support them; costs extra provider credits.

## `blockHeight` (type: `string`):

Token holders only. A past block number such as 21000000 for a historical snapshot (Foundational Chains only). Leave empty for the latest.

## `snapshotDate` (type: `string`):

Token holders only. A past date (YYYY-MM-DD) for a historical snapshot (Foundational Chains only). Leave empty for today.

## `noSnapshot` (type: `boolean`):

Token holders only. Skips the last cached snapshot and reads the latest holder list.

## `startingBlock` (type: `string`):

Contract log events only. First block to read: a number, a hex block, or earliest or latest.

## `endingBlock` (type: `string`):

Contract log events only. Last block to read: a number, a hex block, or earliest or latest.

## `days` (type: `integer`):

Historical portfolio value only. Number of days to return; the provider defaults to 30.

## `maxResults` (type: `integer`):

The most rows this run returns and charges for, across all chains and addresses.

## `requestsPerMinute` (type: `integer`):

Pacing. GoldRush allows 4 requests a second on the trial and Vibe Coding plans and 50 on Professional, and answers 429 above it, which the actor waits out and retries.

## `apiKey` (type: `string`):

Your own GoldRush API key, from the API Keys page of your GoldRush platform account (goldrush.dev/platform). Stored as a secret and sent only in the Authorization header; it is never logged. You can instead set the DATA_API_KEY environment secret.

## Actor input object example

```json
{
  "mode": "tokenBalances",
  "addresses": [
    "vitalik.eth"
  ],
  "chainNames": [
    "eth-mainnet"
  ],
  "quoteCurrency": "USD",
  "noSpam": true,
  "noNftMetadata": false,
  "transactionOrder": "newest",
  "noLogs": false,
  "withInternal": false,
  "noSnapshot": false,
  "maxResults": 100,
  "requestsPerMinute": 120
}
```

# Actor output Schema

## `records` (type: `string`):

One row per token balance, transaction, NFT collection, holder, log event, portfolio point or chain.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "addresses": [
        "vitalik.eth"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("nabeelbaghoor/wallet-token-balance-nft-blockchain-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "addresses": ["vitalik.eth"] }

# Run the Actor and wait for it to finish
run = client.actor("nabeelbaghoor/wallet-token-balance-nft-blockchain-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "addresses": [
    "vitalik.eth"
  ]
}' |
apify call nabeelbaghoor/wallet-token-balance-nft-blockchain-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nabeelbaghoor/wallet-token-balance-nft-blockchain-api"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/NpNAUpQpRcn2porep/builds/HC7D0lhaicLsYKg9g/openapi.json