Connect Allium to ChatGPT: Run SQL Queries and Track Wallet Assets

If you need to connect Allium to ChatGPT to query on-chain data, track wallet assets, or automate DeFi data pipelines, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between ChatGPT's tool calling capabilities and Allium's complex REST API. You can either spend weeks building and maintaining this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. (If your team uses Claude, check out our guide on connecting Allium to Claude or explore our broader architectural overview on connecting Allium to AI Agents).

Giving a Large Language Model (LLM) read and write access to massive sets of blockchain data is an engineering challenge. You must handle complex multi-chain data schemas, asynchronous query polling logic, and aggressive rate limits. Every time Allium updates a blockchain schema or adds a new DEX endpoint, you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Allium, connect it natively to ChatGPT, and execute complex on-chain data workflows using natural language.

The Engineering Reality of the Allium API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools over JSON-RPC, the reality of implementing it against vendor APIs is painful. If you decide to build a custom MCP server for Allium, you own the entire API lifecycle.

Here are the specific integration challenges that break standard CRUD assumptions when working with Allium's data platform:

Asynchronous Blockchain Queries

Extracting massive datasets from the blockchain cannot be handled synchronously. When you execute an Allium Explorer query, the API does not wait for the database engine to churn through terabytes of on-chain data and return a response. Instead, you get a run_id. A naive MCP server will try to block the HTTP connection, leading to a timeout and an LLM hallucination. To properly handle this, your MCP server must expose discrete tools to trigger the query, poll the list_all_allium_query_run_status endpoint, and only fetch results when the status hits success.

Multi-Chain Address Resolution

Querying a wallet balance or token price in Allium requires extreme precision. A token address on Ethereum is different from the same token bridged to Polygon. Allium's endpoints often require strict arrays of [chain, address] pairs to prevent data collisions. If your MCP server's JSON schema definitions do not explicitly instruct the LLM to structure these arrays correctly, ChatGPT will send flat lists of addresses, resulting in 400 Bad Request errors.

Strict Rate Limits and Cursors

Allium deals with massive data egress. You will hit rate limits. Factual note on rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Allium API returns an HTTP 429 Too Many Requests, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller (or the orchestrating framework) is strictly responsible for retry and backoff logic. Furthermore, when fetching paginated items like Hyperliquid events or token transfers, you must explicitly instruct the LLM to pass cursor values back unchanged to fetch the next block of records.

sequenceDiagram
    participant LLM as ChatGPT
    participant Server as Truto MCP Server
    participant Upstream as Allium API
    
    LLM->>Server: Call list_all_allium_query_run_results
    Server->>Upstream: GET /v1/explorer/queries/{run_id}/results
    Upstream-->>Server: HTTP 429 Too Many Requests
    Server-->>LLM: JSON-RPC Error (Rate Limited) + IETF Headers
    Note over LLM: Client logic pauses based on ratelimit-reset
    LLM->>Server: Retry list_all_allium_query_run_results
    Server->>Upstream: GET /v1/explorer/queries/{run_id}/results
    Upstream-->>Server: 200 OK + Data
    Server-->>LLM: JSON-RPC Result

Generating a Managed Allium MCP Server

Instead of hardcoding tool definitions, Truto derives them dynamically from the integration's underlying resource definitions and human-readable documentation records. This dynamic, documentation-driven generation ensures that when Allium updates their API, the MCP tools update instantly without code changes.

You can generate an MCP server for your connected Allium instance in two ways.

Method 1: Via the Truto UI

For administrators setting up internal ChatGPT environments, the UI is the fastest path:

1. Navigate to the integrated account page for the Allium connection.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select the desired configuration (name, allowed methods, tags, expiry).
5. Copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4...).

Method 2: Via the Truto API

If you are dynamically provisioning AI agents for your customers, you can generate MCP servers programmatically. Send a POST request to /integrated-account/:id/mcp.

