Wallet Auth for LlamaIndex: Condition-Based Access for AI Agents

#ai #python #llm #blockchain

LlamaIndex ships 68 community tool integrations out of the box. Today there is a 69th: llama-index-tools-insumer. Four methods, 33 chains, ECDSA-signed boolean verdicts your agent can verify offline against a public JWKS. Boolean, not balance.

Why an agent needs wallet auth

Autonomous agents increasingly hold wallets, decide what to buy, decide who to trust, and decide when to act. The question "does this wallet meet this specific on-chain condition right now?" is one that agents ask constantly — before discounting, before routing a payment, before admitting a counterparty to a session. Today, most agents answer it by scraping a block explorer, parsing a JSON response, and guessing. That is neither portable nor verifiable.

Wallet auth collapses that question into a single tool call. The agent receives back a cryptographic artifact: a signed yes or no, bound to the exact condition that was evaluated, with a block height and a condition hash. The agent can reason over the result, pass it to a downstream service, or log it for audit — all without ever seeing the raw wallet balance.

What shipped today

One pip install, one ToolSpec, four methods:

pip install llama-index-tools-insumer

The package exposes a single InsumerToolSpec class. Following LlamaIndex convention, each of the four spec_functions becomes a tool the agent can invoke by name:

attest_wallet — run a wallet attestation against one to ten conditions (token balance, NFT ownership, EAS attestation, Farcaster ID). Returns a signed verdict per condition. Maps to POST /v1/attest.
get_trust_profile — fetch a multi-dimensional wallet trust profile (stablecoins, governance, NFTs, staking, plus optional Solana, XRPL, and Bitcoin dimensions). Returns a signed summary. Maps to POST /v1/trust.
list_compliance_templates — discover pre-configured EAS compliance templates (Coinbase Verified Account, Gitcoin Passport, and so on). No API key required.
get_jwks — fetch the public JSON Web Key Set so your agent can verify any signed result offline against the insumer-attest-v1 key.

Drop it into an agent loop

Any LlamaIndex agent that accepts a tool list will accept this one:

from llama_index.tools.insumer import InsumerToolSpec
from llama_index.agent.openai import OpenAIAgent

insumer = InsumerToolSpec(api_key="insr_live_...")

agent = OpenAIAgent.from_tools(
    insumer.to_tool_list(),
    verbose=True,
)

agent.chat(
    "Does wallet 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 "
    "hold at least 100 USDC on Base?"
)

Under the hood the agent picks attest_wallet, fills in the right arguments, receives back a signed boolean, and reasons over it the same way it reasons over anything else a tool returns. The agent never sees — and never needs to know — how the balance was read, from which chain, or whether the answer came from a cache or a live read. It just sees a yes or a no, with a signature attached.

What the API actually returns

A single live attest_wallet call against vitalik.eth checking USDC on Base ≥ 1:

{
  "ok": true,
  "data": {
    "attestation": {
      "id": "ATST-33DCD2AC57859853",
      "pass": true,
      "results": [{"met": true, "conditionHash": "0x...", "blockNumber": "0x..."}],
      "passCount": 1,
      "failCount": 0,
      "attestedAt": "2026-04-16T21:xx:xx.000Z",
      "expiresAt": "2026-04-16T22:xx:xx.000Z"
    },
    "sig": "...",
    "kid": "insumer-attest-v1"
  },
  "meta": {"creditsRemaining": 999, "creditsCharged": 1}
}

The pass field tells you the verdict. The sig + kid let any relying party verify the result offline. The conditionHash binds the signature to the exact condition that was evaluated — tamper with the condition and the signature no longer checks. The raw balance is never in the response.

Boolean, not balance

This is the core differentiator worth spelling out for anyone coming from a block-explorer mindset. Standard on-chain APIs return balances, transaction lists, NFT inventories — the underlying state. The consumer is expected to evaluate the predicate themselves and act on the raw numbers.

Wallet auth inverts that. The caller sends the predicate in, the API evaluates it against the live chain state, and the response is a cryptographically signed yes or no. The balance never crosses the wire. That matters for three reasons:

Privacy by default. An agent that needs to know whether a wallet is a "USDC holder" does not also need to see the exact holdings.
Audit without exposure. The signed verdict is verifiable by any party, forever, without re-reading the chain.
Portability. The attestation is the receipt. It survives outside the agent, outside the session, outside the request context it was issued in.

Why LlamaIndex specifically

LlamaIndex is the second-most-adopted agent framework in Python after LangChain, with 48K GitHub stars and a library of nearly 70 official tool integrations. The plug-in shape — one ToolSpec class, multiple spec_functions, published as a standalone pip package — is exactly the pattern a new integration should follow. Anything else looks out of place.

There is also a langchain-insumer package for LangChain developers, an MCP server for any MCP-aware client (Claude Desktop, Cursor, Cline), and an ElizaOS plugin. The LlamaIndex tool completes the four major agent-framework surfaces. Developers can pick the framework they already use and get the same primitive everywhere.

What makes this different from scraping

A naive answer to "does wallet X hold Y?" is to hit a public RPC, call balanceOf, compare to a threshold, return a boolean. That works once, inside one program, for one caller. The answer is not portable — another service has to trust your service blindly, or repeat the RPC call itself. And if you log the answer, the log is worthless to anyone else.

A signed attestation is different. Any service that holds the verdict can verify it independently, offline, forever, against the published JWKS. The condition hash binds the signature to the exact predicate. The block number records when it was read. An audit log of signed attestations is an audit log anyone can verify — including regulators, counterparties, and future instances of the agent itself.

Free to start

Every new API key ships with enough credits to run end-to-end before you spend anything. Attestations cost 1 credit, trust profiles cost 3 credits. Template discovery and JWKS lookups are free.

curl -X POST https://api.insumermodel.com/v1/keys/create \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "appName": "my-agent", "tier": "free"}'

When a real agent deployment needs more, credits top up via on-chain payment — USDC or USDT on any major EVM chain, USDC on Solana, BTC on Bitcoin — through POST /v1/credits/buy. No Stripe, no signup flow, no fiat rails. Same rails the agents themselves run on.

The three-step primitive

If you take one thing away from this post: wallet auth is read → evaluate → sign. The API reads wallet state from the chain, evaluates it against the caller-specified condition, and signs the verdict. No secrets. No identity-first. No static credentials. The condition is public, the signature binds it to the verdict, and the verdict is the truth — right up until expiresAt, when the agent is free to re-read.

LlamaIndex now gives agents that primitive as a first-class tool. pip install is the whole ceremony.

Canonical URL: https://insumermodel.com/blog/llamaindex-tool-wallet-auth-condition-based-access.html

Package: https://pypi.org/project/llama-index-tools-insumer/

Source: https://github.com/douglasborthwick-crypto/llama-index-tools-insumer