{"openapi":"3.0.0","paths":{"/chains":{"get":{"description":"Returns every EVM network currently available on the platform. Each entry exposes the internal `id` used in query requests, the numeric `evmChainId`, and a human-readable display `name`. Use the `id` value in the `chain` field of the query endpoints.","operationId":"ChainsController_listChains","parameters":[],"responses":{"200":{"description":"The list of supported chains.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChainsResponseDto"}}}}},"summary":"List supported EVM chains","tags":["Chains"]}},"/query":{"post":{"description":"Evaluates a query expression against the contracts defined in `schema` on the given `chain`. The engine automatically batches on-chain reads into multicall rounds and returns a typed `result` along with execution metadata (block number, call count), latency, and units consumed. Validate expressions with [`POST /query/validate`](#tag/query/POST/query/validate) before invoking this endpoint to catch type errors without spending units.","operationId":"QueryController_executeQuery","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryExecuteRequestDto"}}}},"responses":{"200":{"description":"Successful execution. The response contains the typed `result`, on-chain `meta` (block number, total calls, total rounds), `performance` metrics, and the `units` consumed by this call.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryExecuteResponseDto"}}}},"400":{"description":"The request body failed validation, or the query expression is invalid (unknown identifiers, type mismatch, unsupported chain)."},"402":{"description":"The organization's subscription does not allow API access. Upgrade the plan or update billing details."},"429":{"description":"The organization has exceeded its rate limit. Retry after the window resets."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Execute a query against EVM smart contracts","tags":["Query"]}},"/query/validate":{"post":{"description":"Type-checks a query expression against the provided schema and returns its inferred result type plus an `estimatedUnits` cost. Use this endpoint in editors and pre-flight checks to surface errors early without consuming units for an actual on-chain read.","operationId":"QueryController_validateExpression","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryValidateRequestDto"}}}},"responses":{"200":{"description":"The expression was parsed and type-checked. `valid` reflects whether the expression is well-formed, `type` is the inferred result type, and `estimatedUnits` is an upper bound on the units an execution would consume.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryValidateResponseDto"}}}},"400":{"description":"The request body failed validation (malformed schema, unsupported chain)."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Validate a query expression without executing it","tags":["Query"]}},"/query/describe":{"post":{"description":"Resolves the supplied contracts on the given `chain` and returns the fully expanded schema — contract methods, input/output types, and any context variables that are available to expressions. Call this first to discover what you can query against a set of contracts before authoring an expression.\n\nPass `include: [\"resolution\"]` to annotate the schema with where each method reads from: every contract gains an `_extension.resolution` with its dispatch route, and every method one naming the address it executes at and the source its ABI came from.","operationId":"QueryController_describeSchema","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryDescribeRequestDto"}}}},"responses":{"200":{"description":"The resolved schema, including contract methods with their input and output types plus any available context variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QueryDescribeResponseDto"}}}},"400":{"description":"The request body failed validation, or one of the contracts could not be resolved on the given chain."}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Describe a schema: extract contract methods and context","tags":["Query"]}},"/usage":{"get":{"description":"Returns the current compute-weighted unit usage for the rolling minute and hour windows. Use this endpoint to drive in-app usage meters or to gate behaviour as the organization approaches its rate limits.","operationId":"UsageController_getUsageStats","parameters":[],"responses":{"200":{"description":"The organization's unit usage snapshot: `minute`/`hour`, each with `used` and `limit`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageStatsResponseDto"}}}}},"security":[{"api-key":[]},{"bearer":[]}],"summary":"Get unit usage stats for the authenticated organization","tags":["Usage"]}}},"info":{"title":"evmquery.com API","description":"REST API for querying EVM smart contracts with expressive, typed queries.\nExecute multi-call reads against contracts on any supported chain, validate\nquery expressions ahead of time, and inspect the schema derived from your\ncontract ABIs — all from a single JSON endpoint.\n\n## Getting Started\n\n1. **Create an API key** in [API Keys settings](https://app.evmquery.com/settings/api-keys) and copy the secret.\n2. **Send the key** on every request via the `X-API-Key` header.\n3. **Pick a chain** from [`GET /chains`](#tag/chains/GET/chains) to discover supported networks.\n4. **Describe your contracts** with [`POST /query/describe`](#tag/query/POST/query/describe)\n   to see which methods and context variables are available.\n5. **Validate an expression** with [`POST /query/validate`](#tag/query/POST/query/validate)\n   to catch type errors and see estimated credit cost before executing.\n6. **Execute** with [`POST /query`](#tag/query/POST/query)\n   to run the query and receive a typed result.\n\n## Authentication\n\nEvery request must include an `X-API-Key` header. Manage keys in [API Keys settings](https://app.evmquery.com/settings/api-keys).\nKeys are scoped to a single organization; all unit usage and rate limits\napply to that organization.\n\n## Units & Rate Limits\n\nEach query consumes units proportional to the number of on-chain reads it performs. Usage is limited per organization by sliding per-minute and per-hour unit windows; exceeding a window returns `429 Too Many Requests` with a `Retry-After` header. Track consumption on the [dashboard](https://app.evmquery.com/) or via [`GET /usage`](#tag/usage/GET/usage).\n\n## Errors\n\nErrors follow the standard HTTP status codes. `400` indicates a validation\nerror in the request body, `401` an authentication failure, `403` an\nauthorization failure, and `429` a rate-limit breach. Error responses\ninclude a JSON body with a human-readable `message` and, where applicable,\nstructured `details`.","version":"v1.24.0+176b506","contact":{}},"tags":[{"name":"Chains","description":"Discover the EVM networks available on the platform. Use the returned chain identifiers in the `chain` field of query requests."},{"name":"Query","description":"Describe contract schemas, validate query expressions, and execute multi-call reads against EVM smart contracts."},{"name":"Usage","description":"Inspect rolling minute/hour unit consumption for the authenticated organization."}],"servers":[{"url":"https://api.evmquery.com/api/v1"}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key authentication. Create and manage keys in the [API Keys settings](https://app.evmquery.com/settings/api-keys)."}},"schemas":{"ChainsResponseDto":{"type":"object","properties":{"chains":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Internal chain identifier"},"evmChainId":{"type":"number","description":"Numeric EVM chain ID"},"name":{"type":"string","description":"Human-readable chain name"}},"required":["id","evmChainId","name"]}}},"required":["chains"]},"QueryExecuteRequestDtoQuerySchemaInputDto":{"type":"object","properties":{"contracts":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","description":"Contract address (shorthand for { address })"},{"type":"object","properties":{"address":{"type":"string","description":"Contract address"}},"required":["address"]}]},"description":"Named contract definitions"},"context":{"description":"Context variable type declarations","type":"object","additionalProperties":{"anyOf":[{"type":"string","enum":["sol_int"]},{"type":"string","enum":["sol_address"]},{"type":"string","enum":["bool"]},{"type":"string","enum":["string"]},{"type":"string","enum":["bytes"]},{"type":"string","enum":["list<sol_int>"]},{"type":"string","enum":["list<sol_address>"]},{"type":"string","enum":["list<bool>"]},{"type":"string","enum":["list<string>"]},{"type":"string","enum":["list<bytes>"]}]}}},"required":["contracts"]},"QueryExecuteRequestDto":{"type":"object","properties":{"chain":{"type":"string","description":"Chain Identifier"},"expression":{"type":"string","minLength":1,"description":"Query expression to evaluate"},"schema":{"$ref":"#/components/schemas/QueryExecuteRequestDtoQuerySchemaInputDto"},"context":{"description":"Runtime context variables","type":"object","additionalProperties":{}},"options":{"description":"Query execution options","type":"object","properties":{"timeoutMs":{"description":"Execution timeout in milliseconds (max 30000)","type":"integer","exclusiveMinimum":true,"maximum":30000,"minimum":0}}}},"required":["chain","expression","schema"]},"QueryExecuteResponseDto":{"type":"object","properties":{"result":{"type":"object","properties":{"value":{"description":"Query result value"},"type":{"type":"string","description":"Result type identifier","nullable":true}},"required":["value","type"]},"meta":{"type":"object","properties":{"blockNumber":{"type":"string","description":"Block number used for execution"},"totalCalls":{"type":"number","description":"Total RPC calls made"},"totalRounds":{"type":"number","description":"Execution rounds completed"}},"required":["blockNumber","totalCalls","totalRounds"],"description":"Execution metadata","nullable":true},"performance":{"type":"object","properties":{"latencyMs":{"type":"number","description":"Execution latency in milliseconds"}},"required":["latencyMs"]},"units":{"type":"object","properties":{"consumed":{"type":"number","description":"Compute-weighted units consumed by this query"}},"required":["consumed"]}},"required":["result","meta","performance","units"]},"QueryValidateRequestDtoQuerySchemaInputDto":{"type":"object","properties":{"contracts":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","description":"Contract address (shorthand for { address })"},{"type":"object","properties":{"address":{"type":"string","description":"Contract address"}},"required":["address"]}]},"description":"Named contract definitions"},"context":{"description":"Context variable type declarations","type":"object","additionalProperties":{"anyOf":[{"type":"string","enum":["sol_int"]},{"type":"string","enum":["sol_address"]},{"type":"string","enum":["bool"]},{"type":"string","enum":["string"]},{"type":"string","enum":["bytes"]},{"type":"string","enum":["list<sol_int>"]},{"type":"string","enum":["list<sol_address>"]},{"type":"string","enum":["list<bool>"]},{"type":"string","enum":["list<string>"]},{"type":"string","enum":["list<bytes>"]}]}}},"required":["contracts"]},"QueryValidateRequestDto":{"type":"object","properties":{"expression":{"type":"string","minLength":1,"description":"Query expression to validate"},"schema":{"$ref":"#/components/schemas/QueryValidateRequestDtoQuerySchemaInputDto"},"chain":{"type":"string","description":"Chain Identifier"}},"required":["expression","schema","chain"]},"QueryValidateResponseDto":{"type":"object","properties":{"valid":{"type":"boolean","description":"Whether the expression is valid"},"type":{"type":"string","description":"Inferred result type","nullable":true},"estimatedUnits":{"description":"Estimated units this expression will consume","type":"number"}},"required":["valid","type"]},"QueryDescribeRequestDtoQuerySchemaInputDto":{"type":"object","properties":{"contracts":{"type":"object","additionalProperties":{"anyOf":[{"type":"string","description":"Contract address (shorthand for { address })"},{"type":"object","properties":{"address":{"type":"string","description":"Contract address"}},"required":["address"]}]},"description":"Named contract definitions"},"context":{"description":"Context variable type declarations","type":"object","additionalProperties":{"anyOf":[{"type":"string","enum":["sol_int"]},{"type":"string","enum":["sol_address"]},{"type":"string","enum":["bool"]},{"type":"string","enum":["string"]},{"type":"string","enum":["bytes"]},{"type":"string","enum":["list<sol_int>"]},{"type":"string","enum":["list<sol_address>"]},{"type":"string","enum":["list<bool>"]},{"type":"string","enum":["list<string>"]},{"type":"string","enum":["list<bytes>"]}]}}},"required":["contracts"]},"QueryDescribeRequestDto":{"type":"object","properties":{"schema":{"$ref":"#/components/schemas/QueryDescribeRequestDtoQuerySchemaInputDto"},"chain":{"type":"string","description":"Chain identifier"},"include":{"description":"Optional detail to add to the schema. `resolution` annotates each contract and method with where its ABI came from and which address it executes at, under `_extension.resolution`.","type":"array","items":{"type":"string","enum":["resolution"]}}},"required":["schema","chain"]},"QueryDescribeResponseDto":{"$ref":"#/components/schemas/SelSELSchema"},"UsageStatsResponseDto":{"type":"object","properties":{"minute":{"type":"object","properties":{"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Compute-weighted units consumed in this window, rounded to the nearest whole unit"},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Unit cap for this window"}},"required":["used","limit"],"description":"Rolling 1-minute burst window"},"hour":{"type":"object","properties":{"used":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Compute-weighted units consumed in this window, rounded to the nearest whole unit"},"limit":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Unit cap for this window"}},"required":["used","limit"],"description":"Rolling 1-hour usage window"}},"required":["minute","hour"]},"SelSELSchema":{"type":"object","properties":{"version":{"type":"string","description":"Schema format version"},"contracts":{"type":"array","items":{"$ref":"#/components/schemas/SelContractSchema"},"description":"Available contracts and their methods"},"variables":{"type":"array","items":{"$ref":"#/components/schemas/SelVariableSchema"},"description":"Variables available in expressions (e.g., \"user\", \"blockNumber\")"},"constants":{"type":"array","items":{"$ref":"#/components/schemas/SelVariableSchema"},"description":"Top-level constants exposed by the runtime (e.g., WAD, Q96). They are registered via CEL's registerConstant mechanism, so they share the identifier namespace with variables but are read-only and always present. Surfacing them separately keeps the schema hydration path for `variables` free of these built-ins."},"types":{"type":"array","items":{"$ref":"#/components/schemas/SelTypeSchema"},"description":"Type definitions (primitives, structs, enums)"},"functions":{"type":"array","items":{"$ref":"#/components/schemas/SelFunctionSchema"},"description":"Built-in CEL functions"},"macros":{"type":"array","items":{"$ref":"#/components/schemas/SelMacroSchema"},"description":"CEL macros (all, exists, map, filter, etc.)"},"enabledFeatures":{"type":"array","items":{"type":"string"},"description":"Names of features that are enabled in this schema."},"_extension":{"$ref":"#/components/schemas/SelSELExtension","description":"Consumer-defined metadata for the schema as a whole. See  {@link  SELExtension } ."}},"required":["version","contracts","variables","types","functions","macros"],"additionalProperties":false,"description":"Root schema type for SEL expression language. Contains all contracts, variables, types, functions, and macros available in a SEL environment."},"SelContractSchema":{"type":"object","properties":{"name":{"type":"string","description":"Identifier used in expressions: erc20.balanceOf(...)"},"address":{"type":"string","description":"Contract address (for display/documentation)"},"description":{"type":"string","description":"Human-readable description"},"methods":{"type":"array","items":{"$ref":"#/components/schemas/SelMethodSchema"},"description":"Available methods (view/pure functions only)"},"_extension":{"$ref":"#/components/schemas/SelSELExtension","description":"Consumer-defined metadata. See  {@link  SELExtension } ."}},"required":["name","address","methods"],"additionalProperties":false,"description":"Schema for a contract with available methods. Methods are view/pure functions that can be called in CEL expressions."},"SelMethodSchema":{"type":"object","properties":{"name":{"type":"string","description":"Method name: \"balanceOf\""},"description":{"type":"string","description":"From NatSpec"},"params":{"type":"array","items":{"$ref":"#/components/schemas/SelParamSchema"},"description":"Method parameters"},"abi":{"$ref":"#/components/schemas/SelAbiFunction","description":"Raw ABI function entry for viem encoding/decoding"},"returns":{"$ref":"#/components/schemas/SelTypeRef","description":"Return type reference"},"category":{"type":"string","description":"For autocomplete grouping"},"_extension":{"$ref":"#/components/schemas/SelSELExtension","description":"Consumer-defined metadata. See  {@link  SELExtension } ."}},"required":["name","params","abi","returns"],"additionalProperties":false,"description":"Schema for a contract method. Represents a view or pure function that can be called in CEL expressions."},"SelParamSchema":{"type":"object","properties":{"name":{"type":"string","description":"Parameter name: \"owner\""},"type":{"$ref":"#/components/schemas/SelTypeRef","description":"Type reference: \"address\", \"uint256\", etc."},"description":{"type":"string","description":"From NatSpec"},"_extension":{"$ref":"#/components/schemas/SelSELExtension","description":"Consumer-defined metadata. See  {@link  SELExtension } ."}},"required":["name","type"],"additionalProperties":false,"description":"Schema for a method parameter or type field. Used in methods, structs, and function signatures."},"SelTypeRef":{"type":"string","description":"Type reference string used throughout the schema. These are CEL type names like \"int\", \"string\", \"bool\", or custom types defined in the schema. For parameterized types, use CEL syntax (e.g., \"list<sol_address>\")."},"SelSELExtension":{"type":"object","additionalProperties":{},"description":"Free-form, consumer-defined metadata bag for extending a schema entry with data that"},"SelAbiFunction":{"type":"object","properties":{"type":{"type":"string","const":"function"},"constant":{"type":"boolean","deprecated":"use `pure` or `view` from {@link AbiStateMutability } instead"},"gas":{"type":"number","deprecated":"Vyper used to provide gas estimates"},"inputs":{"type":"array","items":{"$ref":"#/components/schemas/SelAbiParameter"}},"name":{"type":"string"},"outputs":{"type":"array","items":{"$ref":"#/components/schemas/SelAbiParameter"}},"payable":{"type":"boolean","deprecated":"use `payable` or `nonpayable` from {@link AbiStateMutability } instead"},"stateMutability":{"$ref":"#/components/schemas/SelAbiStateMutability"}},"required":["type","inputs","name","outputs","stateMutability"],"additionalProperties":false,"description":"ABI [\"function\"](https://docs.soliditylang.org/en/latest/abi-spec.html#json) type"},"SelAbiParameter":{"$ref":"#/components/schemas/SelPrettystructure-77500401-2331-2492-77500401-2331-2673-77500401-2323-2674-77500401-2296-2675-77500401-0-6579structure-77500401-2577-2672-77500401-2496-2672-77500401-2494-2673-77500401-2331-2673-77500401-2323-2674-77500401-2296-2675-77500401-0-6579"},"SelPrettystructure-77500401-2331-2492-77500401-2331-2673-77500401-2323-2674-77500401-2296-2675-77500401-0-6579structure-77500401-2577-2672-77500401-2496-2672-77500401-2494-2673-77500401-2331-2673-77500401-2323-2674-77500401-2296-2675-77500401-0-6579":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string"},"internalType":{"$ref":"#/components/schemas/SelAbiInternalType","description":"Representation used by Solidity compiler"},"components":{"type":"array","items":{"$ref":"#/components/schemas/SelAbiParameter"}}},"required":["components","type"],"description":"Combines members of an intersection into a readable type."},"SelAbiInternalType":{"type":"string"},"SelAbiStateMutability":{"type":"string","enum":["pure","view","nonpayable","payable"],"description":"State mutability for  {@link  AbiFunction }"},"SelVariableSchema":{"type":"object","properties":{"name":{"type":"string","description":"Variable name available in expressions"},"type":{"$ref":"#/components/schemas/SelTypeRef","description":"Type reference"},"description":{"type":"string","description":"Description for hover/documentation"},"example":{"type":"string","description":"Example value for documentation"},"feature":{"type":"string","description":"The feature that contributed this variable, if any. Set automatically by the schema builder when merging feature contributions."},"_extension":{"$ref":"#/components/schemas/SelSELExtension","description":"Consumer-defined metadata. See  {@link  SELExtension } ."}},"required":["name","type"],"additionalProperties":false,"description":"Schema for a variable available in CEL expressions. Represents runtime context values like \"user\", \"blockNumber\", etc."},"SelTypeSchema":{"type":"object","properties":{"name":{"type":"string","description":"Type name"},"kind":{"type":"string","enum":["primitive","struct"],"description":"Type category"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/SelParamSchema"},"description":"For structs: field definitions"},"description":{"type":"string","description":"Description"},"feature":{"type":"string","description":"The feature that contributed this type, if any. Set automatically by the schema builder when merging feature contributions."},"_extension":{"$ref":"#/components/schemas/SelSELExtension","description":"Consumer-defined metadata. See  {@link  SELExtension } ."}},"required":["name","kind"],"additionalProperties":false,"description":"Schema for a type definition. These are reusable types that can be used in method signatures, variable types, and function signatures."},"SelFunctionSchema":{"type":"object","properties":{"name":{"type":"string","description":"Function name: \"size\", \"string\", \"int\", \"startsWith\""},"signature":{"type":"string","description":"Function signature for display\n\ne.g., \"size(list<T>): int\" | \"string.startsWith(prefix): bool\""},"description":{"type":"string","description":"Description"},"params":{"type":"array","items":{"$ref":"#/components/schemas/SelParamSchema"},"description":"Parameter documentation (excludes the receiver for methods)"},"returns":{"$ref":"#/components/schemas/SelTypeRef","description":"Return type"},"receiverType":{"$ref":"#/components/schemas/SelTypeRef","description":"When set, this function is a receiver method on the given type. E.g., `receiverType: \"string\"` means it is called as `expr.name(...)`."},"feature":{"type":"string","description":"The feature that contributed this function, if any. Set automatically by the schema builder when merging feature contributions."},"_extension":{"$ref":"#/components/schemas/SelSELExtension","description":"Consumer-defined metadata. See  {@link  SELExtension } ."}},"required":["name","signature","params","returns"],"additionalProperties":false,"description":"Schema for a built-in CEL function.\n\nFunctions are either **free functions** (`size(list)`) or\n**receiver methods** (`string.startsWith(prefix)`). When `receiverType` is set, the function is a method that can only be called on expressions of that type using dot-syntax."},"SelMacroSchema":{"type":"object","properties":{"name":{"type":"string","description":"Macro name: \"all\", \"exists\", \"map\", \"filter\""},"pattern":{"type":"string","description":"Usage pattern\n\ne.g., \"list.all(x, predicate)\" | \"list.map(x, transform)\""},"description":{"type":"string","description":"Description"},"example":{"type":"string","description":"Example"},"_extension":{"$ref":"#/components/schemas/SelSELExtension","description":"Consumer-defined metadata. See  {@link  SELExtension } ."}},"required":["name","pattern"],"additionalProperties":false,"description":"Schema for a CEL macro. Macros are syntactic sugar that expand to function calls."}}}}