// POST https://api.truto.one/integrated-account/<allium-account-id>/mcp
// Authorization: Bearer <Truto_API_Token>
 
{
  "name": "Allium DeFi Analyst MCP",
  "config": {
    "methods": ["read", "custom"],
    "tags": ["explorer", "wallet"]
  },
  "expires_at": "2026-12-31T23:59:59Z"
}

Truto validates that the integration has tools available, generates a secure cryptographically hashed token stored in Cloudflare KV, and returns the ready-to-use URL.

Connecting the MCP Server to ChatGPT

The URL generated by Truto encodes the specific tenant environment and tool configurations. It is fully self-contained.

Method 1: Via the ChatGPT UI

If you are using ChatGPT Plus, Team, or Enterprise, you can connect the server directly in the browser interface:

1. In ChatGPT, navigate to Settings -> Apps -> Advanced settings.
2. Enable the Developer mode toggle.
3. Under MCP servers / Custom connectors, click to add a new server.
4. Enter a name (e.g., "Allium Blockchain Data").
5. Paste the Truto MCP URL into the Server URL field and click Save.

ChatGPT will immediately send an initialize JSON-RPC handshake followed by a tools/list request, exposing the Allium data capabilities to your chat session.

Method 2: Via Manual Configuration File

If you are connecting an open-source MCP client, Cursor, or building a custom LangGraph agent, you can mount the remote Truto MCP server using the official Server-Sent Events (SSE) bridge package. Update your client's configuration file:

{
  "mcpServers": {
    "allium-truto": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/a1b2c3d4e5f6..."
      ]
    }
  }
}

Hero Tools for Allium

Truto exposes dozens of proxy APIs as LLM tools, effectively flattening the input namespace to handle both query parameters and request bodies dynamically. Here are the highest-leverage operations for Allium.

1. Asynchronous Explorer Queries

Tool: create_a_allium_querie_run_async

This tool triggers a saved SQL query against Allium's data warehouse without waiting for the final payload. It returns a run_id that the LLM uses to track execution. This is critical for heavy analytical workloads like calculating TVL across multiple DEXs.

"Trigger the 'DEX Volume 30D' query using query ID 'q_12345' for the Uniswap v3 protocol. Give me the run ID so we can poll the status."

2. Fetch Query Results

Tool: list_all_allium_query_run_results

Once an async query completes, this tool fetches the paginated rows. Truto automatically injects limit and next_cursor schema descriptions to force the LLM to loop through large result sets safely.

"The query run ID 'run_9876' is complete. Fetch the first 50 results and summarize the top 5 trading pairs by volume."

3. Track Wallet PnL (Profit and Loss)

Tool: create_a_allium_wallet_pnl

Fetches current realized and unrealized PnL metrics for one or more wallet addresses. The request expects an array of objects specifying both the chain and the address, handling the multi-chain mapping perfectly.

"Get the current Profit and Loss metrics for wallet address '0xABCD1234' on the Ethereum chain and '0xEFGH5678' on the Solana chain."

4. Historical Token Pricing

Tool: create_a_allium_token_price_history

Fetches historical OHLC (Open, High, Low, Close) price data for up to 50 token/chain pairs over a specific time window. Excellent for generating market context before agentic decision-making.

"Fetch the daily historical price data for the USDC token on Arbitrum between January 1st and January 31st of this year."

5. Hyperliquid Event History

Tool: create_a_allium_hyperliquid_event

Retrieves granular user event history for a Hyperliquid address, tracking funding payments and non-funding ledger updates. Useful for building programmatic trading audit trails.

"Pull the Hyperliquid funding payment events for user address '0xTRADER99' over the last 72 hours."

6. Deploy Beam Pipelines

Tool: create_a_allium_beam_deployment

Allium Beam allows developers to stream on-chain data directly to Kafka. This tool deploys a predefined pipeline configuration, automatically provisioning Kafka topics and spinning up pipeline workers.

"Deploy the Beam pipeline configuration 'config_xyz' to start streaming zero-lag Ethereum block data to our Kafka cluster."

