Condition

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/insumermodel-com/json-schema/insumermodel-com-condition-schema.json",
  "title": "Condition",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/insumermodel-com-openapi.json#/components/schemas/Condition",
  "type": "object",
  "required": [
    "type"
  ],
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "token_balance",
        "nft_ownership",
        "eas_attestation",
        "farcaster_id",
        "evm_view_call",
        "ratio_to_amount",
        "ratio_to_supply",
        "erc8004_agent",
        "erc7710_delegation",
        "account_code"
      ]
    },
    "expect": {
      "type": "string",
      "enum": [
        "none",
        "eip7702",
        "contract"
      ],
      "description": "Required for account_code. The code state the wallet address itself must be in at the anchored block: \"none\" (no code: a plain key account, including an address that has never been used, which has no code either), \"eip7702\" (the EIP-7702 delegation designator: a key that has delegated execution to a contract), or \"contract\" (any other code: a smart-contract wallet, a protocol, a token). The three are exclusive on a chain. The result is the boolean met; the code and the delegation target are never returned. EVM chains only (a non-EVM chainId is a 400). 1 credit. Proof mode returns an EIP-1186 account proof whose codeHash field is the proven value (subject \"account_code\")."
    },
    "delegate": {
      "type": "string",
      "description": "Optional, account_code with expect \"eip7702\" only (a 400 with any other expect). An EVM address: the condition is met iff the wallet's designator points at this address. A caller who cares which contract names it here and still receives only yes or no; when supplied it is echoed inside the signed evaluatedCondition so the hash binds the question asked."
    },
    "contractAddress": {
      "type": "string",
      "description": "Token or NFT contract address (required for token_balance, nft_ownership, ratio_to_amount, ratio_to_supply, and evm_view_call; use \"native\" for the chain's native asset on token_balance and ratio_to_amount; nft_ownership requires the NFT contract, ratio_to_supply an ERC-20 contract and evm_view_call a real contract, and \"native\" on any of those three is a 400. To ask whether a wallet holds the native coin, use token_balance with \"native\"). For Solana: \"native\" for SOL, or the mint address (base58, 32 to 44 characters); anything else is a 400. On nft_ownership a Solana address names one NFT (its mint address, or the asset ID of a compressed or Core NFT) or a verified collection, which any NFT in that collection satisfies; an unverified collection tag never counts. For XRPL: use \"native\" for XRP, or the issuer r-address for trust line tokens and NFTs; the base58 checksum is verified, so a mistyped issuer is a 400. For Tron: \"native\" for TRX, or a TRC-20 contract address (starts with T; the checksum is verified, so a mistyped address is a 400). For Stellar: \"native\" for XLM, or the asset issuer's G-address (StrKey, 56 chars; the checksum is verified, so a mistyped issuer is a 400). For Bitcoin: must be \"native\". For Sui: must be a coin type (address::module::Name, optionally with type parameters); the short form (0x2::sui::SUI) and the 64-hex long form of an address name the same coin, and anything that is not a coin type is a 400. On two chains the native asset is ALSO exposed as an ERC-20 at a mirror contract, so \"native\" and that address are one balance read two ways: Celo 42220 (0x471EcE3750Da237f93B8E339c536989b8978a438) and Arc 5042 (USDC predeploy 0x3600000000000000000000000000000000000000, which is Arc's gas asset). TWO token_balance conditions requiring BOTH in one call count the same holding twice, so that pair is refused with a 400 naming both condition indexes before any credit is charged — use one or the other. The guard covers token_balance pairs only; a ratio_to_amount rule is not summed against a token_balance threshold, so that combination is redundant rather than refused."
    },
    "selector": {
      "type": "string",
      "description": "Required for evm_view_call. The canonical signature of a view function returning bool, in the form \"functionName(address)\" (e.g. \"hasAccess(address)\"). v1 supports single-address-argument view functions only; the 4-byte selector is derived from this signature. EVM chains only."
    },
    "chainId": {
      "$ref": "#/$defs/ChainId"
    },
    "threshold": {
      "oneOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ],
      "description": "Minimum balance required (token_balance type), in token/display units — e.g. \"100\" for 100 USDC or \"0.001\" for 0.001 ETH, NOT base units/wei. The token's own decimals are read from the chain (a decimals value in the request is a cross-check, never an override) and the raw balance is scaled before comparison, so a base-unit threshold such as \"1000000\" for 1 USDC is a valid request for one million USDC and simply returns met: false. v1 keys take a JSON number (e.g. 100). v2 keys — which is every newly created key — require a decimal STRING (e.g. \"100\"); a JSON number is rejected with 400. v2 carries the threshold as an exact canonical decimal so an agent can specify full-precision thresholds that a JSON float would silently round. Must be > 0 (use \"0.000001\" / 0.000001 for prove-any-balance). A decimal string is at most 400 characters."
    },
    "multiple": {
      "oneOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ],
      "description": "Required for ratio_to_amount. The collateralization multiple — the condition is met iff balance >= multiple * amount (e.g. 10 for \"hold >= 10x the transaction amount\"). v1 keys take a JSON number; v2 keys — every newly created key — require a decimal STRING (e.g. \"10\") and reject a JSON number with 400. Must be > 0. A decimal string is at most 400 characters."
    },
    "amount": {
      "oneOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ],
      "description": "Required for ratio_to_amount. The per-request reference amount (e.g. the transaction size the agent intends to make), in token/display units — e.g. 100 for 100 USDC, NOT base units/wei. v1: JSON number; v2: decimal STRING (e.g. \"100\"). Must be > 0. An amount with more decimal places than the token has is a 400. ratio_to_amount is supported on EVM chains only. A decimal string is at most 400 characters."
    },
    "minFraction": {
      "oneOf": [
        {
          "type": "number"
        },
        {
          "type": "string"
        }
      ],
      "description": "Required for ratio_to_supply. The required share of the token's on-chain total supply, as a fraction in (0, 1] — e.g. 0.005 for 0.5% of supply. The condition is met iff balance / totalSupply() >= minFraction. v1: JSON number; v2: decimal STRING (e.g. \"0.005\"). Use for project/governance tokens where share-of-supply is meaningful (not stablecoins). Supported on EVM chains, ERC-20 contracts only. A decimal string is at most 400 characters."
    },
    "decimals": {
      "oneOf": [
        {
          "type": "integer",
          "minimum": 0,
          "maximum": 100
        },
        {
          "type": "string",
          "pattern": "^(0{0,2}[0-9]|0?[1-9][0-9]|100)$"
        }
      ],
      "description": "Optional, for token_balance and ratio_to_amount. The token's own decimals are always read from the chain: decimals() on EVM and Tron at the anchored block, the coin metadata on Sui; native coins are fixed by definition. A scale is never taken from the request and never assumed. When sent, decimals is a cross-check. It must be an integer from 0 to 100 (a JSON number, or its digits as a string); anything else is a 400. If it equals the token's own value nothing changes; if it differs the API returns 400 and the message names the token's own value. A token that states no decimals on chain: a zero balance is signed as met: false (zero is zero at any scale); any other balance is a 400 on every key, because no scale exists for the threshold to be read at and none is ever taken from the request. If the token's decimals cannot be read (an upstream failure) the API returns the documented 503 rpc_failure, never a 400. Why: a threshold is in display units, so the verdict depends on the scale, and the relying party must be able to trust that the scale is the token's own."
    },
    "currency": {
      "type": "string",
      "description": "XRPL currency code (required for XRPL trust line tokens, ignored for other chains). One of: a 3-character standard code (e.g. \"USD\"; letters, digits and ?!@#$%^&*<>(){}[]| only), a token name of 1 to 20 printable ASCII characters (e.g. \"RLUSD\", hex-encoded to a 40-character code), or a 40-character hex currency code. Anything else, including a non-string, is a 400. Currency codes are case-sensitive on the XRP Ledger: send the code exactly as the issuer created it. `USD` and `usd` are different currencies, and a token name is encoded in the letter case sent. `XRP` is the native coin, not a trust line currency: on a trust line condition it is a 400, as are its 40-character hex spellings. To check XRP, use contractAddress \"native\". The 40-character hex spelling of a 3-character code is that code, and is returned in the 3-character form. The code is carried inside the signed evaluatedCondition, so it can only ever be well-formed Unicode."
    },
    "assetCode": {
      "type": "string",
      "description": "Stellar trustline asset code (e.g. \"USDC\"): 1 to 12 characters from a-z, A-Z, 0-9. Required for Stellar trustline token_balance conditions (contractAddress is the G-issuer); not used for native XLM. Anything outside that alphabet, or a non-string, is a 400. The code is carried inside the signed evaluatedCondition, so it can only ever be well-formed Unicode."
    },
    "taxon": {
      "type": "integer",
      "description": "XRPL NFToken taxon filter (optional, for XRPL conditions): an integer from 0 to 4294967295, as a JSON number or its digits as a string; anything else (a fraction, a negative, text) is a 400, and so is null on nft_ownership. On nft_ownership it filters NFTs by issuer + taxon; on any XRPL condition a supplied taxon is carried into the signed evaluatedCondition as a JSON number."
    },
    "label": {
      "type": "string",
      "maxLength": 100,
      "description": "Human-readable label for this condition. It is carried inside the signed result. A longer label is cut to 100 UTF-16 code units rather than rejected, and the cut never splits a surrogate pair: the signed label is always well-formed Unicode (an unpaired surrogate is replaced with U+FFFD), so the signed bytes can be rebuilt in any language."
    },
    "schemaId": {
      "type": "string",
      "description": "EAS schema ID (bytes32 hex string). Required for eas_attestation unless template is provided."
    },
    "attester": {
      "type": "string",
      "description": "Expected attester address (optional, for eas_attestation). If provided, the attestation's attester must match this address (case-insensitive). Recipient is not a request-side field — it auto-binds to the wallet being verified, and the attestation's recipient field must equal that wallet for the condition to pass."
    },
    "indexer": {
      "type": "string",
      "description": "EAS indexer contract address (0x + 40 hex chars; format-validated when present: a malformed value returns 400, as does a malformed attester). Required for raw (non-template) eas_attestation conditions: a raw condition without it returns 400, because without an indexer there is no way to resolve an attestation UID and nothing could be evaluated. Templates supply their own. The API resolves the attestation UID by calling `getAttestationUid(address recipient, bytes32 schema) returns (bytes32)` (selector 0xab2717dd) on this contract, then fetches the resolved attestation from the EAS contract on the target chain. The condition is met iff ALL of: the attestation's recipient is the wallet being verified; it is not revoked (revocationTime is 0); it has not expired (expirationTime is 0 or later than the anchored block's timestamp); its schema equals schemaId (checked on the attestation itself, not taken from the indexer); and, when attester is given, its attester matches. The Coinbase templates are checked the same way; the Gitcoin Passport templates are decided by their decoder (see decoderMethod). Custom EAS issuers must deploy or co-list in such an indexer; see /developers/compliance/#custom-eas-issuers."
    },
    "template": {
      "type": "string",
      "enum": [
        "coinbase_verified_account",
        "coinbase_verified_country",
        "coinbase_one",
        "gitcoin_passport_score",
        "gitcoin_passport_active"
      ],
      "description": "Pre-configured compliance template name. Use instead of raw schemaId/attester/indexer — the template fills in all three. See GET /v1/compliance/templates for available templates."
    },
    "agentId": {
      "type": "string",
      "description": "Required for erc8004_agent (generally available on any API key, and on x402 pay-per-call with no key). The ERC-8004 agent ID as a uint256 decimal string. Must be supplied by the caller — the deployed Identity Registry has no wallet-to-agentId reverse lookup. The condition is met iff the attested wallet owns the agent NFT (ownerOf) or is the registry's on-chain signature-verified agentWallet binding (getAgentWallet). Registry: ERC-8004 Identity Registry 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432 on Base; chainId 8453 only. tokenURI JSON is never trusted. Note the honest semantics: 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\" and implies no vetting, no reputation, no endorsement. Merkle proofs are not available for this type."
    },
    "delegationManager": {
      "type": "string",
      "description": "Required for erc7710_delegation (generally available on any API key, and on x402 pay-per-call with no key). The DelegationManager contract address the delegation was signed against. Must be one of the three recognized MetaMask Delegation Framework managers on Base (framework versions 1.0.0 / 1.1.0 / 1.3.0; current default 0xdb9B1e94B5b69Df7e401DDbedE43491141047dB3). chainId 8453 only. Max 3 erc7710_delegation conditions per request. Merkle proofs ARE available for this type: with proof: \"merkle\" the result carries an EIP-1186 storage proof of the revocation slot (subject \"delegation_revocation\"), for managers whose storage layout has been verified on-chain — currently the v1.3.0 manager 0xdb9B1e94B5b69Df7e401DDbedE43491141047dB3 on Base. Other recognized managers return proof.available: false with a reason naming the unverified layout, because an inferred slot would produce a proof of the wrong location that still verifies against the block header."
    },
    "expectedDelegator": {
      "type": "string",
      "description": "Required for erc7710_delegation. The principal address the caller asserts authorized this agent. The condition fails unless the delegation's declared delegator matches this address — without it a self-delegation would read as authority, so there is no structural-only mode."
    },
    "delegation": {
      "type": "object",
      "description": "Required for erc7710_delegation. The signed ERC-7710 delegation to evaluate. The condition is met iff ALL of: the attested wallet is the delegate; the declared delegator is expectedDelegator; the EIP-712 signature verifies (EOA recovery, or ERC-1271 for contract principals); the delegation is not revoked on-chain as of the anchored block; every caveat uses a recognized enforcer (an unknown enforcer fails the condition, no override); and any time-window caveat is currently satisfied. Recognized caveat enforcers (5 kinds): timestamp (time window — evaluated now), erc20_transfer_amount, native_transfer_amount, allowed_targets, limited_calls. Recognition is per manager: native_transfer_amount is recognized on the 1.1.0 and 1.3.0 managers only, not on 1.0.0 (a 1.0.0 delegation carrying it fails as an unknown enforcer). The last four are REPORTED as declared limits — on-chain redemption enforces them; the attestation states what the principal signed, it does not simulate enforcement. Keep the two apart: `met` is the verdict — the boolean listed above, and nothing more. `declaredLimits` is NOT an input to that boolean; it is a signed DECODE of the caveat terms the caller itself submitted, riding alongside the verdict inside the signed results — on true and false verdicts alike, once the signature and revocation checks pass. Each decoded entry carries the exact `terms` hex it was decoded from, so the decode is a checkable claim rather than an assertion: re-run the enforcer contract's public getTermsInfo byte layout against `terms` and compare, and recompute `delegationHash` (in evaluatedCondition — the EIP-712 struct hash committing to every caveat's enforcer and terms) from the delegation object you hold. Set the top-level `declaredLimits` request modifier to \"omit\" to leave the decode out of the signed results entirely. Attestations containing a delegation condition expire in 5 minutes (not the standard 30) — revocation is one transaction away, so the verdict window stays tight; the verdict states \"not revoked as of block N\".",
      "required": [
        "delegator",
        "delegate",
        "authority",
        "caveats",
        "salt",
        "signature"
      ],
      "properties": {
        "delegator": {
          "type": "string",
          "description": "Principal address that signed the delegation. Must equal expectedDelegator."
        },
        "delegate": {
          "type": "string",
          "description": "Agent wallet the delegation authorizes. Must equal the attested wallet."
        },
        "authority": {
          "type": "string",
          "description": "Root authority only (0xffff…ffff, 32 bytes of 0xff). Delegation chains are unsupported in v1."
        },
        "caveats": {
          "type": "array",
          "maxItems": 16,
          "description": "Caveats the principal signed (max 16). Every enforcer must be recognized or the condition fails.",
          "items": {
            "type": "object",
            "required": [
              "enforcer",
              "terms"
            ],
            "properties": {
              "enforcer": {
                "type": "string",
                "description": "Caveat enforcer contract address"
              },
              "terms": {
                "type": "string",
                "description": "ABI-encoded caveat terms (hex)"
              }
            }
          }
        },
        "salt": {
          "type": "string",
          "description": "Delegation salt (decimal string)"
        },
        "signature": {
          "type": "string",
          "description": "EIP-712 signature over the delegation (hex). EOA recovery, or ERC-1271 for smart-contract principals."
        }
      }
    }
  },
  "$defs": {
    "ChainId": {
      "oneOf": [
        {
          "type": "integer",
          "enum": [
            1,
            56,
            8453,
            43114,
            137,
            42161,
            10,
            88888,
            1868,
            98866,
            146,
            100,
            5000,
            534352,
            59144,
            324,
            81457,
            167000,
            2020,
            42220,
            88,
            204,
            480,
            130,
            57073,
            1329,
            80094,
            33139,
            50,
            4663,
            5042
          ]
        },
        {
          "type": "string",
          "enum": [
            "solana",
            "xrpl",
            "bitcoin",
            "tron",
            "stellar",
            "sui"
          ]
        }
      ],
      "description": "EVM chain ID (integer), or one of \"solana\", \"xrpl\", \"bitcoin\", \"tron\", \"stellar\", \"sui\" (string). Supported chains: Ethereum (1), BNB Chain (56), Base (8453), Avalanche (43114), Polygon (137), Arbitrum (42161), Optimism (10), Chiliz (88888), Soneium (1868), Plume (98866), Sonic (146), Gnosis (100), Mantle (5000), Scroll (534352), Linea (59144), zkSync Era (324), Blast (81457), Taiko (167000), Ronin (2020), Celo (42220), Viction (88), opBNB (204), World Chain (480), Unichain (130), Ink (57073), Sei (1329), Berachain (80094), ApeChain (33139), XDC Network (50), Robinhood Chain (4663), Arc (5042), Solana (\"solana\"), XRP Ledger (\"xrpl\"), Bitcoin (\"bitcoin\"), Tron (\"tron\"), Stellar (\"stellar\"), Sui (\"sui\"). Bitcoin only supports token_balance with contractAddress \"native\". Tron, Stellar, and Sui support token_balance only. Moonbeam (1284) and Moonriver (1285) were retired on 2026-09-20 after both networks stopped producing blocks. GLMR and MOVR now live on Base (chainId 8453) as ERC-20s and are read with an ordinary token_balance condition; a request naming either retired chain returns 400.\n"
    }
  }
}