State Attestation Specification

Abstract

This document specifies the attestation format, signing scheme, and verification algorithm used by InsumerAPI, the on-chain attestation authority for AI agents, apps, and commerce.

An InsumerAPI attestation is a cryptographically signed boolean assertion ("wallet X satisfies condition Y at block Z") that any downstream system can independently verify without re-querying a blockchain node or learning the underlying state values. Every attestation carries an ECDSA P-256 signature. Since 1 September 2026 it also carries, whenever post-quantum signing is configured, an additive ML-DSA-65 post-quantum signature over a post-quantum domain tag followed by the same preimage (Section 12, Check 6).

This specification defines:

• The attestation format: the structure of signed responses
• The condition types: what can be attested
• The signing scheme: how responses are signed (ECDSA P-256)
• The verification algorithm: how integrators confirm authenticity and integrity
• The Merkle proof extension: optional trustless verification against block headers

This document is intended for integrators and verifiers who consume InsumerAPI responses. It defines everything needed to parse, verify, and trust an attestation.

1. Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

2. Overview

                                   ┌──────────────┐
                                   │  Blockchain   │
                                   │    State      │
                                   └──────┬───────┘
                                          │
                                          │
┌──────────┐    conditions + wallet    ┌──┴───────────┐    signed attestation    ┌──────────┐
│  Caller  │ ────────────────────────▶ │  InsumerAPI  │ ──────────────────────▶ │ Verifier │
└──────────┘                           └──────────────┘                         └──────────┘
                                                                                     │
                                                                              fetch JWKS
                                                                                     │
                                                                              ┌──────┴───────┐
                                                                              │  JWKS        │
                                                                              │  Endpoint    │
                                                                              └──────────────┘

1. A caller submits a wallet address and one or more conditions to InsumerAPI (POST /v1/attest).
2. InsumerAPI reads chain state at a recent block, evaluates each condition, and returns a signed attestation.
3. The verifier (which may be the caller or a downstream system) validates the attestation using InsumerAPI's public key, condition hashes, and block anchoring, without contacting the API again.

3. Signing

3.1 Algorithm

All InsumerAPI responses are signed using ECDSA with the P-256 curve (secp256r1) and SHA-256 (JOSE algorithm identifier ES256).

3.2 Signature format

The sig field contains a base64-encoded (standard alphabet) P1363-format signature (two 32-byte integers r || s, total 64 bytes). The encoded signature is 88 characters.

P1363 is the fixed-length format (not DER). Verifiers MUST use P1363 decoding.

3.3 Signed payload

For an attestation, the signed payload is the JSON serialization of the following fields in this order:

{"id":"...","pass":true,"results":[...],"attestedAt":"..."}

The field order is fixed: id, pass, results, attestedAt. This is the exact output of JSON.stringify() on the attestation object as constructed by InsumerAPI.

Every other field of the attestation object is outside the signed payload: passCount, failCount, expiresAt, and any field not listed above. Anyone holding a response can change them without affecting the signature. expiresAt is bound to the signed attestedAt by Check 4, and passCount and failCount are recounted from the signed results by Check 2a (Section 12). A relying party treats no other unsigned field as part of the attestation.

For a trust profile, the signed payload is the JSON serialization of the trust object with fields in this order: id, wallet, conditionSetVersion, dimensions, summary, profiledAt, expiresAt.

The digest is SHA-256(json_bytes), and the signature is computed over this 32-byte digest.

3.3.1 v2 signed payload (domain-separated)

Keys created on or after the v2 rollout sign a domain-separated preimage. For these keys the signature is computed over:

attestation:   "insumer.attestation.v2" + "\n" + canonical_json({"v":2,"id":"...","pass":true,"results":[...],"attestedAt":"..."})
trust profile: "insumer.trust.v2"       + "\n" + canonical_json({"id":"...","wallet":"...","conditionSetVersion":"2026-10-08","dimensions":{...},"summary":{...},"profiledAt":"...","expiresAt":"..."})

where the attestation preimage carries a leading "v":2 member and the trust preimage is the entire trust object exactly as returned (the same seven fields as Section 3.3, expiresAt included, no "v" member), and canonical_json is the JCS / RFC 8785 canonical form (recursively sorted keys, Section 8) rather than insertion order. The domain tag binds each signature to its message type, so an attestation signature cannot be reinterpreted under another context. Under v2 the threshold of a token_balance or ratio_to_amount condition, and the ratio quantities, are canonical decimal strings with no decimals field, so the signed bytes are exact and reproducible by any verifier in any language. nft_ownership conditions and the curated trust checks keep threshold as the JSON number 0 (Sections 7 and 14.1).

v1 keys continue to sign the insertion-order payload in Section 3.3 with no domain tag (see Section 14, Versioning). The kid on the response selects both the key and the scheme.

3.4 Key identification

Every signed response includes a kid (Key ID) string. Verifiers use this value to select the correct public key from the JWKS endpoint.

4. Key Distribution

4.1 JWKS endpoints

InsumerAPI publishes its signing keys as a JSON Web Key Set (RFC 7517) at two locations:

• API endpoint: GET https://api.insumermodel.com/v1/jwks (24-hour cache)
• Static fallback: https://insumermodel.com/.well-known/jwks.json (also served at https://api.insumermodel.com/.well-known/jwks.json)

The JWKS document holds five entries over two keys. The first three are the ECDSA P-256 key under three kid values; the last two are RFC 9964 AKP entries for the ML-DSA-65 post-quantum key (Section 12, Check 6). The EC entries carry:

The two AKP entries, appended after the EC entries so that a verifier that falls back to the first key still meets a classical one, carry:

4.2 Key rotation

Keys are never removed from the JWKS document. If a key rotation occurs, the previous key stays in the JWKS document permanently under its original kid, so the signature on an attestation made with it stays checkable for as long as anyone holds the attestation as a record. This does not extend the attestation's validity: once its expiresAt has passed, a verifier applying Check 4 rejects it as expired. Verifiers SHOULD select the key matching the response's kid rather than hardcoding a key. Relying parties that keep attestations as records SHOULD also keep a copy of the JWKS document and of /.well-known/pq-key-binding.json with them, so the records can be verified without depending on these endpoints.

5. Attestation Object

An attestation is the core output of the protocol. It asserts whether a wallet satisfies a set of conditions at a specific point in time.

5.1 Top-level structure

{
  "id": "ATST-A7C3E1B2D4F56789",
  "pass": true,
  "results": [ ... ],
  "passCount": 2,
  "failCount": 0,
  "attestedAt": "2026-02-26T12:34:57.000Z",
  "expiresAt": "2026-02-26T13:04:57.000Z"
}

5.2 Result object

Each entry in the results array describes the evaluation of one condition:

5.3 Signed response envelope

The complete response pairs the attestation object with its signature:

{
  "ok": true,
  "data": {
    "attestation": { ... },
    "sig": "<88-char base64, P1363 r||s>",
    "kid": "insumer-attest-v2",
    "pqSig": "<base64 ML-DSA-65 signature>",
    "pqKid": "insumer-attest-pq1"
  },
  "meta": {
    "version": "1.0",
    "timestamp": "2026-02-26T12:34:57.000Z"
  }
}

