--- name: agents.allium.so description: agents.allium.so provides on-chain data APIs for EVM wallets and tokens, covering wallet balance snapshots (current and historical), token metadata, and token price data (current stats, historical OHLC series, and point-in-time prices). All endpoints are single-shot query/response — no streaming or real-time feeds. Coverage is limited to EVM-compatible chains. host: agents.allium.so --- # agents.allium.so Allium is a blockchain data provider offering structured query endpoints for EVM chain data. It serves agents that need wallet portfolio snapshots, token metadata resolution, and historical or aggregated price data. Its distinct characteristic is the combination of wallet-level balance history with token-level price history, enabling portfolio valuation workflows across time. It does not offer swap routing, bridge quotes, or non-EVM chain support. ## When to use this host Use agents.allium.so when an agent needs EVM wallet balance data (current or historical), token metadata resolution, or token price data (current stats, OHLC history, or point-in-time). It is well-suited for portfolio valuation workflows that combine balance history with historical prices. Do not use this host for: real-time or streaming price feeds (no live tick data); non-EVM chains such as Solana or Bitcoin; swap routing or bridge quotes (no DEX aggregation); bulk multi-chain portfolio aggregation in a single call (chain-by-chain requests required); or transaction/transfer event history (balance snapshots only, not transfer logs). For live price feeds, consider a dedicated price oracle or DEX API. For transaction history, consider a chain indexer such as Etherscan or The Graph. ## Capabilities ### Wallet Balance Lookup Retrieves token holdings for EVM wallets, either as a current snapshot on a single chain or as historical balance snapshots across a time range. Provides raw balances, token metadata, and block-level context. - **`fetch-wallet-token-balances`** — Returns all token balances for a given wallet address on a specified chain, including native and ERC-20 tokens with price, decimals, raw balance, and block metadata. - **`fetch-wallet-balance-history`** — Returns historical on-chain balance snapshots for one or more EVM wallet addresses across specified networks, filtered by time range, with per-token block-level detail. ### Token Metadata and Stats Resolves on-chain token metadata including name, decimals, supply, holder count, trading volume, and all-time high/low for a specific contract address on a named chain. - **`fetch-token-by-chain-address`** — Returns token metadata, price, supply, volume, and holder stats for a given contract address on a specified blockchain. ### Token Price Data Provides token price information across three access patterns: aggregated current stats with 1h/24h ranges, historical OHLC candlestick series with configurable granularity, and point-in-time price lookup at a specific UNIX timestamp. - **`fetch-token-price-stats`** — Returns aggregated price statistics for a specified token on a given chain, including latest price, 24h/1h high/low ranges, percent changes, and decimals. - **`fetch-asset-price-history`** — Returns OHLC and average price time series for one or more on-chain token addresses over a specified time range and granularity. - **`fetch-asset-prices-at-timestamp`** — Returns historical token prices at a specific UNIX timestamp for one or more on-chain assets across supported networks, with configurable time granularity. ## Workflows ### Historical Portfolio Valuation *Use when an agent needs to compute the USD value of a wallet's token holdings at a specific point in the past, such as for PnL calculation or historical audit.* 1. **`fetch-wallet-balance-history`** — Retrieve historical token balance snapshots for the wallet at or around the target timestamp to determine what tokens were held and in what quantities. 2. **`fetch-asset-prices-at-timestamp`** — For each token identified in the balance snapshot, fetch the price at the same historical timestamp to compute USD value per holding. ### Current Portfolio Snapshot with Pricing *Use when an agent needs a full picture of a wallet's current holdings on a chain, enriched with up-to-date price range and percent-change data for each token.* 1. **`fetch-wallet-token-balances`** — Fetch all current token balances for the wallet on the target chain, including raw balances and any embedded price data. 2. **`fetch-token-price-stats`** — For tokens where richer price statistics (1h/24h high/low, percent change) are needed, fetch aggregated price stats per token address. ### Token Deep Dive with Price History *Use when an agent needs to fully characterize a token — its metadata, supply, holders — alongside its historical price trajectory over a time window.* 1. **`fetch-token-by-chain-address`** — Resolve token metadata including name, decimals, supply, holder count, and current price for the contract address. 2. **`fetch-asset-price-history`** — Fetch OHLC price series for the same token over the desired time range and granularity to analyze price behavior over time. ## Skill reference ### `fetch-wallet-balance-history` **BalanceTrail – Wallet Balance History** — Returns historical on-chain balance snapshots for one or more EVM wallet addresses across specified networks, filtered by time range, with per-token block-level detail. *Use when:* Use when an agent needs to retrieve historical token balance snapshots for one or more EVM wallet addresses across chains (e.g. Ethereum, Base) within a specific date range, including block-level metadata per balance change. *Not for:* Do not use for real-time or live balance lookups; use a current-balance endpoint instead. Not suitable for non-EVM chains or for transaction history — this returns balance snapshots, not transfer events. **Inputs:** - `chain` (string) — Primary chain identifier for a single-address query (e.g. 'base', 'ethereum'). - `address` (string) — Primary EVM wallet address for a single-address query. - `addresses` (array) — Array of objects each containing 'chain' and 'address' fields, for multi-address queries across one or more networks. - `start_timestamp` (string) — ISO 8601 UTC timestamp defining the start of the historical window (inclusive). - `end_timestamp` (string) — ISO 8601 UTC timestamp defining the end of the historical window (inclusive). **Returns:** Returns an 'items' array of balance snapshots each containing chain, wallet address, token metadata (contract address and type), raw balance as number and string, and block-level metadata (timestamp, number, hash). **Example:** `{"chain":"ethereum","address":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","start_timestamp":"2025-05-15T00:00:00Z","end_timestamp":"2025-06-17T23:59:59Z"}` --- ### `fetch-wallet-token-balances` **Wallet Token Balances** — Returns all token balances for a given wallet address on a specified chain, including native and ERC-20 tokens with price, decimals, raw balance, and block metadata. *Use when:* Use when an agent needs a complete snapshot of a wallet's token holdings on a specific chain, including token prices, raw balances, and the block at which each balance was last recorded. *Not for:* Do not use for cross-chain aggregate portfolio views across multiple chains in a single call; submit one request per chain. Not suitable for real-time streaming balance updates — this is a single-shot lookup. **Inputs:** - `chain` (string, required) — The blockchain network to query (e.g. 'base'). - `address` (string, required) — The wallet address whose token balances are being fetched. **Returns:** Returns an items array where each element contains chain, wallet address, token metadata (name, symbol, price, decimals, type), raw balance in atomic units, and the block timestamp/number/hash at which the balance was last recorded. **Example:** `{"chain": "base", "address": "0x402Feee072D655B85e08f1751AF9ddbCd249521f"}` --- ### `fetch-token-by-chain-address` **Chain Token Resolver** — Returns token metadata, price, supply, volume, and holder stats for a given contract address on a specified blockchain. *Use when:* Use when an agent needs on-chain token details — including current price, decimals, supply, trading volume, trade counts, all-time high/low, and holder count — for a specific token address on a named chain. *Not for:* Do not use for bulk token lookups across many addresses in a single call; this endpoint resolves one token address per request. Not suitable for real-time streaming price feeds. **Inputs:** - `chain` (string, required) — Blockchain identifier for the token (e.g. 'solana', 'ethereum'). - `token_address` (string, required) — Contract or mint address of the token on the specified chain. **Returns:** Returns a single-element array with the token's name, symbol, decimals, USD price, 1h/1d price diffs and volumes, trade counts, all-time high/low, total supply, fully diluted valuation, and holder count. **Example:** `{"chain": "solana", "token_address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"}` --- ### `fetch-token-price-stats` **PricePulse Stats** — Returns aggregated price statistics for a specified token on a given chain, including latest price, 24h/1h high/low ranges, percent changes, and decimals. *Use when:* Use when an agent needs current or recent price statistics for a specific EVM token address on a supported chain, including price range and percent change data for 1h and 24h windows. *Not for:* Do not use for streaming or real-time tick-by-tick price feeds; this is a single-shot aggregated stats snapshot. Not suitable for cross-chain bridge quotes or swap routing. **Inputs:** - `chain` (string, required) — The blockchain network name to query (e.g. 'ethereum'). - `token_address` (string, required) — The EVM contract address of the token to retrieve price stats for. **Returns:** Returns an items array with one object containing the token's mint address, chain, timestamp, latest USD price, 24h and 1h high/low ranges, percent changes, and decimals. **Example:** `{"chain": "ethereum", "token_address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"}` --- ### `fetch-asset-price-history` **Allium Price History** — Returns OHLC and average price time series for one or more on-chain token addresses over a specified time range and granularity. *Use when:* Use when an agent needs historical price data (open, high, low, close, average) for a specific token address on a given chain, with configurable time range and bucket granularity (e.g. 5m, 1h). *Not for:* Do not use for real-time streaming prices or live spot quotes; this endpoint returns historical candlestick data only. **Inputs:** - `chain` (string, required) — The primary chain context for the request (e.g. 'base', 'ethereum'). - `token_address` (string, required) — Contract address of the token to fetch price history for on the primary chain. - `addresses` (array, required) — List of address objects, each with 'chain' and 'token_address' fields, specifying additional tokens to include in the response. - `start_timestamp` (string, required) — ISO 8601 UTC timestamp marking the start of the historical window. - `end_timestamp` (string, required) — ISO 8601 UTC timestamp marking the end of the historical window. - `time_granularity` (string, required) — Bucket size for price aggregation (e.g. '5m', '1h', '1d'). **Returns:** Returns an items array where each entry contains the token mint address, chain, decimals, and a prices array of 5-minute OHLC+average USD price buckets covering the requested window. **Example:** `{"chain": "base", "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "addresses": [{"chain": "ethereum", "token_address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"}], "start_timestamp": "2025-06-17T10:00:00Z", "end_timestamp": "2025-06-17T18:00:00Z", "time_granularity": "5m"}` --- ### `fetch-asset-prices-at-timestamp` **Price at Timestamp** — Returns historical token prices at a specific UNIX timestamp for one or more on-chain assets across supported networks, with configurable time granularity. *Use when:* Use when an agent needs the price of one or more tokens at a specific historical moment (e.g., to value a past trade, compute PnL at a given time, or audit a historical portfolio snapshot). *Not for:* Do not use for real-time or streaming price feeds; use a live price endpoint instead. Not suitable for bulk historical OHLCV series — this returns a single point-in-time price per token. **Inputs:** - `addresses` (array, required) — List of token address objects, each specifying a chain and token_address to look up. - `timestamp` (string, required) — ISO 8601 UTC datetime string specifying the target point in time for price lookup. - `time_granularity` (string, required) — Granularity bucket for price resolution (e.g., '1m' for 1-minute buckets). **Returns:** Returns an items array with USD price, resolved price_timestamp, mint, and chain for each token that had data, plus an optional message listing tokens with no available price at that timestamp. **Example:** `{"addresses": [{"chain": "solana", "token_address": "So11111111111111111111111111111111111111112"}, {"chain": "solana", "token_address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"}], "timestamp": "2025-07-11T14:31:30Z", "time_granularity": "1m"}` ---