# InsumerAPI — Condition-Based Access Infrastructure

version: 1.0.0

> InsumerAPI is condition-based access infrastructure for blockchain state. It reads wallet state, evaluates operator-defined conditions, and returns ECDSA-signed booleans across 33 chains. No secrets. No identity. No static credentials. No balances exposed.

## What This Is

InsumerAPI is the API for condition-based access — an access control model where decisions come from evaluating wallet state against conditions, not from shared secrets, identity lookups, or static credentials. Used by developers, AI agents, and platforms alike. It is read-first: it reads canonical on-chain state, evaluates conditions, and returns signed decision artifacts. It does not write to any blockchain. The core endpoint (`POST /v1/attest`) evaluates up to 10 conditions per request across 33 chains and returns cryptographically signed true/false results. Condition types: `token_balance`, `nft_ownership`, `eas_attestation` (EAS on-chain identity credentials), and `farcaster_id` (social identity). No raw balances. No RPC management. No chain-specific code.

## What This Really Is

Credential infrastructure for blockchain state. Every response is ECDSA P-256 signed with a discoverable public key (JWKS, RFC 7517). Optionally returns EIP-1186 Merkle storage proofs anchored to block headers for trustless verification. Block number and timestamp are included for freshness verification. The result is infrastructure: a signed, timestamped, optionally provable credential about on-chain state that any system can verify independently.

## What This Is Not

- Not a loyalty program
- Not a reputation network
- Not an identity system
- Not a DeFi protocol
- Not a payments processor
- Not an oracle network

It is credential infrastructure designed to be consumed by those systems.

**In production:** AsterPay's KYA Hook (ERC-8183) uses InsumerAPI attestations for 4 of 7 trust score components in agentic commerce. Revettr uses `/v1/trust` as the wallet analysis signal in counterparty risk scoring for x402 agents. SettlementWitness uses `/v1/attest` for pre-transaction verification in SAR settlement flows. InsumerAPI's `attestation_url` pattern is part of the Knowledge Context Protocol standard (KCP RFC-0004).

### Why Agents Use This

If your agent needs to answer "does this wallet hold X?" across any chain, InsumerAPI replaces building RPC connections, managing ABIs, and handling chain-specific quirks. You get a signed boolean you can verify offline.

- One endpoint covers 33 chains (no per-chain integration)
- Multi-condition requests (up to 10 conditions, each with its own chainId, one signature)
- Privacy by default (booleans only, no balance amounts)
- Deterministic and cacheable (same input, same boolean, 30-minute TTL)
- Client-side verifiable (ECDSA P-256 signature, JWKS key discovery, insumer-verify npm package)
- **Self-sustaining loop**: Agents buy their own API key with USDC, USDT, or BTC (`POST /v1/keys/buy`), operate, and refuel credits (`POST /v1/credits/buy`) — no human approval, no subscription renewal. Discover → acquire access → operate → refuel → repeat. The loop is what makes this autonomous infrastructure, not just an API.

### Use Cases

- **AI agent trust scoring**: Verify wallet holdings as trust/reputation signals for agent identity
- **Token-gated access**: Gate APIs, content, SaaS features, or rate limits behind token ownership
- **Agent-to-agent trust**: One agent verifies, another checks the ECDSA signature offline without re-querying the chain
- **DAO eligibility**: Confirm governance token holdings for voting without exposing portfolio composition
- **Compliance gating**: Verify Coinbase Verifications, KYC credentials, or other EAS attestations with pre-configured compliance templates
- **Compliance signals**: Prove minimum balance or staking thresholds with a signed audit trail
- **NFT verification**: Verify collection ownership for bots, platforms, or community gating
- **Holder rewards and commerce**: Verify holdings for reward tiers, merchant discounts, or physical POS verification via QR/NFC
- **Regulated commerce**: Trust screening → compliance attestation → condition-based discount in one multi-step flow
- **Agent trust handshake**: Verify counterparty wallet trust before delegating tasks (used by Revettr for x402 counterparty risk)

## API Base URL

https://api.insumermodel.com

## Authentication

Most `/v1/` endpoints require an API key via the `X-API-Key` header. Public endpoints (no key needed): GET /v1/jwks, GET /v1/compliance/templates, GET /v1/codes/{code}, GET /v1/merchants, GET /v1/merchants/{id}, GET /v1/tokens, GET /v1/discount/check.

Key format: `insr_live_` followed by 40 hex characters.

Get a free key instantly (10 verification credits included): POST `https://api.insumermodel.com/v1/keys/create` with `{ "email": "you@example.com", "appName": "My Agent", "tier": "free" }`.

## Supported Chains (33)

