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

LlamaIndex ships 68 community tool integrations out of the box. Today there is a 69th: llama-index-tools-insumer. Six methods, 33 chains, ECDSA-signed boolean verdicts your agent can verify offline against a public JWKS. Boolean, not balance — and agents can pay for their own key on-chain.

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, agents read raw on-chain state and infer — scraping a block explorer, parsing a JSON response, guessing. That pattern is neither portable nor verifiable.

Wallet auth replaces that entire behavior with a verifiable decision. The agent sends the condition in, the API evaluates it against live chain state, and a cryptographic artifact comes back: a signed yes or no, bound to the exact condition, with a block height and a condition hash. The agent reasons over the verdict, passes it to a downstream service, or logs it for audit — all without ever seeing the raw wallet balance.

For the longer version of the positioning, see Wallet Auth: Gate Any API on Wallet State and Wallet Authentication for AI Agents. This post is about the LlamaIndex surface.

What shipped today

One pip install, one ToolSpec, six methods:

pip install llama-index-tools-insumer

The package exposes a single InsumerToolSpec class. Following LlamaIndex convention, each of the six 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. Perfect first tool call for an agent that needs to pick a KYC primitive on the fly.
• get_jwks — fetch the public JSON Web Key Set. Lets the agent verify any signed result offline against the insumer-attest-v1 key using any standard JWT or JOSE library.
• buy_api_key — let the agent buy its own new API key on-chain with USDC or BTC. No email, no human signup flow. The transaction sender wallet becomes the registered identity. Maps to POST /v1/keys/buy.
• buy_credits — top up credits on the agent’s existing key with a USDC or BTC payment. Maps to POST /v1/credits/buy.

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.

For callers that want the imperative form rather than the agent loop, the whole primitive collapses to three lines:

result = insumer.attest_wallet(wallet=addr, conditions=[condition])
if not result["data"]["attestation"]["pass"]:
    reject()

Same operation. Reject is whatever your app does when a check fails — throw, redirect, refund, gate content, deny the session. The tool doesn’t prescribe the reject path. It just tells you, with a signature, what the right answer is.

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": "...",                         // ECDSA P-256 signature, base64
    "kid": "insumer-attest-v1"             // JWKS key ID
  },
  "meta": {"creditsRemaining": 999, "creditsCharged": 1}
}

That is the entire surface an agent needs. 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.

Two onboarding paths, different economics

Getting a key works two ways depending on who is asking. The paths are deliberately separate because humans have emails and agents have wallets.

Humans evaluating the primitive: one curl, free tier, 10 credits to run end-to-end before spending anything. One key per email, three per IP per 24 hours.

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"}'

Agents paying for themselves: no email, no signup flow. The agent broadcasts a USDC or BTC transfer to the platform wallet, then calls buy_api_key with the transaction hash. The sender wallet becomes the registered identity on the new key — the payment is the auth. Credits scale with amount paid; tier: "paid", 10,000 requests per day, 30-day expiry.

from llama_index.tools.insumer import InsumerToolSpec

# Agent has already broadcast a 100 USDC transfer on Base to the platform wallet.
# Now it redeems the transaction for its own API key:
result = InsumerToolSpec().buy_api_key(
    tx_hash="0xabc...",
    chain_id=8453,            # Base; use "solana" or "bitcoin" for those chains
    app_name="my-agent",
    amount=100.0,
)
my_key = result["data"]["key"]    # insr_live_... — shown once, save it

Topping up an existing key uses the same on-chain pattern via buy_credits. Attestations cost 1 credit, trust profiles cost 3 credits. Template discovery and JWKS lookups are free. No Stripe, 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.