On-Chain Attestation

Building this in Claude Code? Install the wallet auth skill and Claude will write correct, signature-verifying integration code on the first try.

smithery skill add douglasborthwick/insumer-skill

View on Smithery · GitHub repo

What this does

Check if a wallet meets conditions without exposing balances. The API returns an ECDSA-signed true/false result with condition hashes and block anchoring, so any party can independently verify the attestation without trusting the caller. Trust profiles, compliance gating, and commerce endpoints all build on this same signed attestation model.

Gate any API on wallet state

Every existing auth system proves who you are. Wallet Auth proves what you own. It is a new category of API access control where access is gated on wallet state — what a wallet holds, what it has staked, what credentials it carries — rather than identity.

Call POST /v1/attest with format: "jwt". InsumerAPI reads the blockchain, evaluates the conditions, and returns an ES256-signed JWT alongside the standard attestation response. Point any standard API gateway at the JWKS endpoint. No blockchain infrastructure needed on the verifying side. No balance exposure. No additional cost — same 1 credit as a standard attestation.

Gateway compatible. Wallet Auth JWTs are standard ES256 JWTs backed by a JWKS endpoint. Compatible with any system that accepts JWKS-backed JWTs:

Kong · Nginx (ngx_http_auth_jwt) · Cloudflare Access · AWS API Gateway · Azure API Management · Traefik · Envoy · any OAuth 2.0 middleware

1. Request a Wallet Auth JWT

Add "format": "jwt" to any attestation request. The response includes a jwt field alongside the standard sig and kid.

curl -X POST https://api.insumermodel.com/v1/attest \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "wallet": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "format": "jwt",
    "conditions": [{
      "type": "token_balance",
      "contractAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "chainId": 1,
      "threshold": 1000,
      "decimals": 6,
      "label": "USDC >= 1000"
    }]
  }'

# Response includes data.jwt alongside data.sig and data.kid
# The jwt field is the Wallet Auth token — an ES256-signed JWT string

2. Verify with insumer-verify

Pass either the full response object or the JWT string directly — insumer-verify v1.3.0 auto-detects the format.

// npm install insumer-verify
import { verifyAttestation } from "insumer-verify";

// Option A: pass the full API response envelope
const response = await res.json();
const result = await verifyAttestation(response, {
  jwksUrl: "https://insumermodel.com/.well-known/jwks.json"
});

// Option B: pass just the JWT string
const result = await verifyAttestation(response.data.jwt, {
  jwksUrl: "https://insumermodel.com/.well-known/jwks.json"
});

console.log(result.valid);   // true
console.log(result.payload); // the verified attestation data

3. Decode JWT claims

The JWT is a standard three-part token. Decode the payload to see the claims structure. Any JWT library in any language can read these claims.

{
  "iss": "https://api.insumermodel.com",       // issuer
  "sub": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",                       // wallet address
  "jti": "ATST-A7C3E1B2D4F56789",                           // attestation ID
  "iat": 1741089600,                              // issued at (unix)
  "exp": 1741091400,                              // expires in 30 min
  "pass": true,                                   // all conditions met
  "conditionHash": ["0x3a7f..."],              // array of all hashes
  "blockNumber": "0x12a3b4f",                    // from first result
  "blockTimestamp": "2026-03-04T12:00:00.000Z", // from first result
  "results": [                                    // per-condition results
    {
      "condition": 0,
      "label": "USDC >= 1000",
      "type": "token_balance",
      "chainId": 1,
      "met": true,
      "evaluatedCondition": { "type": "token_balance", ... },
      "conditionHash": "0x3a7f...",
      "blockNumber": "0x12a3b4f",
      "blockTimestamp": "2026-03-04T12:00:00Z"
    }
  ]
}

4. Portable credential

A Wallet Auth JWT can be forwarded from Service A to Service B and verified without re-querying the chain. The receiving service fetches the JWKS public key once, checks the ES256 signature, reads the claims, and makes an access decision — all without any blockchain infrastructure, any Insumer SDK, or any network call back to InsumerAPI. The JWT is self-contained proof of wallet state at a specific block height, valid for 30 minutes.

JWKS endpoint: https://insumermodel.com/.well-known/jwks.json — also available at GET /v1/jwks. Key ID: insumer-attest-v1.

Related articles