**EVM (30):** Ethereum (1), BNB Chain (56), Base (8453), Avalanche (43114), Polygon (137), Arbitrum (42161), Optimism (10), Chiliz (88888), Soneium (1868), Plume (98866), Sonic (146), Gnosis (100), Mantle (5000), Scroll (534352), Linea (59144), zkSync Era (324), Blast (81457), Taiko (167000), Ronin (2020), Celo (42220), Moonbeam (1284), Moonriver (1285), Viction (88), opBNB (204), World Chain (480), Unichain (130), Ink (57073), Sei (1329), Berachain (80094), ApeChain (33139)

**Non-EVM:** Solana (use `chainId: "solana"`), XRP Ledger (use `chainId: "xrpl"` — supports native XRP, trust line tokens like RLUSD and USDC, and NFT ownership), Bitcoin (use `chainId: "bitcoin"` with `bitcoinWallet` — native BTC balance, all address formats including Taproot)

## Core Endpoints

### Key Discovery
- `GET /v1/jwks` — JWKS endpoint returning InsumerAPI's ECDSA P-256 public signing key (no auth required, cached 24h). Also available at `https://insumermodel.com/.well-known/jwks.json`

### Compliance Templates
- `GET /v1/compliance/templates` — List pre-configured compliance templates for EAS attestation verification (no auth required). Templates: `coinbase_verified_account` (KYC), `coinbase_verified_country`, `coinbase_one`, `gitcoin_passport_score` (humanity score >= 20), `gitcoin_passport_active`. Use a template name in POST /v1/attest instead of raw schemaId/attester/indexer

### On-Chain Verification (Privacy-Preserving)
- `POST /v1/attest` — Verify 1-10 on-chain conditions (token_balance, nft_ownership, eas_attestation, farcaster_id), get signed true/false verification (1 credit). For EAS attestations, use a compliance template (e.g. `coinbase_verified_account`, `gitcoin_passport_score`) or raw schemaId. For Farcaster, use type `farcaster_id` (checks IdRegistry on Optimism). Response includes `kid` identifying the signing key. Each result includes `evaluatedCondition` (the exact condition logic) and `conditionHash` (SHA-256), making attestations tamper-evident. RPC chain results include `blockNumber` (hex) and `blockTimestamp` (ISO 8601) for freshness verification. Optional `proof: "merkle"` returns EIP-1186 Merkle storage proofs anchored to block headers, enabling fully trustless verification by any verifier without re-querying a chain (2 credits, reveals raw balance). Optional `format: "jwt"` returns a Wallet Auth by InsumerAPI token (ES256-signed JWT) verifiable by any standard JWT library using JWKS — no Insumer SDK required
- `POST /v1/trust` — Wallet trust fact profile: send a wallet address, get a structured ECDSA-signed fact profile across stablecoins (USDC and USDT), governance tokens, NFTs, and staking positions (36 base checks across 20 chains, plus optional Solana/XRPL — up to 39 total). No score, just cryptographically verifiable evidence organized by dimension. 3 credits ($0.12) standard, 6 credits ($0.24) with Merkle proofs. Designed for AI agent-to-agent trust decisions
- `POST /v1/trust/batch` — Batch wallet trust profiles: profile up to 10 wallets in one request. Block numbers fetched once and shared across all wallets (5-8x faster than sequential calls). Each wallet gets an independently ECDSA-signed profile. Partial success supported. 3 credits/wallet standard, 6 with Merkle proofs. Credits only charged for successful profiles
- `POST /v1/keys/buy` — Buy a new API key with USDC, USDT, or BTC (no auth required). Agent-friendly: no email needed, the sender wallet from the transaction becomes the key identity. One key per wallet. Send crypto to the platform wallet, submit txHash/chainId/appName (amount required for stablecoins, not BTC). Volume discounts apply
- `GET /v1/credits` — Check verification credit balance
- `POST /v1/credits/buy` — Buy credits with USDC, USDT, or BTC (volume discounts: $0.04–$0.02/call). First purchase registers the sender wallet to the API key; subsequent purchases must come from the same sender. Include `"updateWallet": true` to change the registered wallet

### Merchant Directory
- `GET /v1/merchants` — List merchants (filter by token, verified status). No auth required
- `GET /v1/merchants/{id}` — Merchant details with tier structures. No auth required
- `GET /v1/tokens` — Token and NFT registry (filter by chain, symbol, type). No auth required

### Discount Verification
- `GET /v1/discount/check` — Calculate discount for wallet + merchant. No auth required
- `POST /v1/verify` — Create signed discount code (INSR-XXXXX, valid 30 min)
- `POST /v1/payment/confirm` — Verify stablecoin payment for discount code