The sig and kid fields MUST be siblings of the object they sign (not nested within it), and so are the post-quantum signature fields pqSig and pqKid (Section 12, Check 6). The meta object is NOT part of the signed payload.

5.4 JWT bearer token format

Callers MAY request the attestation as a standard JWT by including "format": "jwt" in the request body. When present, the response’s data object carries an additional jwt member beside attestation, sig and kid, and a pqJwt beside pqSig (Section 12, Check 6).

The JWT is signed with ES256 (ECDSA P-256 + SHA-256) using the same key identified by kid. The header and claims are:

Header:

Claims:

The JWT is verifiable by any standard JWT library (Kong, Nginx, Cloudflare Access, AWS API Gateway) using the JWKS endpoint at GET /v1/jwks or the static /.well-known/jwks.json.

6. Condition Types

A condition is a predicate evaluated against on-chain state. InsumerAPI supports ten condition types. The four core types are documented first. evm_view_call (an arbitrary bool-returning view function, named by a canonical selector of the form functionName(address), on EVM chains) is an additive type. ratio_to_amount and ratio_to_supply (dimensionless ratio conditions, where the threshold is derived from a multiple of a reference amount or a share of total supply) are additive v2 types; see the signature-scheme section for their canonical decimal-string quantity encoding. erc8004_agent and erc7710_delegation (agent conditions: ERC-8004 agent registration and ERC-7710 delegation validity, Base only at launch) are additive types, generally available on any API key and also reachable with no key via x402 pay-per-call. Their evaluatedCondition layouts are given in Section 7. account_code (Section 6.8) asks what code sits at the wallet address itself: a plain key, an EIP-7702 delegation designator, or contract code; its layout is given in Section 7.3.

6.1 token_balance

Asserts whether a wallet's balance of a token, or of the chain's native coin, meets a threshold.

Semantics: met is true when the wallet's balance (adjusted for decimals) is greater than or equal to threshold.

Comparison (operator field): "gte"

6.2 nft_ownership

Asserts whether a wallet holds at least one NFT from a collection.

Semantics: met is true when the wallet holds one or more tokens from the collection.

Chains: Tron, Stellar and Sui support token_balance only, and Bitcoin supports token_balance with "native" only. Any other combination is rejected with a 400.

Comparison (operator field): "gt". Evaluated threshold: 0

6.3 eas_attestation

Asserts whether a wallet has received a valid Ethereum Attestation Service attestation matching a schema.

Semantics: met is true when a valid, non-revoked attestation exists for the wallet matching the specified schema and attester constraints. The schema named in the signed condition is checked against the attestation that is found, so the choice of indexer cannot change what the signature states. An attestation's expiry is judged at the anchored block's timestamp.

Comparison (operator field): "valid" (standard) or "decoder" (template-specific evaluation logic)

6.4 farcaster_id

Asserts whether a wallet is registered on Farcaster.

Semantics: met is true when the wallet has a registered Farcaster ID. The condition is always read on Optimism and signed with chainId 10; a chainId in the request is not used.

Comparison (operator field): "registered"

6.5 evm_view_call

Asserts whether an arbitrary contract's own view function answers true for the wallet. This is the general-purpose escape hatch: any predicate a contract already exposes (hasAccess(address), isMember(address), an allowlist, a custom policy) becomes attestable without a dedicated condition type.

Semantics: InsumerAPI derives the 4-byte function selector as the first 4 bytes of keccak256 of the canonical signature, forms calldata as that selector followed by the wallet address left-padded to 32 bytes, and calls the view function on contractAddress at the anchored block. met is true when the call returns a nonzero 256-bit word (the ABI encoding of true). A revert or an empty return is an on-chain fact and produces a signed false; a transport failure refuses to sign rather than guessing.

Comparison (operator field): "view_call_true"

Reproducing the verdict: The evaluatedCondition carries the canonical selector string, so a verifier can recompute the 4-byte selector, repeat the same call at the anchored blockNumber, and compare. No information beyond the signed result is needed.

Scope of the claim: The attestation states what the named contract returned at the anchored block, and nothing more. The contract's own correctness, semantics, and upgradeability are outside the signature's scope: the signed bytes commit to the contract, the selector, the chain, and the block. Merkle storage proofs are not available for this type, since the predicate is the contract's computation rather than a single storage slot.

6.6 Ratio conditions: ratio_to_amount and ratio_to_supply

Two dimensionless balance rules share the token_balance anchor and hashing rules. ratio_to_amount is met when the balance is at least multiple times amount; the derived threshold travels in evaluatedCondition.threshold with operator "gte". Under v2 it is multiple times amount rounded up to the token's smallest unit (at a fixed scale of 18 when the token states no decimals), so a verifier recomputes it from the two inputs and the token's decimals and re-reads the balance at the anchored block; under v1 it is the plain product of the two numbers. ratio_to_supply is met when balance divided by the token's totalSupply() at the anchored block is at least minFraction, a value in the open-closed interval (0, 1]; its evaluatedCondition carries minFraction with operator "gte_fraction". The raw supply read is returned as totalSupply (absent when totalSupply() reverts or the address holds no code, which is a signed false), a sibling of evaluatedCondition on the result: inside the signed payload, outside conditionHash, so a verifier re-reads balance and supply at the pinned block and re-derives the boolean exactly. Under v1 the quantities are JSON numbers and the result also carries the computed fraction; under v2 they are canonical decimal strings and no fraction is emitted (Section 14.1). Native assets have no totalSupply() and are rejected for ratio_to_supply. Both ratio types are available on EVM chains only. Under v2, an amount with more decimal places than the token's own decimals, or a multiple with more than 18, is rejected with a 400.

6.7 Input limits

A request outside these limits is rejected with a 400 and nothing is read or signed:

• 1 to 10 conditions per request, of which at most 3 are erc7710_delegation.
• A delegation object of at most 16 KB, with at most 16 caveats, at most 2 KB of terms per caveat and a signature of at most 4 KB. Only the root authority is accepted; delegation chains are not.
• An agentId of at most 78 decimal digits.
• On v2 keys, a decimal string (threshold, multiple, amount, minFraction) of at most 400 characters, in the form given in Section 8.3.
• A threshold, multiple or amount greater than zero.

6.8 account_code

Asserts the code state of the wallet address itself at the anchored block. Three states exist on a chain and they are exclusive: no code (a plain key account), the EIP-7702 delegation designator (a key that has delegated execution to a contract), or any other code (a smart-contract wallet, a protocol, a token). The condition names one state and the attestation says whether the address is in it.

Semantics: The code at the wallet address is read at the anchored block and classified into one of the three states. met is true when that state is the one named by expect, and, when delegate is supplied, when the designator's target is that address. A read that does not complete refuses to sign; it is never reported as met: false.

Comparison (operator field): "code_state"

Scope of the claim: The result is the boolean. The code itself and the delegation target are never returned, in any format or mode; a caller who cares which contract names it in delegate and still receives only yes or no. Which contract stands behind contract code is outside the signed statement. With proof: "merkle" the result carries an account proof whose codeHash is the proven value (Section 10.2). A trust profile reports the same two facts without a target in its account dimension (Section 11.3).

7. Evaluated Conditions

