API Reference | InsumerAPI Docs

See how all 26 endpoints connect → API Topology

Authentication

API Key

Most endpoints require an X-API-Key header. Keys use the format insr_live_ followed by 40 hex characters. Get a free key at /developers/#pricing. Public endpoints (no key needed): JWKS, compliance templates, code validation, merchant directory, token registry, and discount check.

Base URL

https://api.insumermodel.com

All endpoints are relative to this base URL.

Rate Limits

Plan	Verification Credits / Mo	Free Reads / Day	Price
Free	10	100	$0
Pro	1,000	10,000	$29/mo
Enterprise	5,000	100,000	$99/mo

Reads (GET requests) use the daily limit and are free. API credits are consumed by attest, trust, and batch trust endpoints. Merchant credits are consumed by commerce endpoints. See full pricing, per-call costs, and volume discounts →

Response Format

Success

{
  "ok": true,
  "data": { /* endpoint-specific */ },
  "meta": {
    "version": "1.0",
    "timestamp": "2026-02-27T12:00:00Z"
  }
}
                    

Error

{
  "ok": false,
  "error": {
    "code": 401,
    "message": "Invalid or missing API key."
  },
  "meta": {
    "version": "1.0",
    "timestamp": "2026-02-27T12:00:00Z"
  }
}
                    

503 — RPC Failure (retryable)