### Commerce Protocol Integration
- `POST /v1/acp/discount` — ACP (OpenAI/Stripe Agentic Commerce Protocol) format discount eligibility check. Returns coupon objects, applied/rejected arrays, per-item allocations. Same on-chain verification as /v1/verify, wrapped in ACP format. 1 merchant credit
- `POST /v1/ucp/discount` — UCP (Google Universal Commerce Protocol) format discount eligibility check. Returns title, extension field, applied array. Same verification, UCP format. 1 merchant credit
- `GET /v1/codes/{code}` — Validate an INSR-XXXXX discount code (no auth required, no credits). For merchant backends during ACP/UCP checkout to confirm code validity, discount percent, and expiry. Does not expose wallet or token data

### Agent Onboarding (Create & Manage Merchants)
- `POST /v1/merchants` — Create merchant (100 free credits)
- `POST /v1/merchants/{id}/domain-verification` — Request domain verification token (DNS/meta/file)
- `PUT /v1/merchants/{id}/domain-verification` — Trigger domain verification check (5/hour limit)
- `PUT /v1/merchants/{id}/tokens` — Configure token tiers
- `PUT /v1/merchants/{id}/nfts` — Configure NFT collections
- `PUT /v1/merchants/{id}/settings` — Update discount mode, cap, stablecoin payments
- `POST /v1/merchants/{id}/credits` — Buy merchant verification credits
- `POST /v1/merchants/{id}/directory` — Publish to public directory
- `GET /v1/merchants/{id}/status` — Full private merchant details (includes verification status)

## Response Format

Success: `{ "ok": true, "data": { ... }, "meta": { "version": "1.0", "timestamp": "..." } }`

Error: `{ "ok": false, "error": { "code": 401, "message": "..." }, "meta": { ... } }`

RPC Failure (retryable): `{ "ok": false, "error": { "code": "rpc_failure", "message": "Unable to verify all conditions — data source unavailable after retries", "failedConditions": [...] }, "meta": { ... } }` — returned when data sources are temporarily unreachable. No attestation signed, no credits charged. Retry after 2-5 seconds. Do NOT treat as `pass: false`.

## Rate Limits & Pricing

| Tier | Daily Reads | API Credits | Price |
|------|-------------|----------------|-------|
| Free | 100/day | 10 (one-time) | $0 |
| Pro | 10,000/day | 1,000/mo | $29/mo |
| Enterprise | 100,000/day | 5,000/mo | $99/mo |

Reads (GET requests) use the daily limit and are free.

**Two credit pools:**
- **API credits** (belong to API key): consumed by attest (1), trust (3), batch trust (3/wallet). Merkle proofs double cost. Buy more: POST /v1/credits/buy.
- **Merchant credits** (belong to each merchant): consumed by verify, codes, ACP, UCP (1 each). Buy more: POST /v1/merchants/{id}/credits.

**USDC volume discounts (buy credits on-chain):**

| Deposit | Rate | Credits per $1 USDC |
|---------|------|---------------------|
| $5–$99 | $0.04/call | 25 |
| $100–$499 | $0.03/call (25% off) | 33 |
| $500+ | $0.02/call (50% off) | 50 |

**Platform wallets:** EVM (USDC/USDT) `0xAd982CB19aCCa2923Df8F687C0614a7700255a23` (same on all chains) · Solana (USDC/USDT) `6a1mLjefhvSJX1sEX8PTnionbE9DqoYjU6F6bNkT4Ydr` · Bitcoin (BTC) `bc1qg7qnerdhlmdn899zemtez5tcx2a2snc0dt9dt0`
**Supported chains for crypto payments:** Ethereum, Base, Polygon, Arbitrum, Optimism, BNB Chain, Avalanche, Solana (USDC/USDT), and Bitcoin (BTC, converted to USD at market rate, 1 confirmation required).
**Crypto sent on unsupported chains cannot be recovered. All credit purchases are final and non-refundable.**

## Agent SDKs & Integrations

- **MCP Server** (Claude Desktop, Cursor, Windsurf): `npx -y mcp-server-insumer` (v1.7.5) — 26 tools, all endpoints, full XRPL support, Wallet Auth (JWT) format. Listed on Official MCP Registry. npm: https://www.npmjs.com/package/mcp-server-insumer | Glama: https://glama.ai/mcp/servers/@douglasborthwick-crypto/mcp-server-insumer
- **LangChain** (Python): `pip install langchain-insumer` (v0.9.13) — 26 tools covering all endpoints, full XRPL support, Wallet Auth (JWT) format. PyPI: https://pypi.org/project/langchain-insumer/. Also submitted as PR #549 to langchain-community (`from langchain_community.tools.insumer import ...`).
- **ElizaOS** (TypeScript): `eliza-plugin-insumer` (v1.2.1) — 10 actions covering the full autonomous agent lifecycle: BUY_API_KEY, CREATE_MERCHANT, CONFIGURE_TOKENS, ADD_CREDITS, VERIFY_WALLET, CHECK_TRUST, CHECK_TRUST_BATCH, ACP_DISCOUNT, UCP_DISCOUNT, CONFIRM_PAYMENT. npm: https://www.npmjs.com/package/eliza-plugin-insumer
- **OpenAI GPT**: Live in GPT Store as "InsumerAPI Verify" — 26 actions with full XRPL support, merchant onboarding, and commerce protocol integration.
- **Attestation Verifier** (Node.js/Browser): `npm install insumer-verify` — independently verify ECDSA signatures, condition hashes, block freshness, and expiry. Zero dependencies. npm: https://www.npmjs.com/package/insumer-verify