To view the complete inventory of Allium tools, required schema structures, and detailed JSON representations, visit the Allium integration page.

Workflows in Action

MCP tools become exceptionally powerful when ChatGPT orchestrates them in sequence. Here is how specific engineering and finance personas utilize these toolsets.

Scenario 1: The DeFi Analyst Auditing Wallet Performance

A DeFi analyst needs to understand why a specific fund's wallet performance spiked last week and what assets contributed to the gains.

"Look up the historical PnL for wallet '0xDeFiFund' on Ethereum from the last 7 days. If the unrealized PnL spiked, fetch the historical OHLC prices for the top 3 tokens in that wallet during the same time window to correlate the performance."

Agent Execution Flow:

1. Call create_a_allium_wallet_pnl_history: The agent passes the chain (Ethereum), address (0xDeFiFund), start_timestamp, end_timestamp, and granularity (daily). It receives a time-series array of realized and unrealized PnL.
2. Call create_a_allium_wallet_position: The agent identifies the spike, then calls the position tool to see exactly which DeFi positions (token0, token1, unclaimed_fees) the wallet currently holds.
3. Call create_a_allium_token_price_history: The agent extracts the addresses of the top 3 held tokens and fetches their daily OHLC prices over the 7-day window.

Result: ChatGPT correlates the PnL spike directly to a specific token's 45% price surge and outputs a summarized financial report with the raw on-chain data to back it up.

Scenario 2: The Data Engineer Managing Pipeline Execution

A data engineer needs to adjust a blockchain data pipeline and restart the deployment without manually logging into the Allium control plane.

"Check the health stats for Beam deployment 'config_abc'. If there are any crashing workers, tear down the deployment, update the config to increase the pod size, and redeploy it."

Agent Execution Flow:

1. Call list_all_allium_beam_deployment_stats: The agent passes the config_id and receives a payload containing total_workers, healthy_workers, and arrays identifying crashing_workers and oom_killed_workers.
2. Call delete_a_allium_beam_deployment_by_id: Seeing a crashing worker, the agent tears down the deployment, releasing the Kafka topic bindings.
3. Call update_a_allium_beam_config_by_id: The agent updates the pipeline config, overriding the pod_size attribute.
4. Call create_a_allium_beam_deployment: The agent triggers the idempotent deployment tool, spinning up new workers on the larger pod size.

Result: The pipeline is safely cycled, resized, and redeployed, and ChatGPT confirms the new infrastructure state.

Security and Access Control

When connecting ChatGPT to high-value infrastructure like Allium, security is paramount. Truto provides several mechanisms to lock down the generated MCP server:

• Method Filtering: You can configure the config.methods property to restrict access. Passing ["read"] ensures ChatGPT can only fetch data (like token prices) but cannot execute destructive actions (like tearing down Beam pipelines).
• Tag Filtering: By configuring config.tags, you limit the scope of exposed tools. A server scoped with the wallet tag will only expose wallet balance and PnL tools, keeping the prompt context window small and minimizing hallucination risks.
• Require API Token Auth: Setting require_api_token_auth: true forces the MCP client to pass a valid Truto API token via the Authorization: Bearer header. The server URL alone is no longer enough to invoke tools.
• Auto-Expiration: Using the expires_at attribute schedules a durable cleanup alarm. Cloudflare KV automatically revokes the token, making the server ideal for temporary, session-based AI agent lifecycles.

The Smart Way to Build AI Integrations

Building a custom MCP server requires parsing massive Swagger files, writing pagination loops for multi-chain data arrays, handling aggressive upstream rate limits, and securing JSON-RPC transport layers. The infrastructure maintenance compounds with every endpoint Allium releases.

Truto abstracts the underlying boilerplate. By generating tools dynamically based on documentation records, handling the proxy execution layer natively, and enforcing strict, stateless security rules, Truto allows your engineering team to focus on the LLM reasoning logic - not the REST API plumbing.