Wallet Auth for AI Agents: Python + LangChain Tutorial

AI agents that interact with wallets need to verify what those wallets hold before making decisions. An agent approving a payment, granting access, or scoring trust needs a server-side signal, not a client-side read. This tutorial shows how to add wallet verification to a LangChain agent using the langchain-insumer package. Five minutes, working code, 32 chains.

Install the package

pip install langchain-insumer

Requires Python 3.9+ and a free InsumerAPI key. Get one here (10 free credits, no credit card).

Set up the tools

import os
from langchain_insumer import InsumerAPIWrapper, InsumerAttestTool, InsumerWalletTrustTool

os.environ["INSUMER_API_KEY"] = "insr_live_YOUR_KEY_HERE"

api = InsumerAPIWrapper()
attest_tool = InsumerAttestTool(api_wrapper=api)
trust_tool = InsumerWalletTrustTool(api_wrapper=api)

Two tools. attest_tool verifies specific conditions: token holdings, NFT ownership, EAS attestations, and Farcaster identity. trust_tool generates a full trust profile across 4 dimensions: stablecoins, governance, NFTs, and staking.

Add to your agent

from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain_core.prompts import ChatPromptTemplate

llm = ChatOpenAI(model="gpt-4o")
tools = [attest_tool, trust_tool]

prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant that can verify wallet holdings on-chain."),
    ("human", "{input}"),
    ("placeholder", "{agent_scratchpad}"),
])

agent = create_tool_calling_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools)

The agent now has access to both wallet verification tools. It will decide which tool to call based on the user's request.

Verify token holdings

result = executor.invoke({
    "input": "Does wallet 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 hold at least 1000 USDC on Ethereum?"
})
print(result["output"])

The agent calls attest_tool with the right parameters. Under the hood, it hits POST /v1/attest with type: "token_balance", contractAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", chainId: 1, threshold: 1000, and decimals: 6.

The response is ECDSA-signed. The agent gets a boolean, not a balance. Privacy preserved by design.

Generate a trust profile

result = executor.invoke({
    "input": "Generate a trust profile for wallet 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
})
print(result["output"])

trust_tool hits POST /v1/trust. It returns 36 checks across 4 dimensions: stablecoins (USDC and USDT), governance, NFTs, and staking. The agent gets a structured summary with totalPassed, totalFailed, and dimensionsWithActivity.

This is the "does this wallet hold real assets?" verification, useful for cold-start reputation. A wallet that holds governance tokens on multiple chains, stablecoins across several networks, and NFTs from established collections is more credible than an empty wallet created yesterday.

Using the tools directly (without an agent)

You do not need a full agent to use the tools. Call them directly for programmatic workflows:

import json

# Verify specific condition
result = attest_tool.invoke({
    "wallet": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "conditions": json.dumps([
        {
            "type": "nft_ownership",
            "contractAddress": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D",
            "chainId": 1,
            "label": "BAYC holder"
        }
    ])
})

# Trust profile
trust = trust_tool.invoke({
    "wallet": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
})

Same ECDSA-signed responses. Same 32-chain coverage. The tools work identically whether called by an agent or by your code.

MCP server alternative

For agents that use MCP (Model Context Protocol), there is an MCP server that exposes the same capabilities:

npx -y mcp-server-insumer

This exposes the same verify and trust tools as MCP resources. Works with Claude, Cursor, and any MCP-compatible client. No Python needed.

Set the INSUMER_API_KEY environment variable before starting the server, and any connected agent can call verify_wallet and check_trust directly.

What the agent sees

Every verification returns ECDSA-signed results. The agent, or any downstream service, can verify the signature against the public key at GET /v1/jwks. This means the verification is trustworthy even if the agent itself is untrusted.

The response also supports format: "jwt". Pass that parameter to POST /v1/attest and you get an ES256-signed JWT alongside the standard response. Any service with a standard JWT library (Kong, Nginx, Cloudflare Access, AWS API Gateway) can verify it via the JWKS endpoint without any custom code.

Key insight: Wallet Auth for agents works like OAuth for users. OAuth proves who you are. Wallet Auth proves what you hold.

Use cases for agent wallet verification

        - **Pre-transaction trust.** Before an agent sends funds, verify the counterparty holds real assets. A wallet with governance tokens and stablecoins across multiple chains is a stronger counterparty than an empty wallet.
        - **Token-gated API access.** Require proof of token holdings to access premium agent capabilities. Verify once, cache the signed attestation, and check it on every request.
        - **Compliance gates.** Verify Coinbase KYC attestations (via EAS) before processing regulated transactions. The agent verifies the on-chain attestation exists without seeing any personal data.
        - **Agent-to-agent trust.** One agent can verify another agent's wallet as a trust signal. If Agent B claims to represent a DAO, Agent A can verify that Agent B's wallet holds the DAO's governance token.


, before CTA) -->

    Share this article

        [

            Share on X
        ](#)
        [

            LinkedIn
        ](#)
        [

            Reddit
        ](#)


            Discord



            Copy Link

---

InsumerAPI is free to start. Get an API key and try it. View API Docs