## Production Integrations

**AsterPay KYA Hook** (ERC-8183 agentic commerce) uses InsumerAPI for automated agent trust scoring. A single `POST /v1/attest` call with 4 conditions (Base USDC balance, `coinbase_verified_account`, `coinbase_verified_country`, `gitcoin_passport_score`) feeds 4 of 7 trust score components (up to 44/100 points). JWT format attestations verified client-side with `insumer-verify`. First IACPHook with third-party attestation integration. Case study: https://insumermodel.com/blog/asterpay-kya-erc8183-attestation-integration.html

**Revettr** (revettr.com) uses `POST /v1/trust` as the wallet analysis signal in their counterparty risk scoring API. Trust profile dimensions surface at `signal_scores.wallet.details.insumer_trust` in every Revettr score response. Revettr scores wallets, domains, IPs, and company names for x402 agent commerce — wallet auth provides the on-chain verification layer.

**SettlementWitness** (defaultverifier.com) uses `POST /v1/attest` as the pre-transaction verification layer in their Settlement Attestation Record (SAR) flow. Wallet auth qualifies agents going in, SAR verifies delivery coming out — a pre/post pattern for x402 agent commerce.

**KCP RFC-0004** (Knowledge Context Protocol) — InsumerAPI's `attestation_url` pattern is now part of the KCP standard (RFC-0004: Trust, Provenance, and Compliance). Knowledge publishers declare `attestation_url` and `attestation_jwks` in their YAML manifest; agents prove credentials via the attestation endpoint before accessing gated knowledge. InsumerAPI is the reference implementation. Case study: https://insumermodel.com/blog/kcp-rfc-0004-attestation-url-standard.html

**UCP (Universal Commerce Protocol)** — Contributed to the UCP signals (#203) and eligibility (#250) specifications, both merged. The cryptographic attestation signal pattern (`provider_jwks` / `kid` / `payload` / `sig`) in the UCP spec was shaped by InsumerAPI's design. Attestation extension (#264) proposed as a companion capability for eligibility claims — enables offline verification of non-instrument claims (token holdings, on-chain credentials) via JWKS. InsumerAPI is the first production implementation of the UCP attestation pattern. Spec: https://github.com/Universal-Commerce-Protocol/ucp

## Links

- AI Agent Verification API guide: https://insumermodel.com/ai-agent-verification-api/
- JWKS (public signing key): https://insumermodel.com/.well-known/jwks.json
- Full API reference: https://insumermodel.com/llms-full.txt
- OpenAPI spec: https://insumermodel.com/openapi.yaml
- Postman collection: https://insumermodel.com/insumerapi.postman_collection.json
- Case study (AsterPay KYA): https://insumermodel.com/blog/asterpay-kya-erc8183-attestation-integration.html
- Case study (KCP RFC-0004): https://insumermodel.com/blog/kcp-rfc-0004-attestation-url-standard.html
- Agent payments thesis: https://insumermodel.com/blog/before-an-agent-pays-wallet-auth-agentic-commerce.html
- MCP server: https://www.npmjs.com/package/mcp-server-insumer
- LangChain SDK: https://pypi.org/project/langchain-insumer/
- ElizaOS plugin: https://www.npmjs.com/package/eliza-plugin-insumer
- Attestation verifier: https://www.npmjs.com/package/insumer-verify
- Changelog: https://insumermodel.com/developers/changelog/
- Developer hub: https://insumermodel.com/developers/
- Quickstart (first API call in 5 min): https://insumermodel.com/developers/quickstart/
- Verification docs: https://insumermodel.com/developers/verification/
- Trust profile docs: https://insumermodel.com/developers/trust/
- Compliance docs: https://insumermodel.com/developers/compliance/
- Commerce docs (ACP/UCP): https://insumermodel.com/developers/commerce/
- Merchant onboarding docs: https://insumermodel.com/developers/onboarding/
- API reference (all endpoints): https://insumermodel.com/developers/api-reference/
- API topology (visual endpoint graph): https://insumermodel.com/workbench/
- Terms of service: https://insumermodel.com/terms-of-service/
- Contact: contact@insumermodel.com