# Crypto Wallet PnL API - Allium Token Prices and Balances (`nabeelbaghoor/crypto-wallet-pnl-token-price-api`) Actor

Crypto wallet and token data from the Allium Realtime APIs: wallet PnL with cost basis, token balances, decoded transactions and transfers, USD holdings history, DEX token prices, OHLC candles, price stats and token search on Ethereum, Solana, Base, Bitcoin and 17 more chains. Bring your own key.

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

## Pricing

from $5.00 / 1,000 token or balance row 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

## Crypto Wallet PnL API - Allium Token Prices and Balances

Export crypto wallet PnL, token balances, decoded transactions, token transfers, USD holdings history and DEX-derived token prices from the Allium Realtime APIs into an Apify dataset with your own Allium API key.

Works with the Allium Realtime (Developer) APIs at api.allium.so. Give the actor a list of tokens or wallets as `chain:address` lines and it returns clean, deduplicated rows you can download as JSON, CSV or Excel, schedule, or feed into portfolio trackers, tax and accounting tools, trading dashboards, research notebooks and AI agents. Bring your own key.

### What it does

- **Wallet PnL**: realized and unrealized profit and loss for a wallet, its total USD balance, and per-token average cost, using the average cost basis method. Solana, Bitcoin, Ethereum, Base, Arbitrum and 11 more chains.
- **Wallet PnL by token**: PnL for one wallet and one token, with the trade history (amount, price, time) behind its average cost.
- **Latest wallet balances**: every fungible token a wallet holds, scaled by decimals, with USD price, USD value and optional DEX liquidity to filter spam tokens.
- **Historical wallet balances**: each balance change of a wallet over a time range, block by block.
- **Wallet holdings history**: the USD value of a wallet over time at 15 second to 1 day intervals, optionally broken down per token.
- **Wallet transactions**: decoded transactions with asset transfers, labels and activities (DEX trades, NFT trades, approvals, bridges, liquidity pool mints and burns).
- **Wallet token transfers**: fungible token transfers sent or received by a wallet, filtered by token and time range.
- **Latest token price, price history, price stats and price at a timestamp**: USD prices computed from on-chain DEX trades with outlier filtering, OHLC candles from 15 seconds to 1 day, 24h and 1h high, low and percent change.
- **Top tokens, token search and token details**: rank tokens by volume, trade count or fully diluted valuation, search by name or symbol, and read supply, FDV, volume, holders count, all-time high and low.
- **Pay only for results**: a token or wallet Allium returns nothing for, and any refused request, is recorded as a free row that says why.

### How to get an API key

Create an account at app.allium.so/join, log in, and generate a key under Settings > API Keys (one key per user). Allium plans are sold through its sales team and the Realtime APIs must be included in yours. Paste the key 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 | `latestPrice`, `priceHistory`, `priceStats`, `priceAtTimestamp`, `listTokens`, `searchTokens`, `tokenDetails`, `tokenTransfers`, `walletTransactions`, `walletBalances`, `balanceHistory`, `holdingsHistory`, `walletPnl` or `walletTokenPnl` |
| `tokens` | token modes | `chain:address` per line, such as `ethereum:0xa0b8...eb48` or `solana:So111...112`; an address alone uses the default chain |
| `wallets` | wallet modes | `chain:address` per line |
| `walletTokens` | PnL by token | `chain:wallet:token` per line |
| `chain` | all | Default chain for lines without one, and the chain for top tokens and search (default `ethereum`) |
| `searchQuery`, `allChains` | search, top tokens | Name or symbol to search; rank or search across every chain |
| `sortBy`, `sortGranularity`, `sortOrder` | search, top tokens | Volume, trade count or FDV; last day or hour; highest or lowest first |
| `minVolumeUsd1d`, `minVolumeUsd1h` | search, top tokens | Minimum USD volume |
| `startTime`, `endTime` | price history, balance history, holdings, transfers | ISO time, date, or lookback such as `24h` or `30d` (default last 7 days) |
| `timeGranularity` | price history, price at timestamp, holdings | `15s`, `1m`, `5m`, `1h` (default) or `1d` |
| `atTimestamp`, `stalenessTolerance` | price at timestamp | The moment to price at; the furthest lookback such as `1h` |
| `withLiquidityInfo` | latest price, balances | Add total DEX liquidity in USD per token |
| `minLiquidityUsd` | PnL, holdings | Leave out tokens below this liquidity |
| `includeTokenBreakdown` | holdings | Per-token USD value at every interval |
| `activityType`, `transactionHash` | transactions | Only one decoded activity type; only one transaction |
| `transferType`, `transferToken`, `sortDirection` | transfers | Sent, received or both; one token; newest or oldest first |
| `maxResults` | all | Row ceiling for the run (default 100, up to 10,000) |
| `requestsPerMinute` | all | Pacing to your plan's rate limit (default 60) |
| `apiKey` | all | Your Allium API key (secret), or set `DATA_API_KEY` |