Every result includes an evaluatedCondition object that captures the exact predicate that was applied. This is a statement of what was checked, not a repeat of the caller's input.

The evaluated condition MUST include:

The evaluated condition serves two purposes:

1. Transparency: The verifier can see exactly what was checked.
2. Tamper-evidence: The condition hash (Section 8) binds the evaluated condition to the signed attestation.

7.1 erc8004_agent layout

The evaluatedCondition for an erc8004_agent condition carries exactly:

{
  "type": "erc8004_agent",
  "chainId": 8453,
  "registry": "0x8004a169fb4a3325136eb29fa0ceb6d2e539a432",
  "agentId": "123",
  "wallet": "0x<attested wallet>",
  "operator": "owner_or_bound_wallet"
}

The registry and wallet are signed in lower case. met is true iff the attested wallet either owns the agent NFT (ownerOf) or is the registry's on-chain signature-verified agentWallet binding (getAgentWallet). The result object additionally carries agentExists (boolean) and matchedVia ("owner" | "agent_wallet" | "none") inside the signed results array, outside conditionHash. ERC-8004 registration is permissionless NFT minting: the signed statement is exactly “registered in registry R at agentId N, owned by / bound to this wallet”. It implies no vetting, no reputation, no endorsement. The registry clears the agentWallet binding automatically when the agent NFT transfers, so a block-anchored verdict reflects binding truth at that block.

7.2 erc7710_delegation layout

The evaluatedCondition for an erc7710_delegation condition carries exactly:

{
  "type": "erc7710_delegation",
  "chainId": 8453,
  "delegationManager": "0xdb9b1e94b5b69df7e401ddbede43491141047db3",
  "domainVersion": "1",
  "frameworkVersion": "1.3.0",
  "delegationHash": "0x<hash>",
  "delegator": "0x<principal>",
  "delegate": "0x<agent wallet>",
  "wallet": "0x<attested wallet>",
  "authority": "root",
  "expectedDelegator": "0x<principal>",
  "signatureType": "eoa",
  "caveatCoverage": "full",
  "caveatCount": "1",
  "unevaluatedCaveats": "0",
  "operator": "authorized_by_principal"
}

Every address in this layout is signed in lower case. signatureType is one of "eoa", "erc1271", or "none". "eoa" means an EOA principal signed the delegation; "erc1271" means a smart-contract principal asserts the delegation is valid. That is a different claim, and both appear distinctly in the signed bytes. caveatCoverage is "full" or "partial". caveatCount and unevaluatedCaveats are decimal strings inside the signed bytes, never JSON numbers. The result object additionally carries declaredLimits (decoded caveat limits with decimal-string amounts in base units), and on failure unrecognizedEnforcers and failReason (delegate_mismatch, principal_mismatch, invalid_signature, delegator_not_deployed, revoked, unknown_caveat_enforcer, outside_time_window). A recognized enforcer whose terms cannot be decoded is treated as unrecognized: it is listed in unrecognizedEnforcers and the verdict fails with unknown_caveat_enforcer. delegator_not_deployed is reported when the principal address holds no contract code at the anchored block, which is the state a smart-contract wallet is in until its first transaction. It is distinct from invalid_signature because no signature was evaluated: there was no principal on chain to evaluate one against. The verdict is still a signed false, since redemption calls into the delegator account and an undeployed principal cannot exercise the delegation. Declared limits are reported, not simulated: on-chain redemption enforces them, and the attestation states what the principal signed. Attestations containing a delegation condition expire in 5 minutes rather than the standard 30: revocation is one transaction away, so the verdict window stays tight, and the verdict states “not revoked as of block N” (blockNumber is in the signed result). That clause is itself provable: a delegation condition requested with proof: "merkle" returns an EIP-1186 storage proof of the revocation slot, specified in Section 10.7.

7.2.1 The verdict and the declared limits

met is the verdict, and it is exactly this boolean: the attested wallet is the delegate, the declared delegator matches the required expectedDelegator, the EIP-712 signature verifies, the delegation is unrevoked as of the anchored block, every caveat uses a recognized enforcer, and any time-window caveat is satisfied at the anchored block's timestamp (strictly after timestampAfter and strictly before timestampBefore, where 0 means no bound on that side). declaredLimits is not an input to that boolean. It is a signed decode of the caveat terms the caller itself submitted, and it sits as a sibling of evaluatedCondition, inside the signed results payload but outside conditionHash. A verifier reading a delegation attestation should treat met as the statement and declaredLimits as signed context riding alongside it. That context rides on affirmative and negative verdicts alike: the decode is computed once the signature and revocation checks pass, so a delegation failing on unknown_caveat_enforcer or outside_time_window still carries the decode of its recognized caveats. For a time-window failure, the decoded timestamp caveat is the evidence for the failure. Failures at or before the signature and revocation checks (delegate_mismatch, principal_mismatch, invalid_signature, delegator_not_deployed, revoked) carry no decode.

Each entry carries the exact hex bytes it was decoded from, so the decode is independently checkable:

{
  "kind": "erc20_transfer_amount",
  "enforcer": "0xf100b0819427117ecf76ed94b358b1a5b5c6d2fc",
  "terms": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913000000000000000000000000000000000000000000000000000000003b9aca00",
  "token": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  "maxAmount": "1000000000"
}

kind is one of timestamp (fields timestampAfter, timestampBefore), erc20_transfer_amount (token, maxAmount), native_transfer_amount (maxAmount), allowed_targets (targets), or limited_calls (maxCalls). All numeric values are decimal strings in base units. Because the caller supplied terms in its own request, verification requires no external lookup: re-run the enforcer contract's public getTermsInfo byte layout against terms and compare it to the decoded values, then recompute delegationHash (the EIP-712 struct hash inside evaluatedCondition, which commits to every caveat's enforcer and terms) from the delegation object held locally and confirm it matches. The hash pins which caveats were evaluated; the byte layout pins what each one says.

7.2.2 Omitting the declared limits

A delegation attestation in JWT form is portable, so by default the principal's declared limits travel to anyone the attestation is forwarded to. That is usually desirable, since a relying party needs the limits to act on them, but not always. The top-level request modifier declaredLimits (a sibling of proof and format) takes "include" (the default, also the behavior when the field is absent) or "omit". Under "omit" the decoded limits are not included and the result carries declaredLimitsOmitted: true in their place. The caller loses nothing: it submitted the caveats and already holds them.

The modifier changes only what rides alongside the verdict. met, delegationHash, and conditionHash are byte-identical whether or not the limits are omitted, since declaredLimits was never inside evaluatedCondition to begin with. A forwarded attestation therefore still commits to exactly which delegation was checked, and a holder can verify a limit shown to them out-of-band without learning one from the attestation itself.

7.3 account_code layout

The evaluatedCondition for an account_code condition carries exactly:

{
  "type": "account_code",
  "chainId": 8453,
  "expect": "eip7702",
  "operator": "code_state"
}

When the request supplied delegate, the object also carries "delegate": "0x<address>", signed in lower case (Section 8.3). Nothing read from the chain is echoed: the code and the designator's target never appear. The condition hash (Section 8) is computed over this object under both signing schemes; the object above hashes to 0x6c5752bfbfcfd6ba36c9cda6c74df567f0e0414da6b7a3176061ba734aeadc46. A trust profile's account rows carry this same layout with expect "contract" or "eip7702" (Section 11.3), so a row's conditionHash equals the hash of the equivalent attest condition.

