feat(tools): add Insumer Model tools for on-chain attestation

[Douglas Borthwick (douglasborthwick-crypto)]

Summary

• Add 6 tools + API wrapper for The Insumer Model Attestation API
• Privacy-preserving on-chain verification: verifies token balances and NFT ownership across 31 blockchains, returns only signed true/false — never exposes actual balances
• Optional proof="merkle" parameter on InsumerAttest for EIP-1186 Merkle storage proofs, enabling trustless verification against public block headers (2 credits)
• Tools: InsumerAttest, InsumerCheckDiscount, InsumerVerify, InsumerListMerchants, InsumerListTokens, InsumerCredits
• API wrapper: InsumerAPIWrapper in utilities, supports INSUMER_API_KEY env var

Files added

• libs/community/langchain_community/tools/insumer/ — 6 tool modules + __init__.py
• libs/community/langchain_community/utilities/insumer.py — API wrapper
• Updated tools/__init__.py and utilities/__init__.py with lazy-loading registrations

Tamper-evident attestations

Every attestation result includes:

• evaluatedCondition: The exact condition logic that was evaluated (type, chainId, contractAddress, operator, threshold, decimals). Callers can confirm the API checked the right contract with the right parameters.
• conditionHash: SHA-256 of the canonical (sorted-key) JSON of evaluatedCondition, prefixed with 0x. Callers can recompute this to verify integrity.
• blockNumber and blockTimestamp (RPC chains only): The block at which the condition was evaluated, for freshness verification.

All fields are inside the ECDSA-signed results array, so the signature covers the evaluation logic itself. Third parties can independently verify attestations using the reference library: insumer-verify (Node.js/browser, zero dependencies).

Two levels of trust

The attestation endpoint supports two modes:

• Standard (default): Returns ECDSA-signed boolean results with evaluatedCondition and conditionHash for tamper-evidence. Proves who verified what condition. 1 credit.
• Merkle proof: Pass proof="merkle" to receive EIP-1186 Merkle storage proofs alongside boolean results. Callers can verify the result independently against the blockchain's state root. Available on 10 RPC chains for token_balance conditions. 2 credits.

Usage

from langchain_community.utilities.insumer import InsumerAPIWrapper
from langchain_community.tools.insumer import InsumerAttest

api = InsumerAPIWrapper(insumer_api_key="insr_live_...")
tool = InsumerAttest(api_wrapper=api)

# Standard attestation (signed boolean, 1 credit)
result = tool.run(
    '[ {"type":"token_balance","contractAddress":"0xA0b8...","chainId":1,"threshold":100,"decimals":6} ]',
    wallet="0x1234..."
)

# With Merkle storage proofs (2 credits, trustless verification)
result = tool.run(
    '[ {"type":"token_balance","contractAddress":"0xA0b8...","chainId":1,"threshold":100,"decimals":6} ]',
    wallet="0x1234...",
    proof="merkle"
)

Links

• API Documentation
• OpenAPI Spec
• LLM-readable API reference
• Standalone pip package
• Attestation verifier (npm) — independently verify ECDSA signatures, condition hashes, freshness, and expiry

AI disclosure

This PR was developed with assistance from AI agents (Claude Code).

🤖 Generated with Claude Code

[Douglas Borthwick (douglasborthwick-crypto)]

Hi Mason Daugherty (@mdrxy) — friendly bump on this PR. It adds 6 tools + a wrapper for the InsumerAPI (privacy-preserving on-chain token/NFT verification across 31 blockchains). The standalone package is already live on PyPI (langchain-insumer) and working in production. Happy to address any feedback. Thanks!

[Douglas Borthwick (douglasborthwick-crypto)]

Quick update: we just shipped POST /v1/trust (wallet trust profiles) since this PR was opened. The langchain-insumer package on PyPI has been updated to v0.2.0 with the new tool included. 7 tools total now covering attestation, trust profiles, credit checks, merchant directory, and JWKS verification.

Happy to rebase or adjust anything to help get this over the line. The package is seeing production use via the MCP server (mcp-server-insumer) and standalone.

[Douglas Borthwick (douglasborthwick-crypto)]

Rebased on latest main and expanded from 6 tools to 19 tools — full API parity with the MCP server.

New in this update:

• Wallet trust: InsumerWalletTrust + InsumerBatchWalletTrust (batch up to 10 wallets, 5-8x faster)
• JWKS: InsumerJwks for ECDSA signature key discovery
• Merchant onboarding: InsumerCreateMerchant, InsumerMerchantStatus, InsumerConfigureTokens, InsumerConfigureNfts, InsumerConfigureSettings, InsumerPublishDirectory
• Credits: InsumerBuyCredits, InsumerBuyMerchantCredits
• Payments: InsumerConfirmPayment
• Discovery: InsumerGetMerchant

The standalone package (langchain-insumer v0.4.0) is live on PyPI with the same 19 tools. MCP server has had 19 tools since v1.1.0.

Generated with assistance from Claude Code.

[Douglas Borthwick (douglasborthwick-crypto)]

Rebased on latest main and added the 20th tool: InsumerComplianceTemplates — lists available EAS compliance templates for attestation verification (e.g. Coinbase Verifications KYC on Base).

Changes in this update:

• InsumerComplianceTemplates tool — calls GET /v1/compliance/templates, free, no auth
• InsumerAttest updated to support eas_attestation condition type with template names or raw schema IDs
• Wrapper updated with get_compliance_templates() method

Now at 20 tools, full parity with MCP server v1.2.0 and standalone langchain-insumer v0.5.0 on PyPI.