# Capabilities Source: https://docs.allium.so/ai/assistant/capabilities Everything the Allium AI Assistant can do, from SQL generation to deploying live web apps. The assistant has access to **12+ tool categories** that it chains together automatically. You don't need to tell it which tools to use - just describe what you want. ## Natural language to SQL The assistant finds the right tables, writes SQL, validates it, and executes it - all from a plain English question. **Example prompt:** ``` What are the top 10 protocols by TVL on Ethereum this week? ``` 1. **Schema search** - searches Allium's database schemas to find relevant tables and columns 2. **Documentation lookup** - checks Allium docs for data model details and best practices 3. **SQL generation** - writes an optimized query using the discovered schemas 4. **Validation** - runs `EXPLAIN` on the query to catch syntax errors before execution 5. **Execution** - runs the query on Allium's Snowflake warehouse (you'll see a confirmation prompt) 6. **Results** - presents the data with a clear summary **Query confirmation** - the assistant asks for your approval before executing SQL queries. You'll see the exact query it wants to run and can approve or reject it. *** ## Dashboards and visualizations Create interactive dashboards from your data with charts, tables, and configurable layouts. **Example prompts:** ``` Create a dashboard showing daily active wallets on Solana vs Ethereum ``` ``` Add a bar chart showing top 10 DEXes by volume to my dashboard ``` 1. **Runs queries** to gather the data 2. **Creates a dashboard** in Allium Explorer with appropriate chart types 3. **Configures visualizations** - line charts for time series, bar charts for comparisons, tables for detailed data 4. **Returns a link** to the dashboard in the Allium App You can iterate on dashboards in the same conversation - add charts, change layouts, or update queries. *** ## Sharing and export Share your analysis with the world or export it for offline use. ### Public links ``` Make this dashboard public and give me the link ``` Creates a shareable URL (`app.allium.so/s2/...`) that anyone can view without logging in. ### Share to X / LinkedIn ``` Share a summary of this analysis on X ``` The assistant generates a **pre-filled post** with: * A summary of key insights (never raw data) * A link to the dashboard * Relevant hashtags You click the generated link to review and post - the assistant never posts on your behalf. ### PDF reports ``` Generate a PDF report of this analysis ``` Creates a downloadable PDF with tables, charts, and text sections. Supports portrait/landscape orientation, custom titles, and subtitles. Download links are valid for **7 days**. *** ## Real-time data Get live token prices, wallet balances, and transaction history without writing SQL. **Example prompts:** ``` What's the current price of ETH? ``` ``` Show me the token balances for vitalik.eth ``` ``` Get the last 50 transactions for this wallet: 0xabc... ``` **Token prices:** * **Latest** - current price for any token * **History** - historical prices with minute/hour/day granularity * **Stats** - 24h/1h high, low, and percent change **Wallet info:** * **Balances** - current token holdings * **Transactions** - recent transaction history * **History** - historical balance snapshots over time *** ## Web search The assistant can search the web for context that isn't in Allium's database. **Example prompts:** ``` What's happening with the Ethereum Pectra upgrade? ``` ``` Find recent news about Uniswap governance proposals ``` Useful for: * **Current events** and market news * **Protocol research** and governance updates * **Context** about new projects or tokens For blockchain-specific data (schemas, tables, on-chain data), the assistant automatically uses Allium's tools instead of web search. *** ## Address lookup Identify wallets and contracts by looking up labels, names, and project associations. **Example prompt:** ``` Who owns this wallet: 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045? ``` Returns: * **Name** and **label** (e.g., "Vitalik Buterin") * **Category** (e.g., "Individual", "DEX", "Bridge") * **Project** association (e.g., "Uniswap", "Aave") * **Chain** information *** ## Organization memory Persistent key-value storage shared across all users in your organization. The assistant remembers preferences, key addresses, and context across sessions. **Example prompts:** ``` Remember that our treasury wallet is 0xabc... ``` ``` What do you know about our organization? ``` See the dedicated [Organization memory](/ai/assistant/memory) page for details. *** ## Data pipelines (Beam) **Feature-gated** - Beam pipelines are available to organizations with the Custom Transforms feature enabled. Contact [support@allium.so](mailto:support@allium.so) to request access. Create real-time data pipelines that stream blockchain events through custom transforms to Kafka topics. **Example prompts:** ``` Create a pipeline that streams Polygon logs and filters for USDC transfer events ``` ``` Deploy my pipeline and show me the Kafka connection details ``` 1. **Creates a pipeline config** with source (chain + entity), transforms (JavaScript or set filters), and sinks (Kafka topics) 2. **Deploys workers** - creates Kafka topics, provisions credentials, and spins up workers 3. **Returns connection details** - Kafka credentials and code snippets (Python and TypeScript) to consume the stream 4. **Monitors health** - check deployment status and worker health anytime Pipeline management is fully conversational - create, update, deploy, teardown, and check stats all through chat. *** ## Live web apps (Vercel) **Feature-gated** - Vercel app deployment requires the feature to be enabled for your organization. Contact [support@allium.so](mailto:support@allium.so) to request access. Deploy interactive Next.js web apps from a conversation. The assistant generates the code and deploys it to Vercel. **Example prompts:** ``` Build me a wallet tracker app for Ethereum and Polygon ``` ``` Create a token price chart for ETH with 24h stats ``` * **Wallet tracker** - track holdings, PnL, and transactions * **Token analytics** - analyze token prices and stats * **Custom dashboard** - SQL-powered dashboard with configurable widgets * **Wallet flows** - Sankey diagram of wallet inflows/outflows * **Price chart** - OHLCV candlestick chart with dynamic coloring and 24h stats 1. **Generates app code** - Next.js app with Allium API integration 2. **Deploys to Vercel** - builds and deploys the app 3. **Returns a claim URL** - you claim ownership with a free Vercel account 4. **Iterate** - read, edit, and redeploy files through conversation After claiming, add your `ALLIUM_API_KEY` in Vercel project settings to connect your app to live data. # Examples Source: https://docs.allium.so/ai/assistant/examples End-to-end workflow walkthroughs showing the assistant's multi-step reasoning. These examples show how the assistant chains multiple tools together to answer complex questions. Each demonstrates a realistic workflow from question to final result. ## From question to dashboard A single question that triggers schema discovery, SQL, execution, visualization, and sharing. ``` Show me stablecoin market share by issuer over the last 90 days, and create a dashboard I can share. ``` The assistant searches for relevant tables and finds `crosschain.dex.trades`. It checks documentation for best practices on stablecoin analysis. ```sql theme={null} SELECT DATE(block_timestamp) AS date, CASE WHEN symbol IN ('USDT', 'USDT.e') THEN 'Tether' WHEN symbol IN ('USDC', 'USDC.e') THEN 'Circle' WHEN symbol = 'DAI' THEN 'MakerDAO' WHEN symbol = 'BUSD' THEN 'Paxos' ELSE 'Other' END AS issuer, SUM(usd_amount) AS daily_volume FROM crosschain.dex.trades WHERE block_timestamp >= CURRENT_TIMESTAMP - INTERVAL '90 days' AND symbol IN ('USDT', 'USDT.e', 'USDC', 'USDC.e', 'DAI', 'BUSD', 'FDUSD', 'TUSD') GROUP BY date, issuer ORDER BY date DESC; ``` The assistant validates this with `EXPLAIN` before asking you to confirm execution. After execution, the assistant: * Creates a dashboard with an **area chart** showing stablecoin volume share over time * Adds a **summary table** with total volume by issuer * Makes the dashboard **public** and returns a share link > Here's your stablecoin market share dashboard for the last 90 days. > Tether leads with 62% of volume, followed by Circle at 28%. > > **Dashboard:** app.allium.so/s2/abc123 > > Want me to share a summary on X? *** ## Real-time portfolio analysis Using real-time APIs (no SQL) to analyze a wallet's holdings. ``` What tokens does vitalik.eth hold? Give me a full breakdown with current values. ``` The assistant resolves `vitalik.eth` to `0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045` and looks up the address label to confirm it's Vitalik Buterin's wallet. Calls the **real-time wallet balances** API to get current token holdings across chains - no SQL query needed. Fetches **current token prices** for all held tokens to calculate USD values and portfolio allocation. > **Vitalik Buterin's Portfolio (Ethereum)** > > | Token | Balance | USD Value | % of Portfolio | > | ----- | ------- | --------- | -------------- | > | ETH | 1,234 | \$3.2M | 45.2% | > | USDC | 890,000 | \$890K | 12.6% | > | ... | ... | ... | ... | > > **Total value:** \~\$7.1M across 24 tokens > > Want me to check balances on other chains too? *** ## Cross-chain comparison Multi-chain analysis using SQL with schema discovery. ``` Compare average gas costs across L2s this month. Show me which L2 is cheapest for a simple transfer. ``` The assistant searches for gas-related schemas across multiple chains. It finds `.raw.transactions` tables and documentation on gas calculation differences between L2s. Writes a `UNION ALL` query across multiple L2 chains (Arbitrum, Optimism, Base, Polygon zkEVM, etc.), calculating average gas cost in USD per simple transfer. > **Average gas cost per transfer (this month)** > > | L2 | Avg Gas Cost | Median | 95th Percentile | > | -------- | ------------ | -------- | --------------- | > | Base | \$0.001 | \$0.0008 | \$0.003 | > | Arbitrum | \$0.003 | \$0.002 | \$0.01 | > | Optimism | \$0.004 | \$0.003 | \$0.012 | > | ... | ... | ... | ... | > > Base is currently the cheapest for simple transfers at \~\$0.001 avg. > > Want me to create a dashboard tracking this over time? *** ## Building on previous context A multi-turn conversation showing how the assistant builds on earlier work. ``` How many daily active wallets does Uniswap have on Ethereum? ``` The assistant finds `ethereum.dex.trades`, writes SQL filtering for Uniswap, and returns daily active wallet counts. ``` Break that down by Uniswap version (v2 vs v3) ``` The assistant **modifies the previous query** to add a version breakdown - no need to re-explain the context. ``` Add Sushiswap and Curve for comparison ``` Expands the query to include multiple DEXes, adjusting the `WHERE` clause and grouping. ``` Create a dashboard with this data ``` Creates a dashboard with: * Line chart of daily active wallets by DEX over time * Stacked bar chart showing version breakdown for Uniswap ``` Make it public and share on X ``` Makes the dashboard public, generates a tweet with key insights and the dashboard link, and returns the X intent URL for you to review and post. # Organization memory Source: https://docs.allium.so/ai/assistant/memory Persistent context shared across all users in your organization. Organization memory lets the assistant **remember things across sessions** - preferences, key addresses, protocols of interest, and workflow conventions. It's shared across all users in your org, so everyone benefits from stored context. ## How it works Organization memory is a **persistent key-value store** shared across your org. Any user can read or write entries, and the assistant proactively uses stored context to give better answers. The assistant: * **Reads memory** at the start of conversations to understand your org's context * **Writes memory** when it learns useful patterns, preferences, or configurations * **Asks for confirmation** before storing anything ## What to store Treasury wallets, contract addresses, multisigs Preferred chains, default time ranges, chart styles Which protocols your org tracks, naming conventions, internal terminology Common query patterns, known data caveats, reusable SQL snippets ## Example usage ### Storing context ``` Remember that our treasury wallet is 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28 ``` ``` Our team focuses on DeFi on Ethereum and Arbitrum. We mainly track Uniswap, Aave, and Compound. ``` ``` When I ask about "our pools", I mean the Uniswap v3 pools where our treasury is an LP. ``` The assistant stores these as key-value entries like: * `treasury_wallet` → `0x742d35Cc6634C0532925a3b844Bc9e7595f2bD28` * `focus_area` → `DeFi on Ethereum and Arbitrum - Uniswap, Aave, Compound` * `our_pools_definition` → `Uniswap v3 pools where treasury wallet is LP` ### Recalling context ``` What do you know about our organization? ``` Returns all stored entries with who last updated each one and when. ``` What's our treasury wallet? ``` The assistant retrieves the specific key and uses it in queries automatically. ### Using memory in analysis Once context is stored, the assistant uses it **proactively**: ``` Show me our treasury balance ``` The assistant knows to look up `0x742d35...` without you specifying the address again. ``` How are our pools performing? ``` It knows "our pools" means Uniswap v3 LP positions for your treasury wallet. ## Limits | Limit | Value | | ----------------------- | --------------------------------------------------- | | **Max entries per org** | 50 | | **Max value size** | 10 KB per entry | | **Scope** | Organization-wide (all users share the same memory) | ## What is NOT stored * **Sensitive personal data** - personal wallets, credentials, private keys * **Session-specific context** - the assistant already remembers everything within a conversation * **Data meant for one user** - memory is org-wide, not per-user Organization memory is shared with **all users** in your org. Don't store anything you wouldn't want every team member to see. ## Managing memory You can manage stored entries through conversation: ``` Delete the "old_contract" entry from memory ``` ``` Update our treasury wallet to 0xnew... ``` ``` Show me everything in org memory ``` The assistant asks for confirmation before any updates or deletions. # Assistant Source: https://docs.allium.so/ai/assistant/overview An AI-powered blockchain data analyst built into the Allium App. Ask questions in plain English, get SQL queries, dashboards, reports, and live data. The Allium AI Assistant is an **agentic blockchain data analyst** built into [app.allium.so](https://app.allium.so/assistant). It goes beyond simple SQL generation - it can search schemas, write and execute queries, create dashboards, share results, look up wallets, generate PDF reports, and even deploy live web apps, all through natural language conversation. AI Assistant chat interface showing a multi-step analytical workflow ## Capabilities Schema discovery, SQL generation, validation, and execution with confirmation flow Create interactive dashboards with charts, then share them publicly Public links, share to X/LinkedIn, PDF reports Token prices, wallet balances, and transaction history - no SQL needed Persistent context shared across your entire org Current events, market context, and protocol research Create real-time data pipelines with natural language Deploy interactive Next.js apps from conversation ## Getting started Click the **Assistant** icon in the sidebar of the [Allium App](https://app.allium.so). AI Assistant sidebar panel in Allium App Type your question in plain English. The assistant plans and executes the steps needed to answer it. **Example questions:** * "Show me DEX volume by chain for the last 30 days" * "What are the top 10 tokens by trading volume on Ethereum?" * "Create a dashboard showing daily active wallets on Solana" * "What's the current price of ETH?" * "Look up this wallet: 0xabc..." Continue the conversation to drill deeper. The assistant remembers your full session context, so you can say things like "break that down by DEX" or "add a chart for that" without repeating yourself. ## Example workflow **Question:** > Show me DEX trading volume by blockchain over the last 90 days and create a dashboard for it. **What the assistant does:** 1. **Searches schemas** to find the right tables (`crosschain.dex.trades`) 2. **Writes and validates SQL:** ```sql theme={null} SELECT DATE(block_timestamp) AS date, chain, SUM(usd_amount) AS usd_volume, COUNT(DISTINCT transaction_from_address) AS traders FROM crosschain.dex.trades WHERE block_timestamp >= CURRENT_TIMESTAMP - INTERVAL '90 days' GROUP BY date, chain ORDER BY date DESC; ``` 3. **Executes the query** and returns results 4. **Creates a dashboard** with charts visualizing volume and trader counts by chain 5. **Shares a link** so you can access the dashboard anytime See [Examples](/ai/assistant/examples) for more detailed end-to-end walkthroughs. ## Tips The more precise your question, the better the assistant can find the right schemas and write accurate queries. The assistant handles multi-step workflows automatically. Ask for the end result and let it figure out the steps. Build on previous results in the same conversation - refine queries, add filters, or request visualizations. Always review generated queries and dashboards to ensure they match your requirements. ## Need help? For specific queries or deeper insights beyond the AI Assistant, reach out to [support@allium.so](mailto:support@allium.so). We're happy to set up a Slack or Telegram channel for easy communication. # Agent Skills Source: https://docs.allium.so/ai/machine-payments/agent-skills Give your AI agent blockchain data access with machine payments in one command. Agent skills let your AI agent query Allium's blockchain data using machine payments — without writing any payment boilerplate. Install the skills, run your agent, and ask questions in natural language. This works with both Tempo MPP and x402 under the hood. ## Setup ```bash theme={null} npx skills add allium-labs/skills --yes ``` Start Claude Code or any compatible agent and ask about Allium data. That's it. The agent skills handle wallet management, payment signing, and API calls automatically. ## Example Queries Once the skills are installed, try asking your agent: "Fetch the latest price for SOL" "Analyze tokenized asset and RWA activity using Allium Explorer" The agent will use the installed skills to make paid API calls to Allium, handling the full payment flow transparently. ## How It Works When your agent receives a query about blockchain data: 1. The agent skill identifies the relevant Allium API endpoint 2. It makes the API request and receives a `402 Payment Required` response 3. The skill automatically signs a USDC payment authorization 4. It retries the request with the payment attached 5. The agent receives the data and presents it to you All of this happens within the agent's tool execution — you just see the results. ## Related Resources The simplest programmatic integration Full manual control over the payment flow # Endpoints & Pricing Source: https://docs.allium.so/ai/machine-payments/endpoints-pricing All payment-enabled endpoints, pricing, rate limits, and error codes. All endpoints below are accessible via machine payments at `https://agents.allium.so`. No API key needed — pay with USDC using [Tempo MPP](/ai/machine-payments/tempo-mpp) or [x402](/ai/machine-payments/x402). All calls are priced individually. No subscription, no minimum spend. ## Install allium-cli CLI commands require **[allium-cli](https://github.com/Allium-Science/allium-cli)**: ```bash theme={null} curl -sSL https://agents.allium.so/cli/install.sh | sh ``` ## Supported Chains Discovery Check which chains each endpoint supports. **This endpoint is free** — no payment required. ```bash theme={null} curl "https://agents.allium.so/api/v1/supported-chains/realtime-apis/simple" ``` Returns a map of endpoint path to supported chain names. Call once per session and cache the result. *** ## Realtime API ### Prices | CLI Command | Method | Endpoint | Cost | Description | | ------------------------------------- | ------ | --------------------------------------- | ------ | ----------------------------------- | | `allium realtime prices latest` | POST | `/api/v1/developer/prices` | \$0.02 | Get latest token prices | | `allium realtime prices at-timestamp` | POST | `/api/v1/developer/prices/at-timestamp` | \$0.02 | Get token prices at a specific time | | `allium realtime prices history` | POST | `/api/v1/developer/prices/history` | \$0.02 | Get historical token price series | | `allium realtime prices stats` | POST | `/api/v1/developer/prices/stats` | \$0.02 | Get token price statistics | ### Tokens | CLI Command | Method | Endpoint | Cost | Description | | -------------------------------------- | ------ | ---------------------------------------- | ------ | ----------------------------------- | | `allium realtime tokens search` | GET | `/api/v1/developer/tokens/search` | \$0.03 | Search tokens by name or symbol | | `allium realtime tokens chain-address` | POST | `/api/v1/developer/tokens/chain-address` | \$0.02 | Look up tokens by chain and address | | `allium realtime tokens list` | GET | `/api/v1/developer/tokens` | \$0.03 | List all supported tokens | ### Wallets | CLI Command | Method | Endpoint | Cost | Description | | ---------------------------------- | ------ | ------------------------------------------- | ------ | --------------------------------- | | `allium realtime balances latest` | POST | `/api/v1/developer/wallet/balances` | \$0.03 | Get current wallet token balances | | `allium realtime balances history` | POST | `/api/v1/developer/wallet/balances/history` | \$0.03 | Get historical wallet balances | | `allium realtime transactions` | POST | `/api/v1/developer/wallet/transactions` | \$0.03 | Get wallet transaction history | | `allium realtime pnl` | POST | `/api/v1/developer/wallet/pnl` | \$0.03 | Get wallet profit and loss | *** ## Explorer API The Explorer API is also available via machine payments. The `run-sql` endpoint uses machine payments auth directly. The remaining Explorer endpoints (`run`, `status`, `results`) require API key authentication. | CLI Command | Method | Endpoint | Cost | Auth | Description | | ------------------------- | ------ | ----------------------------------------------- | ------- | ---------------- | ---------------------------------- | | `allium explorer run-sql` | POST | `/api/v1/explorer/queries/run-async` | \$0.01 | Machine payments | Submit raw SQL for async execution | | `allium explorer run` | POST | `/api/v1/explorer/queries/{query_id}/run-async` | \$0.01 | API key | Run a saved query asynchronously | | `allium explorer status` | GET | `/api/v1/explorer/query-runs/{run_id}/status` | \$0.01 | API key | Check status of a query run | | `allium explorer results` | GET | `/api/v1/explorer/query-runs/{run_id}/results` | dynamic | API key | Fetch results of a completed query | *** ## Supported Networks | Protocol | Network | USDC Address | | ------------- | ----------------- | ---------------------------------------------- | | **Tempo MPP** | Tempo (mainnet) | `0x20c000000000000000000000b9537d11c60e8b50` | | **x402** | Base (mainnet) | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | | **x402** | Polygon (mainnet) | `0x3c499c542cEF5E3811e1192ce70d8cc03d5c3359` | | **x402** | Solana (mainnet) | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | | **x402** | X Layer (mainnet) | `0x74b7f16337b8972027f6196a17a631ac6de26d22` | ## Rate Limits Two independent rate limit buckets per wallet. You can max out both simultaneously. | Bucket | Endpoints | Limit | | -------- | --------------------------- | ----------------- | | **Data** | All `/developer/` endpoints | 3 requests/second | | **Docs** | All `/docs/` endpoints | 5 requests/second | Exceeding either limit returns HTTP `429`. Wait 1 second before retrying. *** ## Error Codes | Status | Meaning | What to Do | | ------ | ----------------- | ------------------------------------------------------------------------------------------------- | | 400 | Bad request | Check JSON syntax | | 402 | Payment required | Sign the payment and retry (handled automatically by [Tempo MPP](/ai/machine-payments/tempo-mpp)) | | 422 | Validation failed | Check request format | | 429 | Rate limited | Back off for 1 second | | 500 | Server error | Retry with exponential backoff | # Overview Source: https://docs.allium.so/ai/machine-payments/overview Machine payment protocols for AI agents and developers to access Allium's blockchain data with USDC. Machine payments enable AI agents and developers to pay for blockchain data per request using USDC — no API key, no subscription, no human in the loop. Allium supports two machine payment protocols: | | **Tempo MPP** | **x402** | | -------------- | ------------------------- | ---------------------------- | | **Complexity** | One function call | Manual 402 flow | | **Best for** | Quick integration, agents | Full control, custom signing | | **Setup** | Install SDK + private key | Privy wallet + signing logic | ## Protocols The simplest path — one function call handles the entire payment flow Full manual control over 402 negotiation, EIP-712 signing, and payment ## Agent Skills Don't want to manage payment code? Install pre-built agent skills and let your AI agent query blockchain data with automatic payment. Set up machine payments with AI agents in one command ## Endpoints & Pricing All payment-enabled endpoints, pricing, rate limits, and error codes # Tempo MPP Source: https://docs.allium.so/ai/machine-payments/tempo-mpp The simplest way to make paid API calls — one function call handles the entire 402 payment flow. Tempo Machine Payment Protocol (Tempo MPP) is the simplest way to make paid API calls to Allium. The `Client` wrapper handles the entire 402 negotiation, signing, and retry flow — you just make requests as normal. ## Quickstart with Agent The fastest way to get started — let your AI agent handle setup and payments for you. ```bash theme={null} curl -sSL https://agents.allium.so/cli/install.sh | sh ``` [allium-cli](https://github.com/Allium-Science/allium-cli) is still in early beta. ```bash theme={null} npx skills add allium-labs/skills --yes ``` Start Claude Code, Codex, or any compatible AI agent. ``` Set up Allium and fetch the latest balances for vitalik.eth ``` ## How It Works Make an API request using the Tempo `Client`. The client automatically receives the `402 Payment Required` response, signs a USDC payment authorization, and retries the request. You receive your data with a `200` response. The payment flow is invisible to your code. ## Supported Tokens & Networks Tempo MPP payments use **USDC** on the Tempo network: | Network | USDC Contract Address | | ------------------- | -------------------------------------------- | | **Tempo** (mainnet) | `0x20c000000000000000000000b9537d11c60e8b50` | ## Implementation ### Install ```bash theme={null} pip install "pympp[tempo]" ``` ### Set Up Your Account Create a `TempoAccount` from your private key. This account will sign payments on your behalf. ```bash theme={null} export YOUR_PRIVATE_KEY="your-eth-private-key" ``` ### Make a Paid API Call ```python theme={null} from mpp.client import Client from mpp.methods.tempo import tempo, TempoAccount, ChargeIntent from mpp.methods.tempo._defaults import TESTNET_RPC_URL, TESTNET_CHAIN_ID import os account = TempoAccount.from_key(os.getenv("YOUR_PRIVATE_KEY")) async with Client(methods=[ tempo( account=account, rpc_url=TESTNET_RPC_URL, intents={"charge": ChargeIntent()}, ) ]) as client: response = await client.post( "https://agents.allium.so/api/v1/developer/prices", json=[{"chain": "solana", "token_address": "So11111111111111111111111111111111111111112"}], ) print(response.json()) ``` The `Client` intercepts the `402` response, constructs and signs the payment using your `TempoAccount`, and retries the request automatically. You just see the final `200` response with your data. # x402 Source: https://docs.allium.so/ai/machine-payments/x402 Full manual control over 402 payment negotiation, EIP-712 signing, and USDC settlement. x402 is Allium's micropayment protocol that gives you full control over the payment flow. Your client handles the `402 Payment Required` negotiation, constructs EIP-712 typed data, signs via a wallet provider, and retries the request with a payment signature. ## Quickstart with Agent The fastest way to get started — let your AI agent handle setup and payments for you. ```bash theme={null} curl -sSL https://agents.allium.so/cli/install.sh | sh ``` [allium-cli](https://github.com/Allium-Science/allium-cli) is still in early beta. ```bash theme={null} npx skills add allium-labs/skills --yes ``` Start Claude Code, Codex, or any compatible AI agent. ``` Set up Allium and fetch the latest balances for vitalik.eth ``` ## How It Works Make a normal API request to any payment-enabled endpoint. The server responds with `402 Payment Required` and an `accepts` array of payment options. Your client constructs and signs an EIP-712 payment authorization via [Privy server wallets](https://docs.privy.io/api-reference/wallets/ethereum/eth-signtypeddata-v4) — no private keys or gas needed. Resend the original request with the payment signature header attached. Allium verifies the authorization and settles the USDC payment onchain via the network's x402 facilitator — [Coinbase](https://docs.cdp.coinbase.com/api-reference/v2/rest-api/x402-facilitator/x402-facilitator) for Base, Polygon, and Solana, [OKX](https://www.okx.com/x-layer) for X Layer. Payment confirmed — you receive your data with a `200` response. ## Supported Tokens & Networks x402 payments use **USDC** on the following networks: | Network | USDC Contract Address | EIP-712 Domain | | --------------------- | ---------------------------------------------- | ------------------------------ | | **Base** (mainnet) | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | name: `USD Coin`, version: `2` | | **Polygon** (mainnet) | `0x3c499c542cEF5E3811e1192ce70d8cc03d5c3359` | name: `USD Coin`, version: `2` | | **Solana** (mainnet) | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | name: `USDC`, version: `2` | | **X Layer** (mainnet) | `0x74b7f16337b8972027f6196a17a631ac6de26d22` | name: `USD Coin`, version: `2` | ## Implementation This guide uses **[Privy](https://dashboard.privy.io) server wallets** for signing. Privy handles wallet creation and EIP-712 signing via its API — you never touch private keys or pay gas. ### Prerequisites * **Python 3.8+** * **[Privy](https://dashboard.privy.io) account** — free, takes 30 seconds * **USDC** on Base or Solana (mainnet) ### 1. Set Up Privy Go to [dashboard.privy.io](https://dashboard.privy.io), sign up, and click **Create App**. Copy your **App ID** and **App Secret** from the dialog and store them securely. Go to **Configuration → App settings → Basics → New Secret** to generate a new **App ID** and **App Secret** pair. ```bash theme={null} export PRIVY_APP_ID="your-app-id" export PRIVY_APP_SECRET="your-app-secret" ``` ### 2. Install Dependencies ```bash theme={null} pip install privy-client httpx ``` ### 3. Create a Wallet Create a server-managed wallet on Privy. This wallet will sign x402 payments on your behalf. ```python theme={null} import os from privy import PrivyAPI client = PrivyAPI( app_id=os.environ["PRIVY_APP_ID"], app_secret=os.environ["PRIVY_APP_SECRET"], ) wallet = client.wallets.create(chain_type="ethereum") print(f"Wallet ID: {wallet.id}") print(f"Address: {wallet.address}") ``` Save the wallet ID as an environment variable: ```bash theme={null} export PRIVY_WALLET_ID="your-wallet-id" ``` Fund this wallet address with USDC on Base (or Base Sepolia for testing). If testing, get free testnet USDC from [Circle's faucet](https://faucet.circle.com/). Select **Base Sepolia** as the network. ### 4. Make a Paid API Call Here's a complete working example that fetches the current price of ETH. The `x402_request` helper handles the full payment flow: 1. Send the API request 2. Receive a **402 response** containing an `accepts` array of payment options 3. Select a payment option matching your network (Base or Base Sepolia) 4. **Construct EIP-712 typed data** for a USDC `TransferWithAuthorization` ([EIP-3009](https://eips.ethereum.org/EIPS/eip-3009)) 5. **Sign via Privy** using `eth_signTypedData_v4` 6. Build the x402 v2 `PaymentPayload` and retry with the `PAYMENT-SIGNATURE` header ```python theme={null} import base64 import json import os import secrets import httpx from privy import PrivyAPI PRIVY_APP_ID = os.environ["PRIVY_APP_ID"] PRIVY_APP_SECRET = os.environ["PRIVY_APP_SECRET"] WALLET_ID = os.environ["PRIVY_WALLET_ID"] BASE_URL = "https://agents.allium.so" # "eip155:8453" for Base mainnet, "eip155:84532" for Base Sepolia testnet TARGET_NETWORK = "eip155:84532" privy = PrivyAPI(app_id=PRIVY_APP_ID, app_secret=PRIVY_APP_SECRET) # Retrieve the wallet address — needed for the authorization "from" field wallet = privy.wallets.get(wallet_id=WALLET_ID) WALLET_ADDRESS = wallet.address def x402_request(http, method, url, **kwargs): """Make an API request with automatic x402 payment signed via Privy.""" headers = kwargs.pop("headers", {}) response = http.request(method, url, headers=headers, **kwargs) if response.status_code != 402: return response # The 402 response contains an "accepts" array of payment options, # each specifying a network, amount, asset, and payTo address. # There is no pre-built "typed_data" — the client must construct it. payment_details = response.json() accepts = payment_details.get("accepts", []) # Select the payment option matching our network option = next((a for a in accepts if a["network"] == TARGET_NETWORK), None) if option is None: raise ValueError(f"No payment option for {TARGET_NETWORK}") # Parse chain ID from CAIP-2 network string, e.g. "eip155:84532" -> 84532 chain_id = int(option["network"].split(":")[1]) nonce = "0x" + secrets.token_hex(32) # Construct EIP-712 typed data for USDC TransferWithAuthorization (EIP-3009). # The domain name and version come from the payment option's "extra" field — # these differ per network (Base mainnet: "USD Coin", Base Sepolia: "USDC"). typed_data = { "types": { "EIP712Domain": [ {"name": "name", "type": "string"}, {"name": "version", "type": "string"}, {"name": "chainId", "type": "uint256"}, {"name": "verifyingContract", "type": "address"}, ], "TransferWithAuthorization": [ {"name": "from", "type": "address"}, {"name": "to", "type": "address"}, {"name": "value", "type": "uint256"}, {"name": "validAfter", "type": "uint256"}, {"name": "validBefore", "type": "uint256"}, {"name": "nonce", "type": "bytes32"}, ], }, "domain": { "name": option["extra"]["name"], "version": option["extra"]["version"], "chainId": chain_id, "verifyingContract": option["asset"], }, # Privy expects "primary_type" (snake_case), not "primaryType" (camelCase) "primary_type": "TransferWithAuthorization", "message": { "from": WALLET_ADDRESS, "to": option["payTo"], "value": str(option["amount"]), "validAfter": "0", "validBefore": str(option["maxTimeoutSeconds"]), "nonce": nonce, }, } # Sign with Privy server wallet sign_result = privy.wallets.rpc( wallet_id=WALLET_ID, method="eth_signTypedData_v4", params={"typed_data": typed_data}, ) # Build the x402 v2 PaymentPayload with resource, accepted, and payload fields payment_payload = { "x402Version": payment_details["x402Version"], "resource": { "url": option["resource"], "description": option.get("description", ""), "mimeType": option.get("mimeType", "application/json"), }, "accepted": { "scheme": option["scheme"], "network": option["network"], "amount": str(option["amount"]), "asset": option["asset"], "payTo": option["payTo"], "maxTimeoutSeconds": option["maxTimeoutSeconds"], "extra": option.get("extra", {}), }, "payload": { "signature": sign_result.data.signature, "authorization": { "from": WALLET_ADDRESS, "to": option["payTo"], "value": str(option["amount"]), "validAfter": "0", "validBefore": str(option["maxTimeoutSeconds"]), "nonce": nonce, }, }, } # Base64-encode the payload and send as PAYMENT-SIGNATURE header headers["PAYMENT-SIGNATURE"] = base64.b64encode( json.dumps(payment_payload).encode() ).decode() response = http.request(method, url, headers=headers, **kwargs) return response # Fetch ETH price with httpx.Client(timeout=30.0) as http: result = x402_request( http, "POST", f"{BASE_URL}/api/v1/developer/prices", json=[ { "chain": "ethereum", "token_address": "0x0000000000000000000000000000000000000000", } ], ) print(json.dumps(result.json(), indent=2)) ``` **Expected response:** ```json theme={null} { "items": [ { "timestamp": "2026-02-10T09:27:11Z", "chain": "ethereum", "address": "0x0000000000000000000000000000000000000000", "decimals": 18, "price": 2023.6042396986138, "open": 2023.6042396986138, "high": 2023.6042396986138, "close": 2023.6042396986138, "low": 2023.6042396986138 } ] } ``` ### EIP-712 Domain Configuration The USDC contracts use different EIP-712 domains per network. These values are required when constructing the `TransferWithAuthorization` typed data for signing. They are provided in the 402 response's `accepts[].extra` field. | Network | Domain Name | Version | | ----------- | ----------- | ------- | | **Base** | `USD Coin` | `2` | | **Polygon** | `USD Coin` | `2` | | **Solana** | `USDC` | `2` | | **X Layer** | `USD Coin` | `2` | Privy signs the EIP-712 typed data via `eth_signTypedData_v4`, but the **client must construct** the typed data itself from the 402 response fields. The server does not provide a ready-to-sign `typed_data` object. ### Frontend Integration Building a web app with embedded wallets? Use [Privy's `useX402Fetch` hook](https://docs.privy.io/recipes/x402) for seamless client-side x402 payments in React. # Examples Source: https://docs.allium.so/ai/mcp/examples See what you can build with Allium's MCP Server. ## 3D Stablecoin Transfer Map An interactive 3D globe visualizing real-time stablecoin transfers across chains — built in just a few hours using Claude Code + Allium MCP. View live demo → *** ## Election Prediction Markets Report A research report on 2024 election prediction markets, built directly in Claude. Charts and figures powered by Allium's blockchain data. View report on Claude → # Overview Source: https://docs.allium.so/ai/mcp/overview Query blockchain data from Allium Explorer using MCP. Allium's MCP Server lets your AI agents query blockchain data using structured tool calls—no REST or custom glue code required. Agents can run saved Explorer queries, execute raw SQL, and introspect Allium schemas via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). Allium's MCP URL: `https://mcp.allium.so` **Using a chatbot like ChatGPT, Claude, or Copilot?** See the [Chatbots](#chatbots) section for setup instructions. ## Quick Start Get connected in under 30 seconds: ```bash theme={null} npx @allium-labs/mcp install ``` The installer will prompt you to select your AI tool and enter your API key. It supports Claude Code, Cursor, VS Code, Windsurf, and [10+ other clients](#supported-clients). Generate an API key at [app.allium.so/settings/api-keys](https://app.allium.so/settings/api-keys). Restart your AI tool to load the new MCP server. Ask your agent to query blockchain data—it now has access to 80+ chains via Allium. See the [API Key Authentication](#api-key-authentication) section below for manual configuration instructions. ## Key Benefits No REST API glue code needed—agents use standard MCP tool calls Semantic search and introspection of Allium's data schemas Works with any MCP-compatible agent framework Reliable access to Allium's enterprise-grade blockchain data ## API Key Authentication **Recommended for most users.** API key auth works with all coding agents and MCP clients. Generate a key at [app.allium.so/settings/api-keys](https://app.allium.so/settings/api-keys). ### Automatic Setup The fastest way to get started — works with 13+ clients: ```bash theme={null} npx @allium-labs/mcp install ``` For non-interactive environments (CI/CD, scripts): ```bash theme={null} npx @allium-labs/mcp install --client claude-code --api-key YOUR_KEY --yes ``` ### Supported Clients The installer supports the following clients: **Claude Code, Cursor, Claude Desktop, VS Code (GitHub Copilot), Codex, Cline, RooCline, Windsurf, Warp, Gemini CLI, Goose, Zed, and Opencode.** Don't see your client listed? Reach out to [contact@allium.so](mailto:contact@allium.so) and we'll add support for it. ### Manual Setup If you prefer to configure manually: ```bash theme={null} claude mcp add --scope user --transport http allium https://mcp.allium.so --header "X-API-KEY: " ``` Then restart Claude Code. Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project): ```json theme={null} { "mcpServers": { "allium": { "url": "https://mcp.allium.so", "headers": { "X-API-KEY": "" } } } } ``` Then restart Cursor. Add the server: ```bash theme={null} codex mcp add allium --url https://mcp.allium.so ``` Then add your API key to `~/.codex/config.toml`: ```toml theme={null} [mcp_servers.allium] url = "https://mcp.allium.so" http_headers = { "X-API-KEY" = "" } ``` Then restart Codex. Register tools in your agent configuration: ```json theme={null} { "tools": [ { "name": "explorer_run_query", "server": "https://mcp.allium.so", "headers": { "X-API-KEY": "" } }, { "name": "explorer_run_sql", "server": "https://mcp.allium.so", "headers": { "X-API-KEY": "" } } ] } ``` Add `explorer_fetch_schema` and `explorer_search_schemas` the same way. You can also add any of the [Realtime API tools](/ai/mcp/tools-reference/realtime). For `streamable-http` or other CLI-based setups: ```json theme={null} { "mcpServers": { "allium": { "command": "npx", "args": [ "mcp-remote", "https://mcp.allium.so", "--header", "X-API-KEY:${API_KEY}" ], "env": { "API_KEY": "" } } } } ``` This enables local agent tool streaming with auth injected from environment variables. Configure your MCP client to connect to `https://mcp.allium.so` with the `X-API-KEY` header set to your API key. Most MCP clients support HTTP transport with custom headers. Refer to your client's documentation for specific configuration details. *** ## Chatbots If you're using a coding agent like Claude Code or Cursor, use the [Quick Start](#quick-start) above instead. **Note:** Requires ChatGPT Plus, Pro, or Team plan. MCP is not available on the free plan. ChatGPT supports MCP servers as "Apps," letting you ask questions about on-chain data directly in your chat -- no code required.