insumermodel-com Platform API

openapi: 3.2.0
info:
  title: Insumer Platform 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: Platform
  description: Service health and chain-support requests.
paths:
  /v1/health:
    get:
      operationId: healthCheck
      summary: Service health check (no auth required)
      description: Liveness probe covering the API, its datastore, and the attestation signing key. Returns 200 when all checks pass, 503 when any fails. Response is a flat status object, not the standard envelope.
      tags:
      - Platform
      security: []
      responses:
        '200':
          description: All checks passing
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  checks:
                    type: object
                    properties:
                      api:
                        type: string
                        example: ok
                      timestamp:
                        type: string
                        format: date-time
                      datastore:
                        type: string
                        example: ok
                      signing:
                        type: string
                        example: ok
                  meta:
                    type: object
                    properties:
                      version:
                        type: string
                        example: '1.0'
        '500':
          $ref: '#/components/responses/ServerError'
        '503':
          description: One or more checks failing (same shape, ok=false)
  /v1/chain-request:
    post:
      operationId: requestChainSupport
      summary: Request support for a new blockchain (no auth required)
      description: 'Public intake for chain-support requests. Submissions are reviewed by a human; nothing is enabled automatically. Rate limited per email. **Response envelope note**: standalone endpoint — flat `{success, message}`.'
      tags:
      - Platform
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - chainName
              - chainId
              - networkType
              - contactName
              - contactEmail
              properties:
                chainName:
                  type: string
                chainId:
                  type: number
                  description: Numeric chain ID.
                networkType:
                  type: string
                  enum:
                  - evm
                  - non-evm
                rpcUrl:
                  type: string
                  description: Optional public RPC endpoint for the chain.
                contactName:
                  type: string
                contactEmail:
                  type: string
                  format: email
                organizationName:
                  type: string
                message:
                  type: string
      responses:
        '200':
          description: Request recorded for review
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Chain request submitted successfully.
        '400':
          description: Missing or invalid fields
        '405':
          description: Method not allowed (only POST supported)
        '429':
          description: Too many requests from this email — try again tomorrow
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    Meta:
      type: object
      properties:
        version:
          type: string
          example: '1.0'
        timestamp:
          type: string
          format: date-time
    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'
  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.'