8. Condition Hashes

Each result MUST include a conditionHash field computed as:

conditionHash = "0x" + hex(SHA-256(canonical_json(evaluatedCondition)))

Where canonical_json produces a JSON string with:

• Sorted keys (lexicographic, recursive)
• No whitespace
• Standard JSON separators (, and :)

8.1 Verification

A verifier MUST recompute the condition hash (Section 12, Check 2) from the evaluatedCondition object and compare it to the claimed conditionHash. If they differ, the result MUST be rejected as tampered.

Because the conditionHash is embedded in the results array, which is part of the signed payload, a valid signature over the attestation transitively guarantees the integrity of every evaluated condition.

8.2 Example

A token_balance condition on Ethereum mainnet USDC ("holds at least 1000 USDC"), as a v2 attestation carries it. Its canonical form is the exact byte string the hash is computed over:

{"chainId":1,"contractAddress":"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48","operator":"gte","threshold":"1000","type":"token_balance"}

The condition hash is 0x + the hex-encoded SHA-256 of those bytes:

0x630c213d362cd4e617261c2475f7b8ad70096ac911db804392305d6cbf70f094

Both values are reproducible: canonicalize the object, take the SHA-256, and the digest above follows. The threshold is a decimal string in display units, exactly as the condition stated it: "1000" is 1000 USDC. The signed bytes carry no separate scale, because the scale is never an input: it is always the token's own decimals, read from the chain at the anchored block (Section 6.1).

The ratio quantities (multiple, amount, minFraction) follow the same rule as threshold: canonical decimal strings under v2, JSON numbers with decimals under v1.

8.3 How identifiers are spelled

A relying party that pins a conditionHash pins exact bytes, so it needs to know how each identifier is written into the signed condition.

• A contractAddress is signed as sent. It keeps the letter case the request used (an EVM address in checksum case and the same address in lower case produce different hashes), and "native" keeps the case it was sent in. The one rewrite is an xdc prefix on a token_balance, nft_ownership or ratio condition, signed as 0x; an evm_view_call address must already start with 0x.
• A Sui coin type, a Stellar assetCode, an EAS schemaId and attester, and an evm_view_call selector are signed as sent.
• Under v2 a decimal string (threshold, multiple, amount, minFraction) must be digits with an optional fractional part: no sign, no exponent, no leading point. It is signed in canonical form, with leading zeros and trailing fractional zeros removed and no point on a whole number, so "1000.0" is signed as "1000" and "00.50" as "0.5". A JSON number in these fields is rejected with a 400 on a v2 key.
• An XRPL currency is signed in normalized form. A three-character code is kept exactly as given: currency codes are case-sensitive. A 40-character hex code is upper-cased, and when it encodes a three-character code made of letters, digits or the symbols ?!@#$%^&*<>(){}[]| it is signed as that code. Any other name is signed as its 40-character upper-case hex encoding.
• The addresses that the API supplies or checks against a fixed list (the ERC-8004 registry, the delegationManager, and the addresses inside an erc7710_delegation condition) are signed in lower case (Sections 7.1, 7.2).

9. Block Anchoring

9.1 Purpose

Block anchoring binds an attestation result to a specific point in blockchain history. Without it, a verifier cannot distinguish a result from 10 seconds ago from one from 10 minutes ago.

9.2 Fields

9.3 Requirements