Chain coverage differs by endpoint (Allium's published list, October 2026): prices on 13 chains (Ethereum, Solana, Base, Arbitrum, Optimism, Polygon, BSC, Avalanche, Celo, Unichain, zkSync, HyperEVM, Robinhood); balances and transactions on 19 (adds Bitcoin, NEAR, Stellar, Monad, X Layer, XDC, Arc); PnL on 16; token lists and search on 12 (adds Bitcoin, Dogecoin and Stellar).

### Example output

```json
{
    "mode": "walletBalances",
    "recordType": "balance",
    "identifier": "ethereum:0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
    "found": true,
    "chain": "ethereum",
    "address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
    "tokenAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "symbol": "USDC",
    "name": "USD Coin",
    "priceUsd": 0.9999,
    "amount": 123.456789,
    "valueUsd": 123.4444,
    "timestamp": "2026-10-01T00:00:00Z",
    "transactionHash": null,
    "note": null,
    "rawBalance": "123456789",
    "decimals": 6,
    "tokenType": "evm_erc20",
    "blockNumber": 23500000,
    "totalLiquidityUsd": "LIQUIDITY_TOO_HIGH",
    "retrievedAt": "2026-10-12T12:00:00.000Z"
}
```

A wallet PnL row adds `realizedPnlUsd`, `unrealizedPnlUsd`, `unrealizedPnlRatioChange`, `tokenCount` and a `tokens` list with each token's average cost, current price and PnL. A transaction row adds `activityTypes`, `labels`, `assetTransfers` and `activities`. A price candle adds `open`, `high`, `low`, `close` and `granularity`.

### FAQ

#### What is Allium?

Allium is an enterprise blockchain data platform. Its Realtime APIs serve token prices, wallet balances, transactions, holdings and PnL across 20+ chains with a few seconds of freshness, and power wallets such as Phantom. This actor calls those APIs with your key.

#### How does Allium calculate wallet PnL?

With the average cost basis method: buys reweight the average cost, sells keep it, and unrealized PnL is the current balance times the current price minus the average cost. Realized PnL accrues at each sale.

#### Where do Allium token prices come from?

From on-chain DEX trades, converted to USD against known tokens, built into candles and returned as a volume-weighted average price, with z-score outlier filtering against arbitrage spikes. A token with no trade in the last 7 days returns no latest price.

#### Which chains does it support?

Ethereum, Solana, Base, Arbitrum, Optimism, Polygon, BNB Smart Chain, Avalanche, Bitcoin, Unichain, zkSync, Celo, HyperEVM, Monad, Robinhood Chain, X Layer, XDC Network, Arc, NEAR, Stellar and Dogecoin, with coverage per endpoint as listed under Input.

#### How do I filter spam tokens out of balances and PnL?

Turn on `withLiquidityInfo` for balances and prices, then drop rows whose `totalLiquidityUsd` is a small number; or set `minLiquidityUsd` for PnL and holdings history so Allium leaves low-liquidity tokens out of the totals.

#### Why did a wallet or token come back as a row with found set to false?

Allium answered nothing for it (no trades, no holdings, an unsupported chain for that endpoint) or refused the request. The `note` says which, and the row is not charged.

#### Can I use Allium Explorer SQL queries with this actor?

No. The Explorer API is enterprise-only and is not wired here; this actor covers the Realtime APIs.

### Pricing

Pay per event, only for rows that carry data:

- **Token or balance row**: $0.005 (prices, candles, stats, tokens, transfers, balances, holdings snapshots)
- **Decoded wallet transaction**: $0.01
- **Wallet PnL row**: $0.015 (by wallet, or by wallet and token)

Empty lookups and refusals are free. Allium bills your own account separately under your Allium plan.

### Terms

Allium's terms limit use of its service and data to the customer's internal business and forbid redistributing or reselling the data. The rows this actor returns belong to your own Allium account and are for your own use; check your Allium order before sharing them.

### Keyword map

crypto wallet PnL API, wallet profit and loss, token price API, DEX token prices, OHLC crypto candles, wallet token balances, historical wallet balances, portfolio value history, decoded wallet transactions, ERC20 transfers, Solana token prices, Allium API, Allium Realtime API, blockchain data API.

BYOK, not live-tested: the routes were checked against Allium's docs and its route table, but no run used a real Allium key.

# Actor input Schema

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

Token modes read the Tokens field; wallet modes read the Wallets field; wallet PnL by token reads the Wallet and token pairs field. Top tokens and token search need neither. Prices come from on-chain DEX trades; PnL uses the average cost basis method.

## `tokens` (type: `array`):

Token modes. One token per line as chain:address (contract address, Solana mint, or the zero address 0x0000000000000000000000000000000000000000 for a native EVM token), or an address alone on the default chain. Sent 200 to a request; up to 1000 per run.

## `wallets` (type: `array`):

Wallet modes. One wallet per line as chain:address, or an address alone on the default chain. The same address on two chains is two lines. Up to 1000 per run.

## `walletTokens` (type: `array`):

Wallet PnL by token mode. One pair per line as chain:wallet:token, or wallet:token on the default chain.

## `chain` (type: `string`):

The chain for lines that do not name one, and the chain top tokens and token search are limited to. Endpoint coverage differs by chain: prices cover 13 chains, balances and transactions 19, PnL 16 (see the README).

## `searchQuery` (type: `string`):

Token search mode. A case-insensitive substring of the token name or symbol, such as usdc or pepe.

## `allChains` (type: `boolean`):

Top tokens and token search. Ignore the default chain and rank or search tokens across every chain.

## `sortBy` (type: `string`):

Top tokens and token search. The field tokens are ranked by.

## `sortGranularity` (type: `string`):

Top tokens and token search. The window volume or trade count is measured over.

## `sortOrder` (type: `string`):

Top tokens and token search.

## `minVolumeUsd1d` (type: `number`):

Top tokens and token search. Only tokens with at least this much USD volume over the last day.

## `minVolumeUsd1h` (type: `number`):

Top tokens and token search. Only tokens with at least this much USD volume over the last hour.

## `startTime` (type: `string`):

Price history, historical balances, holdings history and transfers. An ISO 8601 time (2026-01-01T00:00:00Z), a date (2026-01-01), or a lookback such as 24h or 30d. Empty means 7 days before the end time (no lower bound for transfers).

## `endTime` (type: `string`):

Same forms as the start time. Empty means now (no upper bound for transfers).

## `timeGranularity` (type: `string`):

Price history, price at timestamp and holdings history. Holdings history allows 15s for ranges up to 24 hours (last 7 days only), 5m up to 7 days, 1h up to a year and 1d beyond.

## `atTimestamp` (type: `string`):

Price at timestamp mode. The moment to price the tokens at, in the same forms as the start time. Allium returns the closest earlier price.

## `stalenessTolerance` (type: `string`):

Price at timestamp mode. The furthest back Allium may look for a price, such as 30m, 1h or 1d. Empty uses the provider default.

## `withLiquidityInfo` (type: `boolean`):

Latest token price and latest wallet balances. Adds total DEX liquidity in USD per token (or LIQUIDITY_TOO_HIGH for majors such as WETH), useful to filter spam tokens.

## `minLiquidityUsd` (type: `number`):

Wallet PnL and holdings history. Leave out tokens with less DEX liquidity than this, which drops spam and dust tokens from the totals.

## `includeTokenBreakdown` (type: `boolean`):

Holdings history. Adds the USD value of each token held at every interval.

## `activityType` (type: `string`):

Wallet transactions. Only transactions with this decoded activity. Empty returns every transaction.

## `transactionHash` (type: `string`):

Wallet transactions. Return only this one transaction (hash or Solana signature).

## `transferType` (type: `string`):

Wallet token transfers.

## `transferToken` (type: `string`):

Wallet token transfers. Only transfers of this token contract or mint address.

## `sortDirection` (type: `string`):

Wallet token transfers.

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

The most rows this run returns and charges for. Paged requests ask Allium only for the rows still left.

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

Pacing. Allium answers 429 above your plan limit, which the actor waits out and retries.

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

Your own Allium API key, from Settings > API Keys in the Allium app (app.allium.so). Stored as a secret and sent only in the X-API-KEY header; it is never logged. You can instead set the DATA_API_KEY environment secret.

## Actor input object example

```json
{
  "mode": "latestPrice",
  "tokens": [
    "ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "solana:So11111111111111111111111111111111111111112"
  ],
  "chain": "ethereum",
  "allChains": false,
  "sortBy": "volume",
  "sortGranularity": "1d",
  "sortOrder": "desc",
  "timeGranularity": "1h",
  "withLiquidityInfo": false,
  "includeTokenBreakdown": false,
  "transferType": "any",
  "sortDirection": "desc",
  "maxResults": 100,
  "requestsPerMinute": 60
}
```

# Actor output Schema

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

One row per result, plus uncharged rows for empty or refused lookups.

# 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 = {
    "tokens": [
        "ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "solana:So11111111111111111111111111111111111111112"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("nabeelbaghoor/crypto-wallet-pnl-token-price-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 = { "tokens": [
        "ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
        "solana:So11111111111111111111111111111111111111112",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("nabeelbaghoor/crypto-wallet-pnl-token-price-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 '{
  "tokens": [
    "ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "solana:So11111111111111111111111111111111111111112"
  ]
}' |
apify call nabeelbaghoor/crypto-wallet-pnl-token-price-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nabeelbaghoor/crypto-wallet-pnl-token-price-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/bcLIYKqveEJ3ycKKv/builds/GuPfAfAiDd7m6uXzY/openapi.json