{
  "ok": false,
  "error": {
    "code": "rpc_failure",
    "message": "Unable to verify all conditions — data source unavailable after retries",
    "failedConditions": [
      { "chainId": 1, "contractAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "message": "fetch failed" }
    ]
  },
  "meta": { "version": "1.0", "timestamp": "..." }
}
                

Returned when an upstream data source is unavailable after retries. No attestation signed, no JWT, no credits charged. Retry after 2–5 seconds. Applies to: /v1/attest, /v1/trust, /v1/trust/batch, /v1/verify, /v1/acp/discount, /v1/ucp/discount.

Endpoint Index

Method	Endpoint	Description
Verification
POST	/v1/attest	Boolean attestation across 33 chains
GET	/v1/jwks	JWKS public key for signature verification
GET	/v1/compliance/templates	List available compliance templates
Trust
POST	/v1/trust	Wallet trust profile (36 checks)
POST	/v1/trust/batch	Batch trust profiles (up to 10)
Commerce
POST	/v1/acp/discount	Generate ACP-format discount
POST	/v1/ucp/discount	Generate UCP-format discount
GET	/v1/codes/{code}	Validate discount code (public)
POST	/v1/verify	Verify wallet and get discount
POST	/v1/payment/confirm	Confirm code redemption
GET	/v1/discount/check	Check discount eligibility
Merchants
GET	/v1/merchants	List published merchants
GET	/v1/merchants/{id}	Get merchant details
GET	/v1/tokens	List supported tokens
Onboarding
POST	/v1/merchants	Create merchant programmatically
POST	/v1/merchants/{id}/domain-verification	Request domain verification token
PUT	/v1/merchants/{id}/domain-verification	Trigger domain verification check
PUT	/v1/merchants/{id}/tokens	Update accepted tokens
PUT	/v1/merchants/{id}/nfts	Update accepted NFTs
PUT	/v1/merchants/{id}/settings	Update merchant settings
POST	/v1/merchants/{id}/credits	Buy merchant verification credits
POST	/v1/merchants/{id}/directory	Publish to merchant directory
GET	/v1/merchants/{id}/status	Get merchant setup status
Account
POST	/v1/keys/buy	Buy API key with USDC, USDT, or BTC (no auth)
GET	/v1/credits	Check credit balance
POST	/v1/credits/buy	Buy credits with USDC, USDT, or BTC

Verification

POST /v1/attest

Boolean attestation. Checks token balances, NFT ownership, EAS attestations, and Farcaster identity across 33 chains. Returns ECDSA P-256 signed result. Up to 10 conditions per request. Full docs →

Parameter	Type	Description
wallet	string required*	EVM wallet address (0x...). Required unless solanaWallet or xrplWallet is provided
solanaWallet	string optional	Solana wallet address (raw base58; .sol domain resolution not supported). Required if any condition uses chainId "solana"
xrplWallet	string optional	XRPL wallet address (r-address). Required if any condition uses chainId "xrpl"
bitcoinWallet	string optional	Bitcoin address (P2PKH, P2SH, bech32, or Taproot). Required if any condition uses chainId "bitcoin"
conditions	array required	Array of condition objects (max 10). Each has: type, contractAddress, chainId, threshold, decimals. Types: token_balance, nft_ownership, eas_attestation, farcaster_id
proof	string optional	Set to "merkle" for EIP-1186 storage proofs. 2 credits instead of 1. 26 of 30 EVM chains
format	string optional	Set to "jwt" to include a Wallet Auth by InsumerAPI token (ES256-signed JWT). Verifiable by any standard JWT library using JWKS. No additional cost

GET /v1/jwks

Returns the JWKS (JSON Web Key Set) containing the ECDSA P-256 public key used to sign attestation and trust responses. 24-hour cache. Also available as a static file at /.well-known/jwks.json.

No parameters. Returns { keys: [{ kty, crv, x, y, kid, alg, use }] }

GET /v1/compliance/templates

Lists all available compliance templates with their condition configurations. Full docs →

No parameters. Returns object of templates keyed by name: coinbase_verified_account, coinbase_verified_country, coinbase_one (Base), gitcoin_passport_score, gitcoin_passport_active (Optimism).

Trust

POST /v1/trust

Generates an ECDSA-signed wallet trust profile with curated checks across up to 7 dimensions: stablecoins — USDC and USDT (26), governance (4), NFTs (3), staking (3), plus optional Solana, XRPL, and Bitcoin. 3 credits per call. Full docs →

Parameter	Type	Description
wallet	string required	EVM wallet address (0x...)
solanaWallet	string optional	Solana wallet address. Adds USDC on Solana check
xrplWallet	string optional	XRPL wallet address (r-address). Adds RLUSD + USDC on XRP Ledger checks
bitcoinWallet	string optional	Bitcoin address. Adds Bitcoin Holdings dimension (native BTC balance check)
proof	string optional	Set to "merkle" for storage proofs. 6 credits instead of 3

POST /v1/trust/batch

Batch trust profiles for up to 10 wallets in a single request. Shared block fetches make it 5-8x faster than individual calls. 3 credits per wallet. Partial success supported.

Parameter	Type	Description
wallets	array required	Array of objects (max 10). Each has: wallet (required), solanaWallet (optional), xrplWallet (optional)
proof	string optional	Set to "merkle" for storage proofs. 6 credits per wallet

Commerce

POST /v1/acp/discount

Verify wallet holdings and generate a discount code in OpenAI/Stripe ACP format. Full docs →

Parameter	Type	Description
merchantId	string required	Merchant ID from the registry
wallet	string required*	EVM wallet address (0x...)
solanaWallet	string optional	Solana wallet address
xrplWallet	string optional	XRPL wallet address (r-address)
items	array optional	Cart items for context

POST /v1/ucp/discount

Verify wallet holdings and generate a discount code in Google UCP format.

Parameter	Type	Description
merchantId	string required	Merchant ID from the registry
wallet	string required*	EVM wallet address (0x...)
solanaWallet	string optional	Solana wallet address
xrplWallet	string optional	XRPL wallet address (r-address)
items	array optional	Cart items for context

GET /v1/codes/{code}

Validate a discount code. Public endpoint, no API key required. Returns code status, merchant, discount percentage, and expiry.

Parameter	Type	Description
code	string required	Path parameter. The discount code to validate

Invalid codes return reason: "not_found" | "expired" | "already_used"

POST /v1/verify

Verify wallet token/NFT holdings against a merchant's configured requirements and return a discount code if eligible.

Parameter	Type	Description
merchantId	string required	Merchant ID from the registry
wallet	string required*	EVM wallet address (0x...)
solanaWallet	string optional	Solana wallet address
xrplWallet	string optional	XRPL wallet address (r-address)

POST /v1/payment/confirm

Verify an on-chain USDC payment and mark a discount code as used. Confirms the transaction on-chain before accepting.

Parameter	Type	Description
code	string required	The discount code to confirm (INSR-XXXXX)
txHash	string required	On-chain USDC transaction hash
chainId	number\|"solana" required	Chain ID of the payment (e.g. 1, 8453, "solana")
amount	number\|string required	USDC amount paid

GET /v1/discount/check

Check if a wallet is eligible for a discount at a specific merchant without generating a code.

Parameter	Type	Description
merchant	string required	Query parameter. Merchant ID
wallet	string optional	Query parameter. EVM wallet address
solanaWallet	string optional	Query parameter. Solana wallet address
xrplWallet	string optional	Query parameter. XRPL wallet address (r-address)

Merchants

GET /v1/merchants

List all published merchants in the directory. Returns merchant name, ID, location, accepted tokens, and discount tiers.

Parameter	Type	Description
token	string query	Filter by token symbol
verified	string query	Filter by domain verification status (`"true"` or `"false"`)
limit	integer query	Results per page (default 50, max 200)
offset	integer query	Pagination offset

GET /v1/merchants/{id}

Get full details for a specific merchant including accepted tokens, NFTs, discount configuration, and business info.

Parameter	Type	Description
id	string required	Path parameter. Merchant document ID

GET /v1/tokens

List all tokens supported across the platform with contract addresses, chain IDs, decimals, and logos.

Parameter	Type	Description
chain	integer\|string query	Filter by chain ID
symbol	string query	Filter by token symbol
type	string query	Filter by "token" or "nft"

Onboarding

POST /v1/merchants

Create a new merchant programmatically. Receives 100 free verification credits. Max 10 merchants per API key. Full docs →

Parameter	Type	Description
companyName	string required	Display name (max 100 chars)
companyId	string required	Unique ID. Alphanumeric, dash, underscore (2-50 chars)
location	string optional	City or region (max 200 chars)

POST /v1/merchants/{id}/domain-verification

Generate a verification token for proving domain ownership. Supports DNS TXT record, HTML meta tag, or verification file. Each POST regenerates the token.

Parameter	Type	Description
id	string required	Path parameter. Merchant ID
domain	string required	Domain to verify (e.g. example.com). No protocol prefix.

PUT /v1/merchants/{id}/domain-verification

Check all three verification methods (DNS TXT, meta tag, file) for the previously requested domain. Rate limited to 5 attempts per hour per merchant.

Parameter	Type	Description
id	string required	Path parameter. Merchant ID

PUT /v1/merchants/{id}/tokens

Configure which tokens the merchant accepts and the minimum balance required for discounts.

Parameter	Type	Description
id	string required	Path parameter. Merchant ID
ownToken	object\|null optional	Merchant's own token config (symbol, chainId, contractAddress, decimals, tiers)
partnerTokens	array optional	Array of partner token configs, same structure as ownToken

PUT /v1/merchants/{id}/nfts

Configure which NFT collections the merchant accepts for discounts.

Parameter	Type	Description
id	string required	Path parameter. Merchant ID
nftCollections	array required	Array of NFT objects with contractAddress, chainId, name, discount. Max 4.

PUT /v1/merchants/{id}/settings

Update discount stacking mode, cap, and USDC payment settings. All fields optional.

Parameter	Type	Description
id	string required	Path parameter. Merchant ID
discountMode	string optional	"highest" (best single discount) or "stack" (sum all)
discountCap	integer optional	Maximum total discount percentage (1-100)
usdcPayment	object\|null optional	USDC payment config (enabled, evmAddress, solanaAddress, preferredChainId) or null to disable

POST /v1/merchants/{id}/credits

Purchase merchant verification credits with USDC. Volume discounts from $0.04 to $0.02/credit. See wallet addresses and volume discounts →

Parameter	Type	Description
id	string required	Path parameter. Merchant ID
txHash	string required	USDC transfer transaction hash
chainId	integer\|string required	Chain where USDC was sent
amount	number required	USDC amount sent (min 5, human-readable units)
updateWallet	boolean optional	Set to true to change the registered sender wallet. Default false

Sender verification: The first purchase registers the sender wallet to the API key. Subsequent purchases must come from the same sender. To change the registered wallet, include "updateWallet": true—the verified transfer proves ownership.

POST /v1/merchants/{id}/directory

Publish (or refresh) the merchant's listing in the public directory. No request body needed. Call again after updating tokens or settings.

Parameter	Type	Description
id	string required	Path parameter. Merchant ID

GET /v1/merchants/{id}/status

Get the setup completion status for a merchant. Shows which steps are done: domain verified, tokens configured, published, etc.

Parameter	Type	Description
id	string required	Path parameter. Merchant ID

Account

GET /v1/credits

Check your current credit balance, plan tier, and usage stats.

No parameters. Returns credits remaining, plan name, daily reads used/limit.

POST /v1/keys/buy No auth required

Buy a new API key with USDC, USDT, or BTC. Agent-friendly: no email or prior authentication needed. The sender wallet from the transaction becomes the key's identity. See wallet addresses and volume discounts →

Parameter	Type	Description
txHash	string required	Transfer transaction hash
chainId	integer\|string required	Chain where payment was sent. Supported: ETH (1), Base (8453), Polygon (137), Arbitrum (42161), Optimism (10), BNB (56), Avalanche (43114), Solana ("solana"), Bitcoin ("bitcoin")
amount	number required for stablecoins	USDC/USDT amount sent (min 5). Not required for BTC (USD value derived from on-chain amount at market rate)
appName	string required	Name for the API key (e.g. your agent or app name, max 100 chars)

How it works: Send USDC, USDT, or BTC to the platform wallet on any supported chain, then call this endpoint with the transaction hash. The on-chain transfer is verified (BTC requires 1 confirmation), a new API key is created, and credits are added at volume-discount rates. USDC and USDT are accepted at face value; BTC is converted to USD at the market rate. One key per wallet — use POST /v1/credits/buy to top up an existing key.

POST /v1/credits/buy

Purchase additional verification credits using USDC, USDT, or BTC on supported chains. See wallet addresses and volume discounts →

Parameter	Type	Description
txHash	string required	Transfer transaction hash
chainId	integer\|string required	Chain where payment was sent. Supported: ETH (1), Base (8453), Polygon (137), Arbitrum (42161), Optimism (10), BNB (56), Avalanche (43114), Solana ("solana"), Bitcoin ("bitcoin")
amount	number required for stablecoins	USDC/USDT amount sent. Not required for BTC
updateWallet	boolean optional	Set to true to change the registered sender wallet. Default false

← Onboarding Back to Developers Hub →