• blockNumber and blockTimestamp are included for every EVM chain.
• Non-EVM chains use their own anchor fields: slot for Solana, ledgerIndex with ledgerHash for XRPL and Stellar, blockHeight with blockHash for Bitcoin and Tron, and checkpointSequence for Sui.
• On every chain family, a result is signed only from a complete, anchored observation. If the anchor cannot be captured, or the chain state cannot be read, or it can be read only in part (a page of a paginated read is missing, or the answer does not cover the kind of asset the condition names), the API returns 503 and signs nothing. A failed read is never reported as met: false.
• A refusal is HTTP 503 with error.code "rpc_failure" and error.failedConditions, a list of {source, chainId, message} naming the kind of read that did not complete and the chain (an integer for EVM chains, a chain name otherwise, or null). No signature is returned.
• What the chain itself answers is an observation, and is signed: a call that reverts, a call to an address holding no code, and an account that does not exist at an anchored ledger are each a true met: false that anyone replaying the read at that anchor obtains again.
• The blockNumber and blockTimestamp MUST correspond to the same block.
• The block MUST be the block at which state was read, not a later or earlier block. Every read behind an EVM result, the supporting ones included (a token's decimals(), an attestation lookup, an identity registry), is made at that block, and a time-dependent test such as an attestation's expiry is judged at that block's own timestamp.
• The non-EVM anchors differ in kind, and a verifier SHOULD read them accordingly. An XRPL ledgerIndex with its ledgerHash names the one validated ledger every read behind the result was pinned to. A Solana slot is a floor: the state was observed at that slot or later, and across a paged read it is the lowest slot any page reported. The Bitcoin and Tron blockHeight with blockHash, the Stellar ledgerIndex with ledgerHash and the Sui checkpointSequence are tip markers captured alongside the read: they bind the observation to a recent point in chain history and do not name the exact state that was read.

9.4 Freshness verification

Verifiers MAY enforce a maximum age by comparing blockTimestamp to their local clock. A verifier SHOULD allow for reasonable clock skew (RECOMMENDED: 60 seconds) and block propagation delay.

For a live access decision, where the result decides something now (admitting a request, pricing a purchase, settling a payment), a verifier that does not choose its own maximum age SHOULD use a default of 120 seconds, before the clock-skew allowance above. The anchor can sit a few blocks behind the tip (Section 9.5, about 72 seconds on Ethereum mainnet in proof mode), so a smaller default would refuse valid results on slower chains; a larger one lets the yes and the action it authorizes drift apart. A relying party whose action is costly to reverse MAY set a tighter value. The maximum age applies to the decision, not to the artifact: a result kept as evidence of what was true at its anchor (Section 13.6) has no maximum age, and only Check 4 bounds its issuance window.

If blockTimestamp is absent, the verifier SHOULD fall back to attestedAt for freshness checks, with the understanding that this provides weaker guarantees.

9.5 Anchor selection

The anchor is chosen by the API, not by the caller. Standard requests anchor at the chain tip. Requests with proof: "merkle", on /v1/attest, /v1/trust and /v1/trust/batch alike, anchor a few blocks behind the tip: a Merkle proof requires the state trie for the anchored block, and nodes commonly serve a block before its state is retrievable, so anchoring at the tip would intermittently make proofs unavailable. The lag is currently six blocks (about 12 seconds on Base, about 72 seconds on Ethereum mainnet) and applies to the whole request, so the verdict and the proof always describe the same block, as required by Section 9.3.

Verifiers MUST NOT assume the anchor equals the chain tip at the time of the response, and MUST NOT treat a small gap between the anchor and the tip as evidence of a stale or replayed attestation. Freshness is evaluated as specified in Section 9.4, against blockTimestamp and expiresAt, not against the distance from the tip.

10. Merkle Storage Proofs

10.1 Overview

When requested via proof: "merkle", InsumerAPI includes a Merkle storage proof alongside the boolean result. On /v1/attest the request may also be made with the query parameter proof=merkle. A proof lets a verifier confirm the on-chain value against a block header without relying on InsumerAPI’s reading of the chain. The response does not include the header: the verifier obtains it for blockNumber from a source it trusts.

10.2 Availability

Four kinds of proof exist, and each proves a different part of the state.

A token_balance or ratio_to_amount condition on an ERC-20 contract produces a balance proof (both prove the same balance slot) when ALL of the following are true:

1. The chain supports Merkle storage proofs (currently 27 of 31 EVM chains).
2. The token's balance slot can be located. A non-zero balance locates it, and once it is located a zero balance is proven as well. A zero balance at a token whose slot has not yet been located returns available: false.

A token_balance or ratio_to_amount condition whose contractAddress is "native" produces an account proof on the same chains. A native balance is a field of the account, not an entry in a contract's storage, so the proof is the account's own branch of the state trie. It carries subject: "account_balance" with the account's balance, nonce and codeHash, and no storageProof, mappingSlot or storageKey. The balance field is the value the condition was evaluated against, and the proof is served only when the two agree. An account proof covers a zero balance as readily as a non-zero one.

An account_code condition produces an account proof of the same shape on the same chains, carrying subject: "account_code". Its codeHash is the value the condition was evaluated against, and the proof is served only when the two agree: keccak256 of empty code (0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470) means no code; keccak256 of 0xef0100 followed by the 20-byte target means an EIP-7702 delegation to that target, which a verifier can check only with the delegate it supplies; anything else means contract code. An account absent from the state trie may report every field as zero, which also means no code. The record carries the account's balance and nonce as well, as every account proof does.

An erc7710_delegation condition produces a revocation proof (Section 10.7) when the DelegationManager the delegation was signed against is a deployment whose storage layout has been verified on-chain. Currently that is the v1.3.0 manager on Base, 0xdb9B1e94B5b69Df7e401DDbedE43491141047dB3 (signed in lower case, Section 8.3). Other recognized managers return available: false with a reason naming the unverified layout.

No other condition type produces a proof. nft_ownership and erc8004_agent in particular do not, and no proof exists on a non-EVM chain.

When unavailable, the response includes a proof object with available: false and a reason string.

10.3 Proof object

{
  "available": true,
  "type": "merkle",
  "blockNumber": "0x12a05f200",
  "mappingSlot": 3,
  "storageKey": "0x...",
  "accountProof": ["0x...", "0x...", ...],
  "storageProof": [
    {
      "key": "0x...",
      "value": "0x3B9ACA00",
      "proof": ["0x...", "0x...", ...]
    }
  ],
  "storageHash": "0x..."
}

InsumerAPI may include additional fields in the proof object. Verifiers SHOULD ignore fields they do not recognize.

10.4 Verification

Merkle proofs can be verified against any Ethereum block header source (archive node, light client, block explorer). For custom implementations, the proof structure follows standard Merkle-Patricia trie verification: verify accountProof against the block's state root, then verify storageProof against the account's storage root. For an account proof only the first step applies: the account branch itself yields the evaluated field: the balance, or on an account_code proof the codeHash.

10.5 Privacy note

Standard attestations (without proof) return only a boolean and never reveal balances, with one exception: ratio_to_supply on v1 keys (Section 13.3). Merkle proofs do reveal the raw on-chain balance. Callers MUST be aware that requesting proofs trades privacy for trustlessness.

10.6 Unavailable proof

When the proof cannot be generated:

{
  "type": "merkle",
  "available": false,
  "reason": "Merkle proofs not available for this chain"
}

An unavailable proof may also carry transient (true when a read did not complete and the same request may succeed later; false when the outcome is settled) and unsupportedChain: true on a chain that serves no proofs. Some variants omit type.

The proof object, available or not and reason included, sits inside the signed results array (and the results claim of a JWT). It is covered by the signature but not by conditionHash, so a verifier MUST NOT remove or rewrite any of its fields before checking the signature. The text of reason is informational and may change between releases.

10.7 Delegation revocation proofs

An erc7710_delegation verdict (Section 7.2) has three parts, and they are not equally checkable by default. The EIP-712 signature verification and the caveat decode are reproducible by the caller without assistance, because the caller holds the delegation object and submitted the raw caveat terms (Section 7.2.1). The remaining clause, “not revoked as of block N”, was an assertion by the API that a verifier could not independently confirm. A revocation proof closes that gap, making the verdict checkable rather than partly trusted.

When a delegation condition is requested with proof: "merkle" and the manager's layout has been verified (Section 10.2), the proof object proves the value of disabledDelegations[delegationHash] in the DelegationManager's storage against the anchored block's state root.

{
  "available": true,
  "type": "merkle",
  "subject": "delegation_revocation",
  "blockNumber": "0x12a05f200",
  "contractAddress": "0xdb9b1e94b5b69df7e401ddbede43491141047db3",
  "mappingSlot": 4,
  "storageKey": "0x...",
  "accountProof": ["0x...", "0x...", ...],
  "storageProof": [
    {
      "key": "0x...",
      "value": "0x0",
      "proof": ["0x...", "0x...", ...]
    }
  ],
  "storageHash": "0x..."
}

A verifier checks a revocation proof as follows:

1. Recompute storageKey = keccak256(abi.encode(delegationHash, mappingSlot)), taking delegationHash from the signed evaluatedCondition, and confirm it equals the returned storageKey. This step is REQUIRED: it is what binds the proof to this specific delegation. Without it, a proof of an unrelated storage slot would still verify correctly against the block header.
2. Verify accountProof against the state root of the block header for blockNumber, then verify storageProof against the account's storage root, as in Section 10.4.
3. Interpret the proven value: 1 means the delegation was revoked, 0 means it was not. Note that this proves absence as firmly as presence: a proven 0 is positive proof that no revocation exists at that slot, not merely a report that none was found.

Proofs are produced only for DelegationManager deployments whose storage layout has been verified on-chain, and the restriction is deliberate rather than provisional. An inferred slot number would yield a well-formed proof of the wrong storage location, and that proof would verify against the block header exactly as a correct one does. A verifier would have no way to detect the mistake. That outcome is worse than returning no proof, so managers without a verified layout return available: false and the boolean verdict is computed and signed as normal.

Unlike a balance proof (Section 10.5), a revocation proof reveals no balance and no wallet holdings: the proven slot is a single revocation flag keyed by a delegation hash the caller already holds.

11. Trust Profiles

A trust profile is a higher-level construct built on top of attestations. It evaluates a curated set of conditions across multiple dimensions to produce a fact-based wallet profile.

11.1 Structure

{
  "id": "TRST-74167",
  "wallet": "0x1601...347E",
  "conditionSetVersion": "2026-10-08",
  "dimensions": {
    "stablecoins":             { "checks": [...], "passCount": 6, "failCount": 46, "notEvaluatedCount": 0, "total": 52 },
    "governance":              { "checks": [...], "passCount": 0, "failCount": 8, "notEvaluatedCount": 0, "total": 8 },
    "nfts":                    { "checks": [...], "passCount": 0, "failCount": 3, "notEvaluatedCount": 0, "total": 3 },
    "staking":                 { "checks": [...], "passCount": 0, "failCount": 5, "notEvaluatedCount": 0, "total": 5 },
    "institutional_stablecoins": { "checks": [...], "passCount": 0, "failCount": 4, "notEvaluatedCount": 4, "total": 8 },
    "tokenized_treasuries":    { "checks": [...], "passCount": 0, "failCount": 15, "notEvaluatedCount": 1, "total": 16 },
    "stablecoin_deposits":     { "checks": [...], "passCount": 5, "failCount": 34, "notEvaluatedCount": 0, "total": 39 },
    "wrapped_bitcoin":         { "checks": [...], "passCount": 0, "failCount": 12, "notEvaluatedCount": 0, "total": 12 },
    "names":                   { "checks": [...], "passCount": 0, "failCount": 2, "notEvaluatedCount": 0, "total": 2 },
    "account":                 { "checks": [...], "passCount": 5, "failCount": 5, "notEvaluatedCount": 0, "total": 10 },
    "solana":                  { "checks": [...], "passCount": 1, "failCount": 13, "notEvaluatedCount": 0, "total": 14 }
  },
  "summary": {
    "totalChecks": 169,
    "totalPassed": 17,
    "totalFailed": 147,
    "totalNotEvaluated": 5,
    "dimensionsWithActivity": 4,
    "dimensionsChecked": 11
  },
  "profiledAt": "2026-10-07T21:53:03.720Z",
  "expiresAt": "2026-10-07T22:23:03.720Z"
}

11.2 ID format

Trust profile IDs use the format TRST- followed by 5 uppercase hex characters.

11.3 Dimensions

A dimension groups related checks. Each dimension contains:

Every check in the curated set is a presence check: a token balance above zero, an NFT held, or, in the account dimension, code present at the wallet address. A curated check on a chain whose wallet is an optional request parameter (Solana, XRPL, Stellar, Sui) cannot be evaluated when that wallet was not supplied. Such a check stays in the signed profile so the condition set is stable, and carries evaluated: false, reason: "wallet_not_provided", and requires naming the parameter. It carries no anchor, met is false, and it is excluded from passCount and failCount; the summary reports the same total as totalNotEvaluated. Verifiers MUST NOT read an unevaluated check as evidence that the condition was not met. Evaluated checks do not carry the evaluated field.

Ten base dimensions are always present, in this fixed order: stablecoins, governance, nfts, staking, institutional_stablecoins, tokenized_treasuries, stablecoin_deposits, wrapped_bitcoin, names, and account, followed by any of solana, xrpl, bitcoin and tron that were switched on, in that order. The order is the same for every wallet, in a batch as in a single profile. Readers MAY look dimensions up by name; the order of checks inside a dimension is stable. The account dimension holds two checks per chain on Ethereum, Base, Arbitrum, Optimism and Polygon: contract code present (bytecode other than the EIP-7702 designator at the wallet address) and EIP-7702 delegation present (the designator at the address). The two are exclusive on a chain and a plain key reads false on both; which contract is never named. Each row's evaluatedCondition is the Section 7.3 layout, so its conditionHash equals that of the equivalent account_code attest condition. These rows carry available: false in proof mode. Signatures are unaffected: the v2 preimage is canonical JSON with sorted keys, and the v1 preimage is the object exactly as the issuer serialized it, which a verifier checks as received. Four optional dimensions appear only when their wallet parameter is supplied: solana (solanaWallet), xrpl (xrplWallet), bitcoin (bitcoinWallet), and tron (tronWallet). A stellarWallet or suiWallet adds no dimension; it lets the Stellar and Sui checks inside the base dimensions (institutional_stablecoins, and USDY on Sui in tokenized_treasuries) be evaluated.

11.4 Condition set versioning

The conditionSetVersion field is a dated identifier of the curated check list that was run, currently "2026-10-08". It carries the same value on every key version and sits inside the signed payload. It is bumped whenever a row is added to or removed from the set. Readers MAY log it and SHOULD treat profiles carrying different values as incomparable. Signature verification MUST NOT fail solely because the value is unfamiliar: the kid, not this field, selects the signing preimage (Section 3). A relying application MAY require a particular value for its own policy.

11.5 Signing

The entire trust object (including id, wallet, conditionSetVersion, dimensions, summary, profiledAt, expiresAt) is signed as a single payload using the same ECDSA P-256 mechanism described in Section 3.

11.6 Requests and batches

POST /v1/trust requires wallet, an EVM address. solanaWallet, xrplWallet, bitcoinWallet, tronWallet, stellarWallet and suiWallet are optional; one that is supplied but malformed is rejected with a 400, never dropped.

With proof: "merkle" each evaluated check carries a proof object (Section 10). Only EVM token checks can carry an available proof: NFT checks, checks on non-EVM chains, the account rows (Section 11.3), and token checks on tokens that compute balances rather than storing them return available: false. A check that was not evaluated carries none. The proof sits inside the signed dimensions, outside conditionHash.

POST /v1/trust/batch takes wallets, an array of 1 to 10 objects, each with the same wallet fields as /v1/trust. The response's data.results holds one entry per wallet, in request order: either {trust, sig, kid, pqSig, pqKid}, a profile signed on its own and verified exactly as a single profile is, or an unsigned {error: {wallet, message}} for a wallet that could not be profiled. data.summary is {requested, succeeded, failed} and is not signed. Every profile in one batch is read at the same block on each EVM chain.

12. Verification Algorithm

A conforming verifier MUST implement checks 1 and 2. Checks 2a, 3 and 4 are RECOMMENDED; Checks 5 and 6 are OPTIONAL. Checks are numbered in publication order; Check 2a was added after Check 6 and keeps the numbers of the others. A verifier reports six independent verdicts: signature (Check 1), condition hashes (Check 2), counts (Check 2a), freshness (Check 3), expiry (Check 4), and the post-quantum signature (Check 6); Check 5 verifies a proof carried with the artifact and is not one of the six verdicts.

Check 1: Signature verification

1. Fetch the JWKS document from https://api.insumermodel.com/v1/jwks.
2. Select the key matching the response's kid. The set holds keys of two types (Section 4.1); select by kid, never by position, and treat an unknown kid as unverifiable. A kid that selects no key (missing, unknown, or the key set unreachable) fails this check alone: Checks 2 to 4 need no key and are still performed and reported as their own verdicts, and the post-quantum verdict of Check 6 is determined by what was transmitted, absent when no post-quantum signature was and unverifiable when one was, since that kid selects no preimage. The artifact is rejected whenever Check 1 does not pass.
3. Reconstruct the signed preimage for the scheme the kid selects (Section 14):
   • v2 (insumer-attest-v2, insumer-trust-v2): for an attestation "insumer.attestation.v2" + "\n" + canonical_json({"v":2,"id":"...","pass":...,"results":[...],"attestedAt":"..."}); for a trust profile "insumer.trust.v2" + "\n" + canonical_json(trust) where trust is the whole returned trust object (no "v" member, expiresAt included); where canonical_json is the RFC 8785 form with keys sorted lexicographically and recursively (Section 3.3.1).
   • v1 (insumer-attest-v1): for an attestation {"id":"...","pass":...,"results":[...],"attestedAt":"..."}; for a trust profile the whole trust object, {"id","wallet","conditionSetVersion","dimensions","summary","profiledAt","expiresAt"}; in each case with fields in that exact insertion order and no domain tag (Section 3.3).
4. Compute SHA-256 of the preimage bytes.
5. Verify the ECDSA P-256 signature against the digest using the public key.
6. If verification fails, REJECT the attestation.

The simplest approach is to use insumer-verify, which handles payload reconstruction and verification in a single call; it is published for Node.js on npm and for Python on PyPI under the same name, and both pass the published test vectors.

Check 2: Condition hash integrity

For each result in results (for a trust profile, each check in every dimensions[*].checks):

1. Compute canonical_json(evaluatedCondition) (keys sorted lexicographically and recursively, no whitespace, Section 8).
2. Compute SHA-256 of the resulting bytes.
3. Compare "0x" + hex(digest) to the claimed conditionHash.
4. If any hash does not match, REJECT the attestation.

Check 2a: Counts (RECOMMENDED)

passCount and failCount are not signed (Section 3.3). Count the results whose met is true and the results whose met is false, and compare them with passCount and failCount. If either differs, or only one of the two is present, REJECT the attestation: a count was changed after signing. An attestation carrying neither count passes this check. A JWT carries no counts, so the check does not apply to it. The reference verifier reports this check as its own verdict, checks.counts, since insumer-verify 1.11.0.

Check 3: Block freshness (RECOMMENDED)

If blockTimestamp is present:

1. Parse blockTimestamp as a UTC datetime.
2. Compute age = now() - blockTimestamp.
3. If age exceeds the verifier's configured maxAge (RECOMMENDED default for a live access decision: 120 seconds, Section 9.4; no maximum when the result is read as evidence), REJECT or flag the attestation as stale.

If blockTimestamp is absent, the verifier MAY use attestedAt as a weaker freshness signal. For a trust profile, profiledAt takes the place of attestedAt.

Check 4: Expiry (RECOMMENDED)

1. Parse expiresAt as a UTC datetime.
2. If expiresAt is later than attestedAt plus the issuance window (30 minutes, or 5 minutes when any result carries an erc7710_delegation condition), REJECT the attestation as tampered.
3. If now() > expiresAt, REJECT the attestation as expired.

expiresAt is not part of the signed payload (Section 3.3), while attestedAt is. InsumerAPI never issues a validity window longer than the values above, so an expiresAt further from the signed attestedAt than the issuance window can only have been edited after signing; step 2 rejects it without waiting for the expiry step, which would otherwise be reading an attacker-chosen clock. An honest attestation is unaffected: its expiresAt is exactly attestedAt plus the window. The insumer-verify library performs this binding automatically. The step does not apply on the JWT path (Section 5.4), where exp is inside the signed token. Verifiers MAY tolerate up to 60 seconds of skew on this binding, rejecting only when expiresAt exceeds attestedAt plus the window by more than that; the reference verifier applies that 60 second tolerance. Verifiers MAY likewise apply a small clock-skew allowance (RECOMMENDED: 60 seconds, as in Section 9.4) to the age computed in Check 3 and to step 3 above; the rule stays fail-closed, and an attestation older than expiresAt plus the allowance is rejected. The reference verifier applies this allowance from release 1.8.4 (option clockSkew, default 60 seconds, 0 disables it).

Check 5: Merkle proof (OPTIONAL)

If a Merkle proof is present and available is true, verify it against a trusted block header source. If subject is "delegation_revocation", the verifier MUST also recompute storageKey from the delegationHash in evaluatedCondition before relying on the proven value, as specified in Section 10.7.

Check 6: Post-quantum signature (OPTIONAL, reported as its own verdict)

When a response carries pqSig and pqKid (raw format) or a sibling pqJwt (JWT format), the verifier MAY check the post-quantum signature and MUST report the result as its own verdict, separate from Checks 1 to 4. The post-quantum signature is additive: sig, kid, and jwt are unchanged, and a verifier that does not implement this check ignores the fields.

1. Resolve pqKid in the JWKS to an RFC 9964 key (kty "AKP", alg "ML-DSA-65", raw public key in pub). An unresolvable pqKid is unverifiable, never a pass.
2. Rebuild the classical preimage exactly as in Check 1 (selected by the classical kid), prepend the domain tag: "insumer.attestation.pq1" + "\n" + preimage (trust profiles: "insumer.trust.pq1"), and verify the ML-DSA-65 signature in pqSig (base64) over those UTF-8 bytes (pure ML-DSA, empty context). A classical kid the verifier does not recognise selects no preimage, so the post-quantum signature cannot be evaluated: it is unverifiable, never refuted. A verifier MUST NOT fall back to another era's preimage for an unrecognised kid, because the post-quantum signature would then be checked against bytes the issuer never signed and a genuine one reported as refuted the first time a new signing kid appears. A recognised classical kid that names the other artifact type is a relabelled artifact, not a new era, and is refuted as before (test vector 21); a pqKid that names the other artifact type is unverifiable (test vector 22).
3. For pqJwt: verify the compact JWS (header alg "ML-DSA-65", kid = the PQ kid) over its own header.payload bytes, then confirm that its payload and the ES256 JWT's payload carry the identical claim set: the same member names, and for every member a deeply equal JSON value (objects compared without regard to member order, arrays in order, numbers by value). Any difference, whether a changed value, a missing member or an extra member on either side, makes the post-quantum signature refuted. The post-quantum signature therefore vouches for every claim a relying party reads from the ES256 JWT, sub, results, conditionHash and the block anchor included, and cannot be transplanted from another artifact. Byte-identical payload segments satisfy this trivially; a verifier MUST NOT require byte identity, since two serializers may order members differently. Test vectors 24 and 25 are the refused cases.
4. Report one of verified, refuted (present and fails), absent, or unverifiable (could not be checked). A refuted post-quantum signature MUST fail the artifact. An absent or unverifiable post-quantum signature affects the overall result only under the verifier's own policy: for a live access decision a verifier MAY require a verified post-quantum signature from a cutoff date of its own choosing, judged by its own clock at the time of verification and never by any timestamp inside the artifact. When reading an artifact after the fact, a verifier MUST NOT refuse it for lacking a post-quantum signature; it reports the absence and, using the anchored binding date published with the key, whether post-quantum signing existed when the artifact was issued.

A format: "jwt" response, verified whole

With format: "jwt" the response carries the tokens beside the attestation, in one object: attestation, sig, kid, pqSig, pqKid, and jwt, pqJwt. The signed attestation does not in general name the wallet (only erc8004_agent and erc7710_delegation results carry it, in evaluatedCondition); the jwt does, in sub. A verifier handed the whole object therefore SHOULD verify the tokens as well as the attestation, and report them as their own verdict: the ES256 signature of jwt under the same kid as the response, its condition hashes (Check 2), that it is the token of this attestation (jti equals id, and pass, results and exp equal the attestation's pass, results and expiresAt in whole seconds), and the pqJwt post-quantum signature as in Check 6. A failure fails the artifact. A relying party that reads claims from a jwt MUST have verified that jwt; verifying the attestation beside it is not a substitute. Test vectors 26 and 27 are the two cases; insumer-verify reports the verdict as checks.jwt from 1.8.7.

13. Security Considerations

13.1 Trust model

Without Merkle proofs, the verifier trusts InsumerAPI to have read chain state honestly. The signature guarantees InsumerAPI produced the attestation (non-repudiation) and that it has not been modified in transit (integrity). Merkle proofs provide an additional layer: they allow the verifier to independently confirm the on-chain value against a block header obtained from a source the verifier trusts, without relying on InsumerAPI’s reading of the chain.

13.2 Replay protection

Attestation IDs and attestedAt timestamps provide replay detection. Verifiers SHOULD reject attestations they have seen before (by ID) or that exceed their acceptable age.

13.3 Privacy

Standard attestations reveal only a boolean (met: true/false) and never expose raw balances or holdings quantities. This is a deliberate privacy property. The one exception is ratio_to_supply on v1 keys: its result also carries totalSupply and the computed fraction, from which the balance can be derived. Under v2 no fraction is returned.

Merkle proofs reveal the raw balance. Callers requesting proofs MUST understand this tradeoff.

InsumerAPI does not log or store wallet addresses beyond the request-response cycle. See the Privacy Policy for details.

13.4 Condition hash as tamper seal

The condition hash chain (Section 8) ensures that modifying any aspect of the evaluated condition (the contract address, threshold, comparison, chain, or, under v1, decimals) invalidates the signature. This prevents an intermediary from substituting conditions after signing.

13.5 Freshness

Verifiers SHOULD enforce freshness bounds (Check 3) to ensure attestations reflect recent chain state.

13.6 What a signed result shows, and what it does not

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.

14. Versioning

New condition types, proof types, and trust dimensions may be introduced in future versions of this specification. Verifiers SHOULD handle unrecognized condition types gracefully: the condition hash is recomputed over whatever the evaluatedCondition carries, type included, so Check 2 applies to every result; what a verifier cannot do for a type it does not know is interpret the condition, and it SHOULD report that rather than reject the whole attestation. Version changes will be reflected in the meta.version field of API responses.

14.1 Signature scheme version

The signature scheme is versioned independently of meta.version and selected by the response kid. v1 (insumer-attest-v1) signs the bare insertion-order payload (Section 3.3) and carries threshold as a JSON number with a decimals field. v2 (insumer-attest-v2, insumer-trust-v2) signs the domain-separated canonical preimage (Section 3.3.1) and carries quantities as canonical decimal strings. Both verify against the same key published at the JWKS endpoint. All keys created on or after the v2 rollout are v2; keys issued earlier remain v1 and stay verifiable unchanged. Verifiers MUST branch on kid and MUST NOT assume a single scheme. One shape is common to both schemes: the curated checks inside a trust profile (Section 11) are presence checks whose evaluatedCondition carries operator "gt", threshold as the JSON number 0, and, on token checks, decimals; that shape is frozen and is not a v1 marker.

14.2 Revision history

Version 1.0 of this specification has been extended additively since publication. Every change below adds capability or corrects a statement; none alters or invalidates a previously specified signed format. Attestations signed under any earlier revision remain valid and verify unchanged.

14.3 Verifying the key binding

The document at /.well-known/pq-key-binding.json binds the ECDSA key to the post-quantum key. It carries a statement (schema insumer.pq_key_binding.v1, issued_at, the classical JWK with its three kids, the post-quantum JWK with its two kids), a contentAddress, two signatures, and an on-chain anchor. A verifier checks it as follows:

1. contentAddress = "0x" + SHA-256(canonical_json(statement)), with canonical_json exactly as in Section 3.3.1.
2. pqSelfSig is ML-DSA-65 over the UTF-8 bytes of "insumer.pq_key_binding.v1" + "\n" + contentAddress, verified with the post-quantum public key in the statement (the key owns the statement).
3. classicalSig is ES256 (P1363) over the UTF-8 bytes of "insumer.pq_key_binding.v1.classical" + "\n" + contentAddress, verified with the ECDSA public key in the statement (the classical key endorses it).
4. anchor.digest = SHA-256(canonical_json(document without the anchor member)), published as the calldata of anchor.txHash on Base (chain id 8453) in block anchor.blockNumber. Read the transaction from any Base node and compare. The block time is the public record of when the post-quantum key came into existence; it is the value a verifier reading an artifact as evidence uses to say whether a post-quantum signature could have existed when the artifact was issued.

15. References

• RFC 2119: Key words for use in RFCs
• RFC 7517: JSON Web Key (JWK)
• RFC 7518 §3.4: ECDSA using P-256 and SHA-256 (ES256)
• EIP-155: Chain ID specification
• RFC 8785: JSON Canonicalization Scheme (JCS)
• RFC 9964: ML-DSA in JOSE and COSE (the AKP key type)
• FIPS 204: Module-Lattice-Based Digital Signature Standard (ML-DSA)

Appendix A: JSON Serialization

This specification uses two different JSON serialization approaches:

Condition hashes (Section 8) use sorted-key canonical JSON:

1. All object keys are sorted by UTF-16 code unit, the order RFC 8785 specifies and the order JavaScript's default sort produces (identical to code point order for every key the API emits, which are ASCII).
2. Sorting is applied recursively to nested objects.
3. No whitespace between tokens.

v1 signature payloads (Section 3.3) use fixed insertion-order JSON: fields appear in the order specified in Section 3.3, not alphabetically. This is the standard output of JSON.stringify() with no replacer argument. v2 signature payloads (Section 3.3.1) are a domain tag and a newline followed by the sorted-key canonical JSON described above.

Condition hash example:

Input evaluatedCondition (unsorted):

{"threshold": "1000", "type": "token_balance", "operator": "gte", "chainId": 1, "contractAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"}

Sorted for hashing:

{"chainId":1,"contractAddress":"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48","operator":"gte","threshold":"1000","type":"token_balance"}

Appendix B: Verification Library

insumer-verify is the official verification library for InsumerAPI attestations, published for Node.js on npm and for Python on PyPI under the same name. The npm package has zero required dependencies; install the optional peer @noble/post-quantum to verify the post-quantum signature. The Python package requires cryptography; install insumer-verify[pq] for the post-quantum signature. Runs all verification checks described in Section 12 in a single function call:

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://api.insumermodel.com/v1/jwks"
});

console.log(result.valid); // true - all checks passed

As of v1.3.0, insumer-verify auto-detects the input type: pass a JWT string and it verifies the ES256 signature via JWKS plus the same checks (Section 12), except that a bare token cannot carry its post-quantum signature: supply that separately, or Check 6 reports it absent. Pass an attestation object and it uses the raw verification path.

Available on npm. Source on GitHub.

Appendix C: Getting Started

InsumerAPI is in production and ready to integrate. To start verifying wallets:

1. Get a free API key at insumermodel.com/developers
2. Call POST /v1/attest with a wallet and conditions (add "format": "jwt" for gateway integration)
3. Verify the response with insumer-verify (npm)