On-Chain Attestation

Every attestation is signed with ECDSA P-256 and also carries a post-quantum signature (ML-DSA-65) as pqSig/pqKid, reported by verifiers as a separate verdict. The algorithm is swappable via JWKS without breaking verifiers. Verify the signature using the insumer-verify library or raw Web Crypto. The same verifier is on PyPI for Python 3.9+ (pip install insumer-verify, add [pq] for the post-quantum check); both packages pass the same 27 published test vectors.

// npm install insumer-verify @noble/post-quantum
// The PQ peer is optional. Without it the post-quantum check reports
// status "unverifiable" rather than verifying it.
import { verifyAttestation } from "insumer-verify";

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

console.log(result.valid); // true

// V1-ONLY WALKTHROUGH. This covers pre-cutover insumer-attest-v1
// responses only. Keys minted today sign with kid insumer-attest-v2
// over a domain-separated, canonical preimage: use insumer-verify for
// those, or follow the verification algorithm in the OpenAPI spec.
const data = (await res.json()).data;
if (data.kid !== "insumer-attest-v1") throw new Error("v2 response: use insumer-verify");

// Fetch the public key from JWKS, selected by the kid on the response
const jwks = await fetch("https://insumermodel.com/.well-known/jwks.json")
  .then(r => r.json());
const key = jwks.keys.find(k => k.kid === data.kid);

// Import the public key
const publicKey = await crypto.subtle.importKey(
  "jwk", key,
  { name: "ECDSA", namedCurve: "P-256" },
  false, ["verify"]
);

// Reconstruct the signed bytes. v1 signs exactly these four fields,
// keys in their original order. Do NOT sort them.
const a = data.attestation;
const payload = new TextEncoder().encode(JSON.stringify(
  { id: a.id, pass: a.pass, results: a.results, attestedAt: a.attestedAt }
));
const sigBytes = Uint8Array.from(
  atob(data.sig), c => c.charCodeAt(0)
);

const valid = await crypto.subtle.verify(
  { name: "ECDSA", hash: "SHA-256" },
  publicKey, sigBytes, payload
);
console.log(valid); // true

Each result includes a conditionHash computed from evaluatedCondition. Recompute it yourself to confirm the attestation matches the condition you requested.

const condition = result.evaluatedCondition;
const sortedKeys = Object.keys(condition).sort();
const canonical = JSON.stringify(condition, sortedKeys);
const hashBuffer = await crypto.subtle.digest(
  "SHA-256",
  new TextEncoder().encode(canonical)
);
const hashHex = "0x" + [...new Uint8Array(hashBuffer)]
  .map(b => b.toString(16).padStart(2, "0"))
  .join("");

console.log(hashHex === result.conditionHash); // true

Add proof: "merkle" to get an EIP-1186 storage proof anchored to a block state root. Verify the balance against that block’s state root, with no call to us. Available on 27 of 31 EVM chains for token_balance, ratio_to_amount, account_code and erc7710_delegation. A condition with contractAddress: "native" carries an account proof instead (subject: "account_balance"): a native balance is a field of the account rather than an entry in a mapping, so the proof is the account’s own branch and its balance field is the value evaluated. There is no storage slot to discover, and it proves a zero balance as readily as a non-zero one. Also on erc7710_delegation conditions, where the proof covers the revocation slot instead of a balance slot, and on account_code conditions, which carry the same account proof as a native balance with subject: "account_code" and codeHash as the proven value: keccak256 of empty code means no code, keccak256 of 0xef0100 followed by the 20-byte target means an EIP-7702 delegation to that target (checkable only with the delegate the verifier supplies), anything else means contract code; an account absent from the state trie may report all zeros, which also means no code.

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

# Response includes a proof object with storageProof, storageHash,
# and blockNumber alongside the standard attestation fields

Merkle proofs cost 2 credits ($0.08) per attestation; whenever no proof is delivered the premium is refunded and the call costs 1, whatever the reason: a read that did not complete, a chain or token that cannot carry a proof, or a condition type that has none. The response includes a proof object containing the raw storageProof array, storageHash, and blockNumber, allowing full trustless verification against the chain state. An account proof (subject: "account_balance", returned for contractAddress: "native") carries accountProof, balance, nonce and codeHash instead, and no storageProof or mappingSlot; on an account_code condition the same record carries subject: "account_code" and its codeHash is the value evaluated. On a delegation condition the object also carries subject: "delegation_revocation" and the contractAddress of the DelegationManager (see Agent conditions for the verification steps).

Add format: "jwt" to receive an ES256-signed JWT alongside the standard response, verifiable by any standard JWT library using the JWKS at /.well-known/jwks.json. A sibling pqJwt (ML-DSA-65) comes beside it; checking the post-quantum signature takes an ML-DSA-65 verifier such as insumer-verify, which binds it to the jwt by the whole claim set. See the full Wallet Auth section below.

