Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Insumer Discovery API
version: '1.0'
description: 'InsumerAPI is the API for wallet auth — the primitive: read on-chain state, evaluate against caller-supplied conditions, return ECDSA-signed booleans across 37 chains. Conditions in, signed attestations out. Provable and private — no shared secrets, no identity-first claims, no static credentials. Never exposes wallet balances. Every result is signed and checkable offline against the published keys, and on EVM chains an optional Merkle proof lets the verifier check the balance against the block header without trusting the API. What a signed result shows: a signed result is InsumerAPI''s statement that it read chain state and evaluated the stated conditions. It does not show who controls the wallet or who the person is, and it describes state at its anchor, valid until expiresAt. With a Merkle proof the value can be checked against the chain itself; without one, the result is as reliable as InsumerAPI, its upstream data sources, and its signing keys. A failed read is refused, never signed. Full list of limits: "What a signed result shows, and what it does not" in https://insumermodel.com/llms-full.txt. InsumerAPI is the programmatic interface for The Insumer Model — used by developers, AI agents, and platforms alike. One endpoint checks token balances, NFT ownership, EAS attestations, Farcaster identity, arbitrary boolean view calls, dimensionless ratio rules (balance vs a transaction amount, or share of supply), account code (plain key, EIP-7702 delegation or contract at the wallet address, any EVM chain), and agent standing on Base (ERC-8004 registration, ERC-7710 delegation validity) across 37 blockchains, returns ECDSA P-256 signed booleans, and never exposes wallet balances. The primitive is five operations: POST /v1/attest, POST /v1/trust, POST /v1/trust/batch, GET /v1/jwks, and GET /v1/compliance/templates (tags Wallet Auth and Trust Fact Profiles). The other 41 operations are applications built on it (merchant discounts and codes, point-of-sale recognition, ACP/UCP formats for agent commerce, the public directory) and the plumbing around it (keys, credits, billing, health). Supports up to 10 conditions per request, each with its own chainId. Optional Merkle storage proofs (EIP-1186) for trustless verification. Pre-configured compliance templates for Coinbase Verifications (KYC, country, Coinbase One) on Base. Not a points program. Not a reputation network. Not an identity system. Not a DeFi protocol. Not a payments processor. Not an oracle network. Used by AsterPay KYA (ERC-8183 agent trust scoring) and Revettr (counterparty risk for x402). 5 agent SDKs: MCP server (npx -y mcp-server-insumer), LangChain (pip install langchain-insumer), LlamaIndex (pip install llama-index-tools-insumer), ElizaOS (@insumermodel/plugin-eliza), ChatGPT plugin (OpenAI''s plugin directory). 2 framework adapters: WDK protocol module (@insumermodel/wdk-protocol-wallet-auth) for Tether''s Wallet Development Kit; mppx condition-gate (@insumermodel/mppx-condition-gate) for Machine Payments Protocol routes (first listed entry on Tempo''s extensions page). Attestations independently verifiable with insumer-verify (npm install insumer-verify, or pip install insumer-verify for Python; same checks, same published test vectors; source https://github.com/insumerapi/insumer-verify). Full guide: https://insumermodel.com/ai-agent-verification-api/ Visual endpoint map: https://insumermodel.com/workbench/'
contact:
email: support@insumermodel.com
url: https://insumermodel.com/developers/
termsOfService: https://insumermodel.com/terms-of-service/
license:
name: Proprietary
servers:
- url: https://api.insumermodel.com
description: Production
security:
- ApiKeyAuth: []
tags:
- name: Discovery
description: Browse merchants, tokens, and NFT collections in the public directory.
paths:
/v1/merchants:
get:
operationId: listMerchants
summary: List merchants in public directory
description: Browse merchants with optional filters. Returns public directory listings. A store whose recognition is paused is left out.
tags:
- Discovery
security: []
parameters:
- name: token
in: query
schema:
type: string
description: Filter by accepted token symbol (e.g. UNI)
- name: verified
in: query
schema:
type: string
enum:
- 'true'
- 'false'
description: Filter by domain verification status
- name: limit
in: query
schema:
type: integer
default: 50
maximum: 200
description: Results per page
- name: offset
in: query
schema:
type: integer
default: 0
description: Pagination offset
responses:
'200':
description: Merchant list
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
const: true
data:
type: array
items:
$ref: '#/components/schemas/MerchantSummary'
meta:
type: object
properties:
total:
type: integer
limit:
type: integer
offset:
type: integer
version:
type: string
timestamp:
type: string
format: date-time
'500':
$ref: '#/components/responses/ServerError'
/v1/merchants/{id}:
get:
operationId: getMerchant
summary: Get merchant details
description: Returns full public merchant profile including token tiers and NFT collections. 404 while the store's recognition is paused.
tags:
- Discovery
security: []
parameters:
- name: id
in: path
required: true
schema:
type: string
description: Merchant ID
responses:
'200':
description: Merchant details
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
const: true
data:
$ref: '#/components/schemas/MerchantDetail'
meta:
$ref: '#/components/schemas/Meta'
'400':
description: Invalid merchant ID format
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'404':
description: Merchant not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'500':
$ref: '#/components/responses/ServerError'
/v1/tokens:
get:
operationId: listTokens
summary: List registered tokens and NFTs
description: Returns all tokens and NFT collections in the registry, with optional filters.
tags:
- Discovery
security: []
parameters:
- name: chain
in: query
schema:
$ref: '#/components/schemas/ChainId'
description: Filter by chain ID
- name: symbol
in: query
schema:
type: string
description: Filter by token symbol
- name: type
in: query
schema:
type: string
enum:
- token
- nft
description: Filter by asset type
responses:
'200':
description: Token and NFT registry
content:
application/json:
schema:
type: object
properties:
ok:
type: boolean
const: true
data:
type: object
properties:
tokens:
type: array
items:
type: object
properties:
id:
type: string
symbol:
type: string
name:
type: string
chainId:
$ref: '#/components/schemas/ChainId'
chainName:
type: string
contractAddress:
type: string
decimals:
type: integer
logo:
type: string
nfts:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
contractAddress:
type: string
chainId:
$ref: '#/components/schemas/ChainId'
chainName:
type: string
image:
type: string
standard:
type: string
meta:
type: object
properties:
tokenCount:
type: integer
nftCount:
type: integer
version:
type: string
timestamp:
type: string
format: date-time
'500':
$ref: '#/components/responses/ServerError'
/v1/registry/tokens:
get:
operationId: getRegistryTokens
summary: List active registry tokens and NFT collections (no auth required)
description: Public read of the approved token and NFT registries, used by browser-side integrations to know which assets to scan for. Only active entries are returned. Flat response, not the standard envelope. Cached at the edge.
tags:
- Discovery
security: []
responses:
'200':
description: Active registry entries
content:
application/json:
schema:
type: object
properties:
tokens:
type: array
items:
type: object
properties:
id:
type: string
active:
type: boolean
name:
type: string
symbol:
type: string
chainId:
oneOf:
- type: integer
- type: string
- type: 'null'
chainName:
type: string
contractAddress:
type:
- string
- 'null'
description: EVM contract address (null for Solana tokens)
mintAddress:
type:
- string
- 'null'
description: Solana mint address (null for EVM tokens)
decimals:
type:
- integer
- 'null'
logo:
type: string
coingeckoId:
type: string
nfts:
type: array
items:
type: object
properties:
id:
type: string
active:
type: boolean
name:
type: string
contractAddress:
type: string
chainId:
oneOf:
- type: integer
- type: string
- type: 'null'
chainName:
type: string
image:
type: string
standard:
type: string
'500':
$ref: '#/components/responses/ServerError'
/v1/registry/merchants:
get:
operationId: getRegistryMerchants
summary: List public-directory merchants with domains (no auth required)
description: 'Public read of the merchant directory in the shape browser-side integrations consume: each entry carries its recognized domains, token tiers, and NFT collections. Flat response, not the standard envelope. For the filterable, paginated directory use GET /v1/merchants instead.'
tags:
- Discovery
security: []
responses:
'200':
description: Directory merchants
content:
application/json:
schema:
type: object
properties:
merchants:
type: array
items:
type: object
properties:
id:
type: string
companyName:
type: string
website:
type: string
location:
type: string
domains:
type: array
items:
type: string
tokens:
type: array
items:
type: object
nftCollections:
type: array
items:
type: object
verified:
type: boolean
verifiedDomain:
type: string
discountStacking:
type: string
enum:
- highest
- stack
- capped
maxDiscountCap:
type: integer
'500':
$ref: '#/components/responses/ServerError'
components:
schemas:
MerchantSummary:
type: object
properties:
id:
type: string
companyName:
type: string
website:
type: string
location:
type: string
verified:
type: boolean
tokens:
type: array
items:
type: object
properties:
symbol:
type: string
maxDiscount:
type: integer
nftCollections:
type: array
items:
type: object
properties:
name:
type: string
discount:
type: integer
discountMode:
type: string
enum:
- highest
- stack
- capped
discountCap:
type: integer
walletTerms:
$ref: '#/components/schemas/WalletTerms'
MerchantDetail:
type: object
properties:
id:
type: string
companyName:
type: string
website:
type: string
location:
type: string
verified:
type: boolean
verifiedDomain:
type: string
discountMode:
type: string
enum:
- highest
- stack
- capped
description: The merchant's stored discount mode, returned as configured.
discountCap:
type: integer
tokens:
type: array
items:
type: object
ownToken:
type:
- object
- 'null'
partnerTokens:
type: array
items:
type: object
nftCollections:
type: array
items:
type: object
acceptsUsdc:
type: boolean
walletTerms:
$ref: '#/components/schemas/WalletTerms'
WalletTerms:
type: object
description: 'What this store gives a wallet with and without proof of control, so an agent can decide before calling whether to sign. A proven wallet gets the full discount its holdings earn (under the store''s tiers and cap), without the daily limit for unproven wallets.
'
properties:
proofAccepted:
type: array
items:
type: string
description: Wallet types whose proof is accepted. Currently ["evm"].
proven:
type: object
properties:
maxDiscountsPerWalletPerDay:
type: 'null'
description: 'Always null: no daily limit for a proven wallet.'
unproven:
type: object
properties:
maxDiscount:
type:
- integer
- 'null'
description: At most this percent without proof; 0 = no discount; null = the same as proven.
maxDiscountsPerWalletPerDay:
type:
- integer
- 'null'
description: Discount codes per unproven wallet per UTC day; null = no limit.
ErrorEnvelope:
type: object
required:
- ok
- error
- meta
properties:
ok:
type: boolean
const: false
error:
type: object
required:
- code
- message
properties:
code:
type: integer
message:
type: string
meta:
$ref: '#/components/schemas/Meta'
ChainId:
oneOf:
- type: integer
enum:
- 1
- 56
- 8453
- 43114
- 137
- 42161
- 10
- 88888
- 1868
- 98866
- 146
- 100
- 5000
- 534352
- 59144
- 324
- 81457
- 167000
- 2020
- 42220
- 88
- 204
- 480
- 130
- 57073
- 1329
- 80094
- 33139
- 50
- 4663
- 5042
- type: string
enum:
- solana
- xrpl
- bitcoin
- tron
- stellar
- sui
description: 'EVM chain ID (integer), or one of "solana", "xrpl", "bitcoin", "tron", "stellar", "sui" (string). Supported chains: 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), Viction (88), opBNB (204), World Chain (480), Unichain (130), Ink (57073), Sei (1329), Berachain (80094), ApeChain (33139), XDC Network (50), Robinhood Chain (4663), Arc (5042), Solana ("solana"), XRP Ledger ("xrpl"), Bitcoin ("bitcoin"), Tron ("tron"), Stellar ("stellar"), Sui ("sui"). Bitcoin only supports token_balance with contractAddress "native". Tron, Stellar, and Sui support token_balance only. Moonbeam (1284) and Moonriver (1285) were retired on 2026-09-20 after both networks stopped producing blocks. GLMR and MOVR now live on Base (chainId 8453) as ERC-20s and are read with an ordinary token_balance condition; a request naming either retired chain returns 400.
'
Meta:
type: object
properties:
version:
type: string
example: '1.0'
timestamp:
type: string
format: date-time
responses:
ServerError:
description: 'Unexpected server error. Safe to retry; no credits are charged on a 500. Router endpoints return the standard error envelope; standalone endpoints (the ones whose 200 is a flat object) return a flat {"error": "..."} object.
'
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/ErrorEnvelope'
- type: object
properties:
error:
type: string
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: 'API key in format: insr_live_ followed by 40 hex characters'
WalletAuth:
type: apiKey
in: header
name: Authorization
description: 'Wallet-signed authentication. Accepted on: POST /v1/attest, POST /v1/trust, POST /v1/trust/batch, GET /v1/credits, and POST /v1/credits/buy. Other endpoints return 501 for this scheme. Header value: `Wallet <base64(JSON({message, signature}))>` where `message` is a SIWE (EIP-4361) string with `Domain: api.insumermodel.com` and `signature` is an EIP-191 personal_sign over `message`. The signing wallet must (1) match the wallet registered to the API key (the sender wallet from POST /v1/keys/buy) and (2) hold the Insumer Access pass (soulbound ERC-721 on Base, collection 0x3E2a408cc6eceba04FF9d04A5B8B05aBa8DD50ce). Nonce is single-use; `Issued At` must be within the last 5 minutes. Wallet auth authenticates the caller only. Every wallet evaluated by /v1/attest, /v1/trust, or /v1/trust/batch comes from the request body, is independent of the signer, and is not required to match it. A relying party that needs the verdict bound to the presenting wallet verifies that wallet''s own signature first, then attests the recovered address (the pattern `@skyemeta/access` implements). Drop-in middleware available as `@skyemeta/access` on npm.
'
x-auth-note: 'Default authentication is the X-API-Key header. Five endpoints — POST /v1/attest, POST /v1/trust, POST /v1/trust/batch, GET /v1/credits, and POST /v1/credits/buy — also accept wallet-signed auth via an Authorization: Wallet header (SIWE envelope) from a wallet that holds an Insumer Access pass. All other endpoints require X-API-Key. POST /v1/attest, POST /v1/trust, and POST /v1/trust/batch additionally accept x402 pay-per-call: a request with NO credential headers on those three receives a 402 quote (see each operation''s 402 response and x-payment-info) rather than a 401. A credential-less GET or HEAD to one of those three paths receives the same 402 quote (the quote''s resource.method still says POST; paid handling stays POST-only). Everywhere else, and whenever a credential is present but invalid, the response is 401 with {ok: false, error: {code: 401, message: ''Invalid or missing API key.''}}. One exception: a request presenting an Authorization: Wallet header to any endpoint outside that five-endpoint wallet-auth allowlist returns 501, stating that wallet-pass auth is scoped to those endpoints only.'