{ "openapi": "3.1.0", "info": { "title": "InsumerAPI", "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 38 chains. Conditions in, signed attestations out. Condition-based access infrastructure across 38 blockchains. Condition types: token_balance, nft_ownership, eas_attestation (Coinbase, Gitcoin Passport), farcaster_id, evm_view_call (arbitrary boolean view functions), ratio_to_amount and ratio_to_supply (dimensionless ratio rules), and the agent standing types erc8004_agent and erc7710_delegation (Base). Up to 10 conditions per request. ACP/UCP compatible. Provable and private. No shared secrets, no identity-first claims, no static credentials. Never exposes wallet balances or requires trust in the API provider. Not a loyalty program. Not a reputation network. Not an identity system. Full guide: https://insumermodel.com/ai-agent-verification-api/\n", "x-guidance": "InsumerAPI answers one question in one call: does this wallet meet these conditions right now? POST /v1/attest with a wallet and 1-10 conditions (token_balance, nft_ownership, eas_attestation, farcaster_id, evm_view_call, ratio_to_amount, ratio_to_supply, erc8004_agent for ERC-8004 agent registration, erc7710_delegation for delegation validity under the MetaMask Delegation Framework on Base) and receive an ECDSA-signed boolean verdict per condition, block-anchored, verifiable against the JWKS at https://insumermodel.com/.well-known/jwks.json. POST /v1/trust returns a multi-dimension signed trust profile for a wallet; POST /v1/trust/batch profiles up to 10 wallets. These three routes accept x402 pay-per-call: send the request with no credentials, receive a 402 quote, sign the USDC authorization on Base, retry with the X-PAYMENT header. No account or API key is needed on that path. All other routes require an X-API-Key (free key: POST /v1/keys/create with an email). Never send balances or private keys; the API reads public chain state only. Docs: https://insumermodel.com/developers/", "contact": { "email": "support@insumermodel.com" } }, "servers": [ { "url": "https://api.insumermodel.com", "description": "Production" } ], "security": [ { "ApiKeyAuth": [] } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key in format: insr_live_ followed by 40 hex characters" } }, "schemas": {} }, "paths": { "/v1/attest": { "post": { "operationId": "createAttestation", "summary": "Create a signed attestation", "description": "Wallet auth: evaluate 1-10 conditions (all nine types incl. erc8004_agent and erc7710_delegation) against wallet state across 38 chains. Returns signed booleans, never balances. 1 credit (2 w/merkle). Pass wallet/solanaWallet/xrplWallet/bitcoinWallet/tronWallet/stellarWallet/suiWallet.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "conditions" ], "properties": { "wallet": { "type": "string", "description": "EVM wallet address (0x followed by 40 hex chars)" }, "solanaWallet": { "type": "string", "description": "Solana wallet address (base58 encoded)" }, "xrplWallet": { "type": "string", "description": "XRPL wallet address (r-address, 25-35 chars). Required when any condition uses chainId: \"xrpl\"." }, "bitcoinWallet": { "type": "string", "description": "Bitcoin address (P2PKH, P2SH, bech32, Taproot). Required when any condition uses chainId: \"bitcoin\". Supports native BTC only." }, "tronWallet": { "type": "string", "description": "Tron T-address (base58, 34 chars). Required when any condition uses chainId: \"tron\". Supports TRC-20 and native TRX (contractAddress \"native\")." }, "stellarWallet": { "type": "string", "description": "Stellar G-address (StrKey, 56 chars). Required when any condition uses chainId: \"stellar\". Trustline tokens require both contractAddress (G-issuer) and assetCode." }, "suiWallet": { "type": "string", "description": "Sui address (0x + 64 hex chars). Required when any condition uses chainId: \"sui\". Coin type goes in contractAddress (e.g. \"0x2::sui::SUI\")." }, "proof": { "type": "string", "enum": [ "merkle" ], "description": "Set to 'merkle' to include EIP-1186 Merkle storage proofs. Costs 2 credits (the premium is refunded if a proof cannot be produced for a transient RPC reason). Proofs available for token_balance on 28 of 32 EVM chains, and for erc7710_delegation on DelegationManagers whose storage layout has been verified on-chain (currently the v1.3.0 manager on Base) — a delegation proof carries subject: 'delegation_revocation' and proves disabledDelegations[delegationHash] against the anchored block's state root, so 'not revoked as of block N' becomes checkable rather than asserted." }, "format": { "type": "string", "enum": [ "jwt" ], "description": "Set to 'jwt' to include a Wallet Auth by InsumerAPI token (ES256-signed JWT) in the response. Verifiable by any standard JWT library using JWKS at https://insumermodel.com/.well-known/jwks.json. No additional cost." }, "declaredLimits": { "type": "string", "enum": [ "include", "omit" ], "default": "include", "description": "Controls whether decoded caveat limits ride along with erc7710_delegation results. Default ('include', or the field absent) returns them inside the signed results, so they also travel inside the JWT when format: 'jwt' is used. Set to 'omit' and they are left out; the result carries declaredLimitsOmitted: true instead. Use 'omit' when the attestation will be forwarded to third parties and the principal's spending ceiling should not travel with it — you submitted the caveats, so you lose nothing. met, delegationHash, and conditionHash are byte-identical either way, so a forwarded token still commits to exactly which delegation was checked. The limits ride on true and false verdicts alike once signature and revocation checks pass. No effect on other condition types, no additional cost." }, "conditions": { "type": "array", "minItems": 1, "maxItems": 10, "description": "Array of on-chain conditions to verify", "items": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "token_balance", "nft_ownership", "eas_attestation", "farcaster_id", "evm_view_call", "ratio_to_amount", "ratio_to_supply", "erc8004_agent", "erc7710_delegation" ], "description": "token_balance checks balance >= threshold; nft_ownership checks NFT ownership; eas_attestation checks EAS attestation via template or schemaId; farcaster_id checks Farcaster registration; evm_view_call calls an arbitrary bool-returning view function named by selector 'functionName(address)' on an RPC EVM chain; ratio_to_amount checks balance >= multiple * amount (RPC EVM chains only); ratio_to_supply checks balance / totalSupply >= minFraction (RPC EVM chains, ERC-20 only); erc8004_agent (Base only) checks the wallet owns or is the signature-verified agentWallet binding of ERC-8004 agentId N; erc7710_delegation (Base only) checks a MetaMask Delegation Framework delegation is signed, unrevoked, principal-matched, and inside any signed time window — that boolean is the verdict; the other declared limits ride alongside it as a signed decode, not as part of it. Attestations containing one expire in 5 minutes" }, "contractAddress": { "type": "string", "description": "Token or NFT contract address (required for token_balance, nft_ownership, ratio_to_amount, ratio_to_supply, and evm_view_call; use \"native\" for the chain's native asset, except ratio_to_supply which requires an ERC-20 contract and evm_view_call which requires a real contract). For XRPL: use \"native\" for XRP, or the issuer r-address for trust line tokens. Well-known asset references: XRPL trust line issuers: RLUSD = rMxCKbEDwqr76QuheSUMdEGf4B9xJ8m5De, USDC = rGm7WCVp9gb4jZHWTEtGUr4dd74z2XuWhE (use with currency). Tron USDT-TRC20 = TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t (decimals 6). Stellar trustline issuers: USDC = GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN, BENJI (Franklin Templeton) = GBJW74JRHIIIYC3X3J5VKLR2CR4UJHKO76V5J5SAYTUFAUE7PJBKCT5R (use with assetCode). Sui USDC = 0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC (decimals 6)." }, "selector": { "type": "string", "description": "Required for evm_view_call: the canonical signature of a bool-returning view function, form \"functionName(address)\" (e.g. \"hasAccess(address)\"). v1 supports single-address-argument view functions only. RPC EVM chains only." }, "chainId": { "description": "Chain to read. EVM chains use the integer chain ID: Ethereum=1, BNB=56, Base=8453, Avalanche=43114, Polygon=137, Arbitrum=42161, Optimism=10, XDC=50, Chiliz=88888, Soneium=1868, Plume=98866, Sonic=146, Gnosis=100, Mantle=5000, Scroll=534352, Linea=59144, zkSync=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, Robinhood Chain=4663. Non-EVM chains use a string: \"solana\", \"xrpl\", \"bitcoin\", \"tron\", \"stellar\", \"sui\" (each requires its matching wallet field). Not needed for farcaster_id. erc8004_agent and erc7710_delegation are Base (8453) only." }, "threshold": { "type": "string", "description": "Minimum token balance (for token_balance), as a decimal STRING in human-readable units (e.g. \"1000\" for 1000 USDC, not wei). Every newly created key signs v2, which requires the string form and rejects a JSON number with a 400. Must be > 0 (use \"0.000001\" for prove-any-balance with merkle)." }, "multiple": { "type": "string", "description": "For ratio_to_amount: collateralization multiple as a decimal STRING (e.g. \"10\" for \"hold >= 10x the amount\"). Condition met iff balance >= multiple * amount. Must be > 0." }, "amount": { "type": "string", "description": "For ratio_to_amount: per-request reference amount in token/display units as a decimal STRING (e.g. \"100\" for 100 USDC, not wei). Must be > 0." }, "minFraction": { "type": "string", "description": "For ratio_to_supply: required share of total supply as a decimal STRING in (0, 1] (e.g. \"0.005\" for 0.5%). Condition met iff balance / totalSupply() >= minFraction. For project/governance tokens, not stablecoins." }, "decimals": { "type": "integer", "description": "Token decimals. Auto-detected from contract if omitted." }, "template": { "type": "string", "enum": [ "coinbase_verified_account", "coinbase_verified_country", "coinbase_one", "gitcoin_passport_score", "gitcoin_passport_active" ], "description": "Compliance template name (for eas_attestation). Use instead of raw schemaId." }, "schemaId": { "type": "string", "description": "Raw EAS schema ID (for eas_attestation, if not using template)" }, "attester": { "type": "string", "description": "Expected attester address (optional, for eas_attestation). Recipient auto-binds to the verified wallet and must match the attestation's recipient field." }, "indexer": { "type": "string", "description": "EAS indexer contract address. Required for raw (non-template) eas_attestation. Verifier calls getAttestationUid(address,bytes32) on this contract (selector 0xab2717dd) to resolve the UID. Custom issuers deploy their own." }, "currency": { "type": "string", "description": "XRPL currency code (required for XRPL trust line tokens). 3-char code (e.g. \"USD\") or token name (e.g. \"RLUSD\", auto hex-encoded)." }, "taxon": { "type": "integer", "description": "XRPL NFToken taxon filter (optional, for nft_ownership on XRPL only)." }, "agentId": { "type": "string", "description": "For erc8004_agent (generally available on any API key, and on x402 pay-per-call with no key): required agentId as a uint256 decimal string (the registry has no wallet-to-agentId reverse lookup). Registration is permissionless minting — the attestation states registration/binding, not vetting." }, "delegationManager": { "type": "string", "description": "For erc7710_delegation (generally available on any API key, and on x402 pay-per-call with no key): a recognized MetaMask Delegation Framework DelegationManager address on Base. With proof: 'merkle' a revocation storage proof is returned for managers whose storage layout has been verified on-chain (currently v1.3.0, 0xdb9B1e94B5b69Df7e401DDbedE43491141047dB3); others return proof.available: false, since an inferred slot would prove the wrong location while still verifying against the block header." }, "expectedDelegator": { "type": "string", "description": "For erc7710_delegation: REQUIRED principal address this delegation must be authorized by. There is no structural-only mode — a self-delegation must never read as authority." }, "delegation": { "type": "object", "description": "For erc7710_delegation: the signed delegation — delegator, delegate (must be the attested wallet), authority (root only), caveats (max 16, each {enforcer, terms}; unknown enforcer fails the condition), salt, signature (EOA or ERC-1271). Spend/target/call limits are reported as declaredLimits; on-chain redemption enforces them. declaredLimits is not part of the met verdict — it is a signed decode of the caveat terms you submitted, and each entry carries the raw terms hex, so you can re-run the enforcer's public getTermsInfo byte layout against it and recompute delegationHash (in evaluatedCondition) to check the decode without any external lookup." }, "label": { "type": "string", "description": "Human-readable label for this condition (e.g. 'USDC >= 1000')" } } } } } } } } }, "responses": { "200": { "description": "Verification created", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object", "properties": { "attestation": { "type": "object", "properties": { "id": { "type": "string", "description": "Format: ATST- followed by 16 uppercase hex characters" }, "pass": { "type": "boolean", "description": "true only when ALL conditions are met" }, "results": { "type": "array", "items": { "type": "object", "properties": { "condition": { "type": "integer" }, "label": { "type": "string" }, "type": { "type": "string" }, "chainId": { "oneOf": [ { "type": "integer" }, { "type": "string", "enum": [ "solana", "xrpl", "bitcoin", "tron", "stellar", "sui" ] } ] }, "met": { "type": "boolean" }, "evaluatedCondition": { "type": "object", "description": "The exact condition logic evaluated. Callers recompute conditionHash from this to verify integrity.", "properties": { "type": { "type": "string" }, "chainId": { "oneOf": [ { "type": "integer" }, { "type": "string", "enum": [ "solana", "xrpl", "bitcoin", "tron", "stellar", "sui" ] } ] }, "contractAddress": { "type": "string" }, "operator": { "type": "string", "description": "gte for token_balance, gt for nft_ownership, valid for eas_attestation, decoder for Gitcoin, registered for farcaster_id" }, "threshold": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "v1 keys return a JSON number; v2 keys (every newly created key) return a canonical decimal string. nft_ownership stays the number 0 on both." }, "decimals": { "type": "integer", "nullable": true, "description": "Present only for token_balance. May be null for Solana and XRPL conditions in attest when not provided in the request. Auto-detected for all 32 EVM chains. Trust profiles always return a non-null value. v2 attest omits this field entirely." }, "currency": { "type": "string", "description": "Normalized XRPL currency code (present only for XRPL trust line conditions)" }, "taxon": { "type": "integer", "description": "XRPL NFToken taxon filter (present only for XRPL nft_ownership conditions)" } } }, "conditionHash": { "type": "string", "description": "SHA-256 of canonical evaluatedCondition JSON, 0x-prefixed" }, "blockNumber": { "type": "string", "description": "Hex block number at which the condition was evaluated. Present on all 32 EVM chains; Solana uses slot, XRPL uses ledgerIndex. API returns 503 if the block anchor could not be captured." }, "blockTimestamp": { "type": "string", "description": "ISO 8601 block timestamp. Present on all 32 EVM chains." }, "ledgerIndex": { "type": "integer", "description": "XRPL validated ledger index (present only for XRPL conditions)" }, "ledgerHash": { "type": "string", "description": "XRPL validated ledger hash (present only for XRPL conditions)" }, "trustLineState": { "type": "object", "description": "Trust line state flags (XRPL trust line tokens only). Frozen lines fail attestation.", "properties": { "frozen": { "type": "boolean" } } }, "slot": { "type": "integer", "description": "Solana slot at which the condition was evaluated. Present only for Solana conditions. Verifiers can reproduce the read by querying wallet state at this slot or later." }, "blockHeight": { "type": "integer", "description": "Bitcoin chain tip block height at observation time. Present only for Bitcoin conditions. Evidence-of-freshness anchor — Bitcoin's UTXO model does not permit reproducible balance-at-block queries." }, "blockHash": { "type": "string", "description": "Bitcoin chain tip block hash (64-char hex) at observation time. Present only for Bitcoin conditions. Co-reported with blockHeight." }, "proof": { "type": "object", "description": "Present only when proof: 'merkle' is requested. Contains EIP-1186 storage proof or available: false with reason. On an erc7710_delegation condition the proof carries subject: 'delegation_revocation' plus contractAddress (the DelegationManager); a proven storage value of 1 means revoked, 0 means not revoked — and a proven 0 is positive proof that no revocation exists, not merely a claim that none was found.", "properties": { "type": { "type": "string" }, "available": { "type": "boolean" }, "subject": { "type": "string", "description": "'delegation_revocation' on erc7710_delegation proofs. Absent on balance proofs." }, "blockNumber": { "type": "string" }, "contractAddress": { "type": "string", "description": "The DelegationManager the proof is against (erc7710_delegation proofs only)." }, "mappingSlot": { "type": "integer" }, "storageKey": { "type": "string", "description": "keccak256(abi.encode(key, uint256(mappingSlot))) — key is the wallet for balance proofs, delegationHash for delegation proofs. Recompute it from the delegationHash in the signed evaluatedCondition and confirm it matches; that is what binds the proof to this delegation." }, "accountProof": { "type": "array", "items": { "type": "string" } }, "storageProof": { "type": "array", "items": { "type": "object" } }, "storageHash": { "type": "string" }, "reason": { "type": "string" } } } } } }, "passCount": { "type": "integer" }, "failCount": { "type": "integer" }, "attestedAt": { "type": "string" }, "expiresAt": { "type": "string" } } }, "sig": { "type": "string", "description": "ECDSA P-256 signature (base64)" }, "kid": { "type": "string", "description": "Key ID for JWKS lookup (e.g. insumer-attest-v1). Fetch public key from https://insumermodel.com/.well-known/jwks.json" }, "jwt": { "type": "string", "description": "Wallet Auth by InsumerAPI token — ES256 JWT (only present when format: 'jwt' is requested). Verifiable with any standard JWT library using the JWKS endpoint." } } }, "meta": { "type": "object", "properties": { "creditsRemaining": { "type": "integer" }, "creditsCharged": { "type": "integer", "description": "1 for standard, 2 for proof: merkle" }, "version": { "type": "string" }, "timestamp": { "type": "string" } } } } } } } }, "402": { "description": "Payment Required. x402 v2 quote: sign the USDC authorization on Base and retry with the X-PAYMENT header. x402 pay-per-call: $0.05 per attestation, $0.10 with proof: merkle. Or 1-2 credits with an API key." } }, "x-payment-info": { "price": { "mode": "dynamic", "currency": "USD", "min": "0.05", "max": "0.10" }, "protocols": [ { "x402": {} } ] }, "security": [] } }, "/v1/compliance/templates": { "get": { "operationId": "listComplianceTemplates", "summary": "List EAS compliance templates", "description": "Lists available compliance templates for EAS attestation verification. Templates provide pre-configured schema IDs for Coinbase Verifications (Base) and Gitcoin Passport (Optimism). Free, no auth required.\n", "security": [], "responses": { "200": { "description": "Compliance template catalog", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object", "properties": { "templates": { "type": "object", "description": "Template name to config mapping", "additionalProperties": { "type": "object", "properties": { "provider": { "type": "string" }, "description": { "type": "string" }, "chainId": { "type": "integer" }, "chainName": { "type": "string" } } } } } } } } } } } } } }, "/v1/trust": { "post": { "operationId": "walletTrust", "summary": "Wallet trust fact profile", "description": "ECDSA-signed wallet trust profile. 44 base checks across 25 chains in 5 dimensions (stablecoins USDC/USDT, governance, NFTs, staking, institutional stablecoins). Optional Solana/XRPL/Bitcoin/Tron wallets add dimensions, up to 49 checks across 27 chains. 3 credits, 6 with merkle.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "wallet" ], "properties": { "wallet": { "type": "string", "description": "EVM wallet address (0x followed by 40 hex chars)" }, "solanaWallet": { "type": "string", "description": "Solana wallet address (base58). If provided, adds Solana USDC check." }, "xrplWallet": { "type": "string", "description": "XRPL wallet address (r-address). If provided, adds XRPL stablecoin checks (RLUSD + USDC)." }, "bitcoinWallet": { "type": "string", "description": "Bitcoin address. If provided, adds Bitcoin Holdings (native BTC)." }, "tronWallet": { "type": "string", "description": "Tron T-address. If provided, adds Tron USDT-TRC20 check." }, "stellarWallet": { "type": "string", "description": "Stellar G-address. If provided, adds USDC + BENJI on Stellar (institutional_stablecoins)." }, "suiWallet": { "type": "string", "description": "Sui address (0x + 64 hex chars). If provided, adds USDC on Sui (institutional_stablecoins)." }, "proof": { "type": "string", "enum": [ "merkle" ], "description": "Set to 'merkle' for EIP-1186 Merkle storage proofs. 6 credits." } } } } } }, "responses": { "200": { "description": "Trust fact profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object", "properties": { "trust": { "type": "object", "properties": { "id": { "type": "string", "description": "Format: TRST-XXXXX" }, "wallet": { "type": "string" }, "conditionSetVersion": { "type": "string" }, "dimensions": { "type": "object", "description": "Object with keys: stablecoins, governance, nfts, staking, solana (if solanaWallet provided), xrpl (if xrplWallet provided)", "additionalProperties": { "type": "object", "properties": { "checks": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "chainId": { "oneOf": [ { "type": "integer" }, { "type": "string", "enum": [ "solana", "xrpl", "bitcoin", "tron", "stellar", "sui" ] } ] }, "met": { "type": "boolean" }, "evaluatedCondition": { "type": "object" }, "conditionHash": { "type": "string" }, "blockNumber": { "type": "string" }, "blockTimestamp": { "type": "string" }, "ledgerIndex": { "type": "integer", "description": "XRPL validated ledger index (XRPL only)" }, "ledgerHash": { "type": "string", "description": "XRPL validated ledger hash (XRPL only)" }, "trustLineState": { "type": "object", "description": "Trust line state flags (XRPL trust line tokens only). Frozen lines fail attestation.", "properties": { "frozen": { "type": "boolean" } } }, "slot": { "type": "integer", "description": "Solana slot at which the condition was evaluated. Present only for Solana conditions. Verifiers can reproduce the read by querying wallet state at this slot or later." }, "blockHeight": { "type": "integer", "description": "Bitcoin chain tip block height at observation time. Present only for Bitcoin checks. Evidence-of-freshness anchor — Bitcoin's UTXO model does not permit reproducible balance-at-block queries." }, "blockHash": { "type": "string", "description": "Bitcoin chain tip block hash (64-char hex) at observation time. Present only for Bitcoin checks. Co-reported with blockHeight." }, "proof": { "type": "object" } } } }, "passCount": { "type": "integer" }, "failCount": { "type": "integer" }, "total": { "type": "integer" } } } }, "summary": { "type": "object", "properties": { "totalChecks": { "type": "integer" }, "totalPassed": { "type": "integer" }, "totalFailed": { "type": "integer" }, "dimensionsWithActivity": { "type": "integer" }, "dimensionsChecked": { "type": "integer" } } }, "profiledAt": { "type": "string" }, "expiresAt": { "type": "string" } } }, "sig": { "type": "string", "description": "ECDSA P-256 signature over the trust object (base64)" }, "kid": { "type": "string", "description": "Key ID for JWKS lookup" } } }, "meta": { "type": "object", "properties": { "creditsRemaining": { "type": "integer" }, "creditsCharged": { "type": "integer", "description": "3 for standard, 6 for proof: merkle" }, "version": { "type": "string" }, "timestamp": { "type": "string" } } } } } } } }, "402": { "description": "Payment Required. x402 v2 quote: sign the USDC authorization on Base and retry with the X-PAYMENT header. x402 pay-per-call: $0.15 per profile, $0.30 with Merkle proofs. Or 3-6 credits with an API key." } }, "x-payment-info": { "price": { "mode": "dynamic", "currency": "USD", "min": "0.15", "max": "0.30" }, "protocols": [ { "x402": {} } ] }, "security": [] } }, "/v1/trust/batch": { "post": { "operationId": "batchWalletTrust", "summary": "Batch wallet trust profiles", "description": "Profile up to 10 wallets in one request. Block numbers fetched once (5-8x faster than sequential calls). Each wallet gets an independently ECDSA-signed profile. Partial success supported. 3 credits/wallet, 6 with merkle.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "wallets" ], "properties": { "wallets": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "object", "required": [ "wallet" ], "properties": { "wallet": { "type": "string", "description": "EVM wallet address (0x...)" }, "solanaWallet": { "type": "string", "description": "Solana wallet (base58). Adds Solana USDC check." }, "xrplWallet": { "type": "string", "description": "XRPL wallet (r-address). Adds XRPL stablecoin checks (RLUSD + USDC)." }, "bitcoinWallet": { "type": "string", "description": "Bitcoin address. Adds Bitcoin Holdings (native BTC)." }, "tronWallet": { "type": "string", "description": "Tron T-address. Adds Tron USDT-TRC20 check." }, "stellarWallet": { "type": "string", "description": "Stellar G-address. Adds USDC + BENJI on Stellar (institutional_stablecoins)." }, "suiWallet": { "type": "string", "description": "Sui address. Adds USDC on Sui (institutional_stablecoins)." } } } }, "proof": { "type": "string", "enum": [ "merkle" ], "description": "EIP-1186 Merkle proofs. 6 credits/wallet." } } } } } }, "responses": { "200": { "description": "Batch trust profiles", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object", "properties": { "results": { "type": "array", "description": "One entry per wallet (trust profile or error)", "items": { "type": "object", "properties": { "trust": { "type": "object", "description": "Full trust profile (same as POST /v1/trust)" }, "sig": { "type": "string" }, "kid": { "type": "string" }, "error": { "type": "object", "properties": { "wallet": { "type": "string" }, "message": { "type": "string" } } } } } }, "summary": { "type": "object", "properties": { "requested": { "type": "integer" }, "succeeded": { "type": "integer" }, "failed": { "type": "integer" } } } } }, "meta": { "type": "object", "properties": { "creditsCharged": { "type": "integer" }, "creditsRemaining": { "type": "integer" }, "version": { "type": "string" }, "timestamp": { "type": "string" } } } } } } } }, "402": { "description": "Payment Required. x402 v2 quote: sign the USDC authorization on Base and retry with the X-PAYMENT header. x402 pay-per-call: $0.15 per wallet ($0.30 with proofs), up to 10 wallets per call. Or credits with an API key." } }, "x-payment-info": { "price": { "mode": "dynamic", "currency": "USD", "min": "0.15", "max": "3.00" }, "protocols": [ { "x402": {} } ] }, "security": [] } }, "/v1/credits": { "get": { "operationId": "getCredits", "summary": "Check verification credit balance", "description": "Returns the verification credit balance, tier, and daily rate limit for the authenticated API key.", "responses": { "200": { "description": "Credit balance", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object", "properties": { "apiKeyCredits": { "type": "integer" }, "tier": { "type": "string", "description": "free, pro, or enterprise" }, "dailyLimit": { "type": "integer" } } }, "meta": { "type": "object", "properties": { "version": { "type": "string" }, "timestamp": { "type": "string" } } } } } } } } } } }, "/v1/merchants": { "get": { "operationId": "listMerchants", "summary": "List merchants in public directory", "description": "Browse merchants that reward token and NFT holders. Returns public directory listings with optional filters.", "security": [], "parameters": [ { "name": "token", "in": "query", "schema": { "type": "string" }, "description": "Filter by accepted token symbol (e.g. UNI, SHIB)" }, { "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 }, "description": "Results per page (max 200)" }, { "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" }, "data": { "type": "array", "items": { "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", "description": "highest, stack, or capped" }, "discountCap": { "type": "integer" } } } }, "meta": { "type": "object", "properties": { "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "version": { "type": "string" }, "timestamp": { "type": "string" } } } } } } } } } }, "post": { "operationId": "createMerchant", "summary": "Create a new merchant", "description": "Create a merchant programmatically. Receives 100 free verification credits. The API key that creates the merchant owns it. Max 10 merchants per API key.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "companyName", "companyId" ], "properties": { "companyName": { "type": "string", "description": "Display name" }, "companyId": { "type": "string", "description": "Unique ID (alphanumeric, dash, underscore)" }, "location": { "type": "string", "description": "City or region" }, "externalId": { "type": "string", "description": "Optional partner handle. Makes the call an idempotent upsert and requires domain verification before the merchant can publish." } } } } } }, "responses": { "201": { "description": "Merchant created", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyName": { "type": "string" }, "credits": { "type": "integer" }, "apiAccessEnabled": { "type": "boolean" } } } } } } } } } } }, "/v1/merchants/{id}": { "get": { "operationId": "getMerchant", "summary": "Get merchant details", "description": "Returns full public merchant profile including token tiers, NFT collections, and discount settings.", "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" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyName": { "type": "string" }, "website": { "type": "string" }, "location": { "type": "string" }, "verified": { "type": "boolean" }, "verifiedDomain": { "type": "string" }, "discountMode": { "type": "string", "description": "highest, stack, or capped" }, "discountCap": { "type": "integer" }, "tokens": { "type": "array", "items": { "type": "object" } }, "ownToken": { "type": "object", "nullable": true }, "partnerTokens": { "type": "array", "items": { "type": "object" } }, "nftCollections": { "type": "array", "items": { "type": "object" } }, "acceptsUsdc": { "type": "boolean" } } }, "meta": { "type": "object", "properties": { "version": { "type": "string" }, "timestamp": { "type": "string" } } } } } } } } } } }, "/v1/tokens": { "get": { "operationId": "listTokens", "summary": "List registered tokens and NFTs", "description": "Returns all tokens and NFT collections in the registry. Use filters to narrow results by chain, symbol, or type.", "security": [], "parameters": [ { "name": "chain", "in": "query", "schema": { "oneOf": [ { "type": "integer" }, { "type": "string", "enum": [ "solana", "xrpl", "bitcoin", "tron", "stellar", "sui" ] } ] }, "description": "Filter by chain ID (integer for EVM, or 'solana'/'xrpl')" }, { "name": "symbol", "in": "query", "schema": { "type": "string" }, "description": "Filter by token symbol (e.g. UNI)" }, { "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" }, "data": { "type": "object", "properties": { "tokens": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "symbol": { "type": "string" }, "name": { "type": "string" }, "chainId": { "type": "integer" }, "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": { "type": "integer" }, "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" } } } } } } } } } } }, "/v1/discount/check": { "get": { "operationId": "checkDiscount", "summary": "Calculate discount for wallet at merchant", "description": "Checks on-chain balances and calculates the total discount a wallet qualifies for at a specific merchant. Free to call — does not consume credits. Provide wallet (0x address) for EVM chains, solanaWallet for Solana, and/or xrplWallet for XRPL.\n", "security": [], "parameters": [ { "name": "wallet", "in": "query", "schema": { "type": "string" }, "description": "EVM wallet address (0x followed by 40 hex chars)" }, { "name": "solanaWallet", "in": "query", "schema": { "type": "string" }, "description": "Solana wallet address (base58 encoded)" }, { "name": "xrplWallet", "in": "query", "schema": { "type": "string" }, "description": "XRPL wallet address (r-address)" }, { "name": "merchant", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Merchant ID" } ], "responses": { "200": { "description": "Discount calculation", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object", "properties": { "eligible": { "type": "boolean" }, "totalDiscount": { "type": "integer", "description": "Total discount percentage" }, "discountMode": { "type": "string", "description": "highest, stack, or capped" }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "symbol": { "type": "string" }, "tier": { "type": "string" }, "discount": { "type": "integer" }, "chain": { "type": "string" } } } }, "merchantId": { "type": "string" }, "merchantName": { "type": "string" }, "chainsChecked": { "type": "array", "items": { "type": "string" } } } }, "meta": { "type": "object", "properties": { "version": { "type": "string" }, "timestamp": { "type": "string" } } } } } } } } } } }, "/v1/verify": { "post": { "operationId": "createVerification", "summary": "Create signed discount code", "description": "Creates a signed discount verification code (INSR-XXXXX) valid for 30 minutes. Consumes 1 merchant credit. The code can be presented at checkout for the calculated discount. Provide wallet (0x) for EVM, solanaWallet for Solana, and/or xrplWallet for XRPL.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "merchantId" ], "properties": { "merchantId": { "type": "string", "description": "Merchant ID" }, "wallet": { "type": "string", "description": "EVM wallet address (0x followed by 40 hex chars)" }, "solanaWallet": { "type": "string", "description": "Solana wallet address (base58 encoded)" }, "xrplWallet": { "type": "string", "description": "XRPL wallet address (r-address)" } } } } } }, "responses": { "200": { "description": "Verification code created", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object", "properties": { "verified": { "type": "boolean" }, "totalDiscount": { "type": "integer", "description": "Total discount percentage" }, "code": { "type": "string", "description": "Discount code (format: INSR-XXXXX), valid 30 minutes" }, "expiresAt": { "type": "string" }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "symbol": { "type": "string" }, "tier": { "type": "string" }, "discount": { "type": "integer" } } } }, "stripeCodeCreated": { "type": "boolean" }, "cloverDiscountName": { "type": "string", "nullable": true }, "merchantName": { "type": "string" }, "sig": { "type": "string", "description": "ECDSA P-256 signature" }, "usdcPayment": { "type": "object", "nullable": true, "description": "Present when merchant has USDC payments enabled", "properties": { "evmAddress": { "type": "string" }, "preferredChainId": { "type": "integer" }, "preferredChainName": { "type": "string" }, "usdcContract": { "type": "string" }, "solanaAddress": { "type": "string", "nullable": true }, "supportedChains": { "type": "array", "items": { "type": "object", "properties": { "chainId": { "type": "integer" }, "name": { "type": "string" }, "usdcContract": { "type": "string" } } } } } } } }, "meta": { "type": "object", "properties": { "version": { "type": "string" }, "timestamp": { "type": "string" } } } } } } } } } } }, "/v1/registry/submit": { "post": { "operationId": "submitToRegistry", "summary": "Submit a token or NFT to the public registry (pending review)", "description": "Submit a token or NFT collection to the public registry, pending human approval. X-API-Key required (free). Set assetType ('token'/'nft'), else inferred from standard (defaults NFT). Token submissions require symbol. Idempotent per chain+address. Flat envelope. Nothing goes live until approved.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "chainId" ], "properties": { "name": { "type": "string" }, "assetType": { "type": "string", "enum": [ "token", "nft" ], "description": "'token' → tokenRegistry; 'nft' → nftRegistry. If omitted, inferred from standard (default nft). 'token' requires symbol." }, "contractAddress": { "type": "string", "description": "EVM contract address (or use mintAddress for Solana)." }, "mintAddress": { "type": "string", "description": "Solana mint address (or use contractAddress)." }, "chainId": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Positive integer for EVM, or the string 'solana'." }, "chainName": { "type": "string" }, "symbol": { "type": "string", "description": "Ticker symbol. Required for token submissions; ignored for NFTs." }, "decimals": { "type": "integer", "description": "Token decimals (token submissions only)." }, "standard": { "type": "string", "description": "e.g. ERC-721, ERC-20, ERC-3643. Used to infer assetType when omitted." }, "image": { "type": "string", "description": "Collection image URL (NFT). For tokens use logo." }, "logo": { "type": "string", "description": "Token logo URL (token; image accepted as fallback)." }, "website": { "type": "string" }, "description": { "type": "string" }, "coingeckoId": { "type": "string", "description": "CoinGecko id for market-cap lookup (token submissions only)." }, "source": { "type": "string", "description": "Provenance tag for the admin review queue (e.g. 'partner-app')." } } } } } }, "responses": { "200": { "description": "Already listed (idempotent)", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "alreadyListed": { "type": "boolean" }, "docId": { "type": "string" } } } } } }, "201": { "description": "Submitted (pending review)", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "pending": { "type": "boolean" }, "docId": { "type": "string" }, "assetType": { "type": "string", "enum": [ "token", "nft" ], "description": "Which bucket the submission was routed into." }, "message": { "type": "string" } } } } } } } } }, "/v1/acp/discount": { "post": { "operationId": "acpDiscount", "summary": "ACP-format discount eligibility check", "description": "Checks token-holder discount eligibility in OpenAI/Stripe Agentic Commerce Protocol format. Returns coupon objects, applied/rejected arrays, per-item allocations. Same verification as createVerification, in ACP format. 1 credit.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "merchantId" ], "properties": { "merchantId": { "type": "string", "description": "Merchant ID" }, "wallet": { "type": "string", "description": "EVM wallet address (0x followed by 40 hex chars)" }, "solanaWallet": { "type": "string", "description": "Solana wallet address (base58 encoded)" }, "xrplWallet": { "type": "string", "description": "XRPL wallet address (r-address)" }, "items": { "type": "array", "description": "Optional line items for per-item cent-amount allocations", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSONPath reference, e.g. $.line_items[0]" }, "amount": { "type": "integer", "description": "Item price in cents" } } } } } } } } }, "responses": { "200": { "description": "ACP-format discount response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object", "properties": { "protocol": { "type": "string" }, "version": { "type": "string" }, "discounts": { "type": "object", "properties": { "codes": { "type": "array", "items": { "type": "string" } }, "applied": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "coupon": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "percent_off": { "type": "integer" } } }, "amount": { "type": "integer", "nullable": true }, "automatic": { "type": "boolean" }, "method": { "type": "string" }, "priority": { "type": "integer" }, "allocations": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "amount": { "type": "integer" } } } }, "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" } } } }, "rejected": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "reason": { "type": "string" } } } } } }, "verification": { "type": "object", "properties": { "code": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "breakdown": { "type": "array", "items": { "type": "object", "properties": { "symbol": { "type": "string" }, "tier": { "type": "string" }, "discount": { "type": "integer" } } } }, "sig": { "type": "string" }, "kid": { "type": "string" } } } } }, "meta": { "type": "object", "properties": { "creditsRemaining": { "type": "integer" }, "creditsCharged": { "type": "integer" }, "version": { "type": "string" }, "timestamp": { "type": "string" } } } } } } } } } } }, "/v1/ucp/discount": { "post": { "operationId": "ucpDiscount", "summary": "UCP-format discount eligibility check", "description": "Checks token-holder discount eligibility in Google Universal Commerce Protocol format. Returns title, extension field, applied array. Same verification as createVerification, in UCP format. 1 merchant credit.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "merchantId" ], "properties": { "merchantId": { "type": "string", "description": "Merchant ID" }, "wallet": { "type": "string", "description": "EVM wallet address (0x followed by 40 hex chars)" }, "solanaWallet": { "type": "string", "description": "Solana wallet address (base58 encoded)" }, "xrplWallet": { "type": "string", "description": "XRPL wallet address (r-address)" }, "items": { "type": "array", "description": "Optional line items for per-item cent-amount allocations", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "JSONPath reference, e.g. $.line_items[0]" }, "amount": { "type": "integer", "description": "Item price in cents" } } } } } } } } }, "responses": { "200": { "description": "UCP-format discount response", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object", "properties": { "protocol": { "type": "string" }, "version": { "type": "string" }, "extension": { "type": "string" }, "discounts": { "type": "object", "properties": { "codes": { "type": "array", "items": { "type": "string" } }, "applied": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "title": { "type": "string" }, "amount": { "type": "integer", "nullable": true }, "automatic": { "type": "boolean" }, "method": { "type": "string" }, "priority": { "type": "integer" }, "allocations": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "amount": { "type": "integer" } } } } } } } } }, "verification": { "type": "object", "properties": { "code": { "type": "string" }, "expiresAt": { "type": "string" }, "sig": { "type": "string" }, "kid": { "type": "string" } } } } }, "meta": { "type": "object", "properties": { "creditsRemaining": { "type": "integer" }, "creditsCharged": { "type": "integer" }, "version": { "type": "string" }, "timestamp": { "type": "string" } } } } } } } } } } }, "/v1/codes/{code}": { "get": { "operationId": "validateCode", "summary": "Validate INSR-XXXXX discount code", "description": "Validates a discount code for merchant backends during ACP/UCP checkout. No authentication required, no credits consumed. Returns validity, discount percent, and expiry. Does not expose wallet or token data.\n", "security": [], "parameters": [ { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Discount code in INSR-XXXXX format" } ], "responses": { "200": { "description": "Code validation result", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object", "properties": { "valid": { "type": "boolean" }, "code": { "type": "string" }, "merchantId": { "type": "string", "description": "Present when valid" }, "discountPercent": { "type": "integer", "description": "Present when valid" }, "expiresAt": { "type": "string", "description": "Present when valid" }, "reason": { "type": "string", "description": "Present when invalid: expired, already_used, not_found" } } }, "meta": { "type": "object", "properties": { "version": { "type": "string" }, "timestamp": { "type": "string" } } } } } } } } } } }, "/v1/jwks": { "get": { "operationId": "getJwks", "summary": "Get JWKS (public key set)", "description": "Returns the JSON Web Key Set containing InsumerAPI's ECDSA P-256 public signing key. Use this to verify attestation signatures. No authentication required. Cached 24h.\n", "security": [], "responses": { "200": { "description": "JWKS document", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "properties": { "kty": { "type": "string" }, "crv": { "type": "string" }, "x": { "type": "string" }, "y": { "type": "string" }, "use": { "type": "string" }, "alg": { "type": "string" }, "kid": { "type": "string" } } } } } } } } } } } }, "/v1/credits/buy": { "post": { "operationId": "buyCredits", "summary": "Buy verification credits with USDC, USDT, or BTC", "description": "Buy credits with USDC, USDT, or BTC. Send to the platform wallet, submit txHash. USDC/USDT auto-detected on EVM/Solana; BTC market-rate USD, 1 confirmation. Volume discounts apply. First purchase registers sender wallet; subsequent must match (403). Set updateWallet: true to change.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "txHash", "chainId" ], "properties": { "txHash": { "type": "string", "description": "Transaction hash proving payment" }, "chainId": { "oneOf": [ { "type": "integer", "enum": [ 1, 56, 8453, 43114, 137, 42161, 10 ] }, { "type": "string", "enum": [ "solana", "bitcoin" ] } ], "description": "Chain where payment was sent" }, "amount": { "type": "number", "minimum": 5, "description": "Stablecoin amount sent (min 5). Not required for BTC — USD value derived from on-chain BTC amount at market rate." }, "updateWallet": { "type": "boolean", "default": false, "description": "Set true to change the registered sender wallet for this API key. The verified transfer from the new address proves ownership." } } } } } }, "responses": { "200": { "description": "Credits purchased", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object", "properties": { "creditsAdded": { "type": "integer" }, "totalCredits": { "type": "integer" }, "usdcPaid": { "type": "string" }, "chainName": { "type": "string" } } } } } } } } } } }, "/v1/payment/confirm": { "post": { "operationId": "confirmPayment", "summary": "Confirm USDC payment for discount code", "description": "After /v1/verify generates a discount code, confirm that a USDC payment was made on-chain. The server checks the transaction receipt to verify USDC arrived at the merchant address.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "txHash", "chainId", "amount" ], "properties": { "code": { "type": "string", "description": "Discount code (e.g. INSR-A7K3M)" }, "txHash": { "type": "string", "description": "On-chain transaction hash" }, "chainId": { "oneOf": [ { "type": "integer", "enum": [ 1, 56, 8453, 43114, 137, 42161, 10 ] }, { "type": "string", "enum": [ "solana" ] } ], "description": "Chain where USDC was sent" }, "amount": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "description": "USDC amount sent" } } } } } }, "responses": { "200": { "description": "Payment confirmed", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object", "properties": { "confirmed": { "type": "boolean" }, "code": { "type": "string" }, "txHash": { "type": "string" }, "chainId": { "type": "integer", "description": "Chain ID where USDC payment was confirmed" }, "chainName": { "type": "string" }, "amountVerified": { "type": "string" }, "confirmedAt": { "type": "string" } } } } } } } } } } }, "/v1/merchants/{id}/status": { "get": { "operationId": "getMerchantStatus", "summary": "Get full private merchant details", "description": "Returns full details including credits, token configs, directory status, domain verification status, and USDC settings. Only accessible by the API key that created the merchant.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Merchant ID" } ], "responses": { "200": { "description": "Full merchant status", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "companyName": { "type": "string" }, "location": { "type": "string" }, "credits": { "type": "integer" }, "apiAccessEnabled": { "type": "boolean" }, "discountMode": { "type": "string" }, "discountCap": { "type": "integer" }, "listedInDirectory": { "type": "boolean" }, "ownToken": { "type": "object", "nullable": true }, "partnerTokens": { "type": "array", "items": { "type": "object" } }, "nftCollections": { "type": "array", "items": { "type": "object" } }, "usdcPayment": { "type": "object", "nullable": true }, "verification": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "unverified", "pending", "verified" ] }, "domain": { "type": "string", "nullable": true }, "method": { "type": "string", "nullable": true, "enum": [ "dns", "meta", "file" ] }, "verifiedAt": { "type": "string", "nullable": true } } }, "createdAt": { "type": "object", "description": "Firestore timestamp object", "properties": { "_seconds": { "type": "integer" }, "_nanoseconds": { "type": "integer" } } } } } } } } } } } } }, "/v1/merchants/{id}/tokens": { "put": { "operationId": "updateMerchantTokens", "summary": "Configure merchant token tiers", "description": "Set up the merchant's own token and/or partner tokens with discount tiers. Max 8 tokens total. Must be called by the API key that created the merchant. For XRPL tokens: use chainId \"xrpl\", contractAddress as issuer r-address or \"native\" for XRP, add \"currency\" for trust line tokens.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Merchant ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ownToken": { "type": "object", "nullable": true, "description": "Merchant's own token config, or null to disable", "properties": { "symbol": { "type": "string" }, "name": { "type": "string", "description": "Optional display name shown in the directory listing." }, "logo": { "type": "string", "description": "Optional logo URL shown in the directory listing." }, "chainId": { "oneOf": [ { "type": "integer" }, { "type": "string", "enum": [ "solana", "xrpl", "bitcoin", "tron", "stellar", "sui" ] } ], "description": "EVM chain ID (integer), or 'solana'/'xrpl' (string)" }, "contractAddress": { "type": "string", "description": "EVM 0x address, Solana mint, XRPL issuer r-address, or 'native' for XRP" }, "decimals": { "type": "integer" }, "currency": { "type": "string", "description": "XRPL trust line currency code (e.g. 'RLUSD'). Only for XRPL." }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "threshold": { "type": "number" }, "discount": { "type": "integer" } } } } } }, "partnerTokens": { "type": "array", "items": { "type": "object", "properties": { "symbol": { "type": "string" }, "chainId": { "oneOf": [ { "type": "integer" }, { "type": "string", "enum": [ "solana", "xrpl", "bitcoin", "tron", "stellar", "sui" ] } ] }, "contractAddress": { "type": "string" }, "decimals": { "type": "integer" }, "currency": { "type": "string", "description": "XRPL trust line currency code (only for XRPL)" }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "threshold": { "type": "number" }, "discount": { "type": "integer" } } } } } } } } } } } }, "responses": { "200": { "description": "Tokens configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object", "properties": { "ownToken": { "type": "object", "nullable": true }, "partnerTokens": { "type": "array", "items": { "type": "object" } }, "totalTokens": { "type": "integer" }, "maxTokens": { "type": "integer" } } } } } } } } } } }, "/v1/merchants/{id}/nfts": { "put": { "operationId": "updateMerchantNfts", "summary": "Configure NFT collections", "description": "Set NFT collections that grant discounts. Max 4 collections. Must be called by the API key that created the merchant. For XRPL NFTs: use chainId \"xrpl\", contractAddress as issuer r-address, optional \"taxon\" field to filter by NFToken taxon.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Merchant ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "nftCollections" ], "properties": { "nftCollections": { "type": "array", "maxItems": 4, "items": { "type": "object", "properties": { "name": { "type": "string" }, "contractAddress": { "type": "string", "description": "EVM 0x address, or XRPL issuer r-address" }, "chainId": { "oneOf": [ { "type": "integer" }, { "type": "string", "enum": [ "xrpl" ] } ], "description": "EVM chain ID (integer) or 'xrpl' (string)" }, "discount": { "type": "integer" }, "taxon": { "type": "integer", "description": "XRPL NFToken taxon filter (optional, XRPL only)" } } } } } } } } }, "responses": { "200": { "description": "NFTs configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object", "properties": { "nftCollections": { "type": "array", "items": { "type": "object" } }, "totalCollections": { "type": "integer" }, "maxCollections": { "type": "integer" } } } } } } } } } } }, "/v1/merchants/{id}/settings": { "put": { "operationId": "updateMerchantSettings", "summary": "Update merchant settings", "description": "Update discount stacking mode, cap, and USDC payment settings. All fields optional. Must be called by the API key that created the merchant.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Merchant ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "discountMode": { "type": "string", "enum": [ "highest", "stack", "capped" ], "description": "'highest' uses best single discount, 'stack' sums all, 'capped' sums all then caps at discountCap" }, "discountCap": { "type": "integer", "description": "Maximum total discount percentage (1-100)" }, "usdcPayment": { "type": "object", "nullable": true, "description": "USDC payment config, or null to disable", "properties": { "enabled": { "type": "boolean" }, "evmAddress": { "type": "string", "description": "EVM wallet for USDC (0x + 40 hex)" }, "solanaAddress": { "type": "string", "description": "Solana wallet for USDC (base58)" }, "preferredChainId": { "oneOf": [ { "type": "integer", "enum": [ 1, 56, 8453, 43114, 137, 42161, 10 ] }, { "type": "string", "enum": [ "solana" ] } ] } } } } } } } }, "responses": { "200": { "description": "Settings updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object", "properties": { "discountMode": { "type": "string" }, "discountCap": { "type": "integer" }, "usdcPayment": { "type": "object", "nullable": true } } } } } } } } } } }, "/v1/merchants/{id}/credits": { "post": { "operationId": "buyMerchantCredits", "summary": "Buy merchant credits with USDC, USDT, or BTC", "description": "Buy merchant credits with USDC, USDT, or BTC (consumed by /v1/verify). Send to the platform wallet, submit txHash. USDC/USDT auto-detected on EVM/Solana; BTC market-rate USD, 1 confirmation. Volume discounts apply. Same sender-wallet check as buyCredits.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Merchant ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "txHash", "chainId" ], "properties": { "txHash": { "type": "string", "description": "Transaction hash proving payment" }, "chainId": { "oneOf": [ { "type": "integer", "enum": [ 1, 56, 8453, 43114, 137, 42161, 10 ] }, { "type": "string", "enum": [ "solana", "bitcoin" ] } ], "description": "Chain where payment was sent" }, "amount": { "type": "number", "minimum": 5, "description": "Stablecoin amount sent (min 5). Not required for BTC — USD value derived from on-chain BTC amount at market rate." }, "updateWallet": { "type": "boolean", "default": false, "description": "Set true to change the registered sender wallet for this API key. The verified transfer from the new address proves ownership." } } } } } }, "responses": { "200": { "description": "Credits purchased", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object", "properties": { "creditsAdded": { "type": "integer" }, "totalCredits": { "type": "integer" }, "usdcPaid": { "type": "string" }, "chainName": { "type": "string" } } } } } } } } } } }, "/v1/merchants/{id}/directory": { "post": { "operationId": "publishToDirectory", "summary": "Publish or unpublish merchant in public directory", "description": "Publish (or refresh) the merchant's listing in the public directory. No body needed to publish. Send { \"listed\": false } to unpublish (delist). Partner- provisioned merchants (externalId set) must pass domain verification first.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Merchant ID" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "listed": { "type": "boolean", "description": "Set false to unpublish (delist). Omit to publish/refresh." } } } } } }, "responses": { "200": { "description": "Published, or unpublished when listed=false", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "published": { "type": "boolean" }, "tokensListed": { "type": "integer" }, "nftCollectionsListed": { "type": "integer" } } } } } } } } } } }, "/v1/merchants/{id}/domain-verification": { "post": { "operationId": "requestDomainVerification", "summary": "Request domain verification token", "description": "Generates a verification token for proving domain ownership. Place via DNS TXT record, HTML meta tag, or a verification file. Each POST regenerates the token. Only the API key that created the merchant can call this.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Merchant ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "description": "Domain to verify (e.g. example.com). No protocol prefix." } } } } } }, "responses": { "200": { "description": "Verification token generated", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object", "properties": { "domain": { "type": "string" }, "token": { "type": "string", "description": "Verification token (insumer-XXXXXXXXXXXXXXXX)" }, "methods": { "type": "object", "properties": { "dns": { "type": "object", "properties": { "type": { "type": "string" }, "host": { "type": "string" }, "value": { "type": "string" }, "instructions": { "type": "string" } } }, "meta": { "type": "object", "properties": { "tag": { "type": "string" }, "instructions": { "type": "string" } } }, "file": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" }, "instructions": { "type": "string" } } } } } } } } } } } } } }, "put": { "operationId": "verifyDomain", "summary": "Trigger domain verification check", "description": "Checks all three verification methods (DNS TXT, meta tag, file) for the previously requested domain. Rate limited to 5 attempts per hour per merchant. Only the API key that created the merchant can call this.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Merchant ID" } ], "responses": { "200": { "description": "Verification result", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object", "properties": { "verified": { "type": "boolean" }, "domain": { "type": "string" }, "method": { "type": "string", "description": "Present only when verified (dns, meta, or file)" }, "verifiedAt": { "type": "string", "description": "Present only when verified" }, "message": { "type": "string", "description": "Present only when not verified" }, "attemptsRemaining": { "type": "integer", "description": "Present only when not verified" } } } } } } } } } } }, "/v1/merchants/{id}/verification": { "put": { "operationId": "partnerAssertDomain", "summary": "White-label partner asserts domain ownership", "description": "Record that a managing white-label partner verified an org's domain in its own branded flow (sets verification.status=verified, method=partner). RESTRICTED to designated white-label partner keys; self-serve keys must use the domain-verification challenge flow instead.\n", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Merchant ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "description": "Domain the partner verified (no protocol prefix)." } } } } } }, "responses": { "200": { "description": "Domain marked verified", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object", "properties": { "verified": { "type": "boolean" }, "domain": { "type": "string" }, "method": { "type": "string" } } } } } } } } } } }, "/v1/keys/buy": { "post": { "operationId": "buyKey", "summary": "Buy a new API key with USDC, USDT, or BTC (no auth required)", "security": [], "description": "Buy API key with USDC/USDT/BTC, no auth. Send to platform wallet; submit txHash/chainId/appName (amount required for stablecoins, not BTC). USDC/USDT auto-detected on EVM/Solana; BTC market-rate USD, 1 confirmation. Sender wallet = key identity. One key per wallet. Volume discounts apply.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "txHash", "chainId", "appName" ], "properties": { "txHash": { "type": "string", "description": "Transaction hash proving payment" }, "chainId": { "oneOf": [ { "type": "integer", "enum": [ 1, 56, 8453, 43114, 137, 42161, 10 ] }, { "type": "string", "enum": [ "solana", "bitcoin" ] } ], "description": "Chain where payment was sent" }, "amount": { "type": "number", "minimum": 5, "description": "Stablecoin amount sent (min 5). Not required for BTC — USD value derived from on-chain BTC amount at market rate." }, "appName": { "type": "string", "description": "Name for this API key (e.g. your agent or app name)" }, "keyDelivery": { "type": "string", "enum": [ "wallet", "apiKey", "both" ], "default": "wallet", "description": "Credential shape. Default 'wallet' returns no API key string on EVM buys (the wallet + Insumer Access pass IS the credential). 'apiKey'/'both' returns the key. Pass 'apiKey' if you need the key string." } } } } } }, "responses": { "200": { "description": "API key created with credits", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "data": { "type": "object", "properties": { "success": { "type": "boolean" }, "key": { "type": "string", "description": "API key (store securely — shown only once). Omitted when keyDelivery defaults to 'wallet' and an SBT mints; always returned otherwise." }, "authMethod": { "type": "string", "enum": [ "wallet", "apiKey", "both" ], "description": "Which credential was delivered: 'wallet' (SBT only, no key), 'apiKey' (key only, no SBT), or 'both'." }, "name": { "type": "string" }, "tier": { "type": "string" }, "dailyLimit": { "type": "integer" }, "creditsAdded": { "type": "integer" }, "totalCredits": { "type": "integer" }, "usdcPaid": { "type": "string" }, "effectiveRate": { "type": "string" }, "chainName": { "type": "string" }, "registeredWallet": { "type": "string", "description": "Wallet address registered to this key (extracted from transaction)" } } } } } } } } } } } } }