Keys are never removed from our JWKS, so an attestation you keep stays checkable. To check it without relying on us at all, save a copy of the JWKS with your stored attestations and verify against that copy. The saved set covers both the ECDSA signature and the post-quantum signature, and nothing is fetched. insumer-verify 1.9.0 and later also ship a snapshot in keys/jwks.json, together with keys/pq-key-binding.json, whose digest is anchored on Base. In Python, pass the saved set as jwks= to verify_attestation; the Python package honours it the same way and fetches nothing.

Use only a copy you saved from our own endpoints: a verifier believes whatever keys you give it. An old attestation still fails the expiry check. Keeping the key keeps the signature checkable; it does not make the attestation valid for access again.

// npm install insumer-verify@^1.9.0 @noble/post-quantum
import { readFileSync } from "node:fs";
import { verifyAttestation } from "insumer-verify";

// Saved when you stored the record, from https://insumermodel.com/.well-known/jwks.json
const savedJwks = JSON.parse(readFileSync("./records/insumer-jwks.json", "utf8"));
const storedResponse = JSON.parse(readFileSync("./records/stored-response.json", "utf8"));

// Nothing is fetched. Evidence mode reports every verdict for an old record.
const result = await verifyAttestation(storedResponse, { jwks: savedJwks, mode: "evidence" });
console.log(result.checks.signature.passed, result.checks.pq.status, result.checks.expiry.passed);
// true verified false

This section describes /v1/attest; the differences on /v1/trust are at the end. A signed result is InsumerAPI's statement that it read chain state, evaluated the conditions in evaluatedCondition, and got the met and pass values shown, at the time in attestedAt. The signature covers id, pass, results and attestedAt together, so neither the conditions nor the outcome can be changed afterwards. What it does not show:

• How far you have to trust the issuer. With a Merkle proof (proof: "merkle", for token balance, ratio-to-amount, account code and delegation revocation conditions on EVM chains, where available), the proven value can be checked against the chain's own state root. The response does not include the block header: fetch it for blockNumber from a node you trust. A balance proof exposes the raw balance to anyone holding the result; an account-code proof carries the account record, native balance included; a revocation proof exposes no balance. Without a proof, the result is as reliable as InsumerAPI, its upstream data sources, and its signing keys.
• Whose wallet was read. The raw format signs no wallet for most condition types. Request format: "jwt" and match sub against the wallet you expect, comparing EVM addresses without regard to letter case. sub names one wallet: if a request covers more than one chain family, send one family per request.
• Who controls the wallet. The wallet comes from the request body. The API does not check that the caller, or anyone, controls it. If your gate needs that, collect a wallet signature yourself.
• Who the person is. The API sees a wallet address and public chain state, and makes no identity statement of its own. An eas_attestation result says only that a third party's attestation exists for the wallet.
• Current state. The result describes state at the anchor it carries and is valid until expiresAt. A wallet can change inside that window. A new call reflects the change.
• The same anchor on every chain. On EVM chains and XRPL the result names the exact block or ledger it describes (blockNumber, or ledgerIndex and ledgerHash), so anyone with the inputs and a node holding that history can repeat the read. A Solana slot is a floor. Bitcoin, Tron, Stellar and Sui anchors mark the chain tip at the time of the result.
• That a label is true. A label is signed, but the caller writes it. Compare evaluatedCondition or conditionHash with the conditions your route requires.
• Spending limits as a verdict. For erc7710_delegation, declaredLimits is a signed decode of what the caller submitted. It is not part of met.
• Fields outside the signature. expiresAt, passCount and failCount are not signed in the raw format. Derive counts from results; expiresAt is bound to attestedAt by the verifier.
• A record held by InsumerAPI. InsumerAPI keeps a record that a check took place, its result and when, tied to the API key or payer, but not the wallet, the conditions or any balance. It cannot reproduce a result later. Keep the response, with a copy of the JWKS, if you will need it.

What false means. A failed read is refused with a 503 and never signed (on /v1/trust/batch, as an unsigned error entry for that wallet). met: false means the evaluation completed and the condition was not met. Usually the chain answered no. On EVM chains that includes a token or view contract that reverts or has no code. On XRPL a trust line with a freeze set on it, or whose issuer has frozen everything it issued, is false whatever the balance. For erc7710_delegation it can also mean the delegation failed a check on its own contents, or carries a caveat the API does not recognise. For account_code it means the address is in a code state other than expect, or, with delegate, that its EIP-7702 designator points elsewhere. A kid your verifier does not recognise leaves the result unverified: treat it as no result, not as a signed false.

On /v1/trust. The signature covers the whole trust object, including wallet (the EVM wallet), summary and expiresAt, and the time is profiledAt. Other-chain wallets are not in the signed object, and there is no JWT format. A check marked evaluated: false was not run: its wallet was not supplied.