openapi: 3.1.0 info: title: Mezcal Explorer API version: 1.0.0 description: Public Mezcal explorer contract for external integrators, SDKs, CLI workflows, and direct API integrations, including selected advanced utility routes. servers: - url: /api description: Hosted external Mezcal API base for this docs deployment. Requests execute against /api/v1/* on the same host. security: - MezcalApiKey: [] paths: /.well-known/mezcal-agent.json: get: summary: Agent-readable Mezcal memory contract description: Public machine-readable discovery document for agents. It points agents at the authenticated meta routes, route families, operating rules, and typed artifact contract without requiring chat history. servers: - url: / description: Same-host public well-known discovery root security: - {} responses: "200": description: Agent-readable discovery and operating contract content: application/json: schema: $ref: "#/components/schemas/AgentMemoryContract" x-mezcal-audience: public-core x-mezcal-certification: certified x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: public parameters: - $ref: "#/components/parameters/RequestIdHeader" tags: - Reference /v1/meta/capabilities: get: summary: Agent-readable API capabilities description: Authenticated route-family catalog for agents and developers. Hosted external clients call `/api/v1/meta/capabilities` with `X-Starkscan-Api-Key`; `X-Mezcal-Api-Key` remains a legacy alias. Same-origin explorer traffic uses this `/v1` route through the trusted edge. Use this before selecting the smallest route set for a task. security: - MezcalApiKey: [] responses: "200": description: Capability and route-family catalog content: application/json: schema: $ref: "#/components/schemas/MetaCapabilitiesView" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read parameters: - $ref: "#/components/parameters/RequestIdHeader" tags: - Reference /v1/meta/chains: get: summary: Supported chain ids for this deployment description: Authenticated chain catalog. Hosted external clients call `/api/v1/meta/chains` with `X-Starkscan-Api-Key`; `X-Mezcal-Api-Key` remains a legacy alias. Same-origin explorer traffic uses this `/v1` route through the trusted edge. security: - MezcalApiKey: [] responses: "200": description: Supported chain metadata content: application/json: schema: $ref: "#/components/schemas/MetaChainsView" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read parameters: - $ref: "#/components/parameters/RequestIdHeader" tags: - Reference /v1/meta/agent-context: get: summary: Full agent context contract description: Authenticated context document that combines the public agent-memory contract with handoff artifact guidance. Hosted external clients call `/api/v1/meta/agent-context` with `X-Starkscan-Api-Key`; `X-Mezcal-Api-Key` remains a legacy alias. Same-origin explorer traffic uses this `/v1` route through the trusted edge. security: - MezcalApiKey: [] responses: "200": description: Full agent context contract content: application/json: schema: $ref: "#/components/schemas/MetaAgentContextView" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read parameters: - $ref: "#/components/parameters/RequestIdHeader" tags: - Reference /v1/{chain}/status: get: summary: Chain status security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Current indexed and finalized head status content: application/json: schema: $ref: "#/components/schemas/ExplorerStatusView" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: certified x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Status /v1/{chain}/block/{number_or_hash}: get: summary: Block detail by number or hash security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: number_or_hash in: path required: true schema: type: string example: latest - name: tx_limit in: query description: Max block transactions returned (clamped to 1..200). Defaults to `50` when omitted. schema: type: integer format: int32 default: 50 minimum: 1 maximum: 200 example: 50 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Block detail with transaction preview content: application/json: schema: $ref: "#/components/schemas/BlockView" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Block not found headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: certified x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Blocks /v1/{chain}/blocks: get: summary: Paginated latest blocks feed security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: cursor in: query description: Optional block number cursor for reverse pagination. schema: type: integer format: int64 minimum: 0 example: 8279910 - name: limit in: query description: Page size (clamped to 1..200). Defaults to `25` when omitted. schema: type: integer format: int32 default: 25 minimum: 1 maximum: 200 example: 25 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Chain blocks page content: application/json: schema: $ref: "#/components/schemas/ChainBlockListPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Blocks /v1/{chain}/block/{number}/txs: get: summary: Paginated transactions for one block security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: number in: path required: true schema: type: integer format: int64 example: 8279910 - name: cursor in: query description: Optional transaction index cursor for reverse pagination. schema: type: integer format: int32 minimum: 0 example: 0 - name: limit in: query description: Page size (clamped to 1..100). Defaults to `25` when omitted. schema: type: integer format: int32 default: 25 minimum: 1 maximum: 100 example: 25 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Block transaction page content: application/json: schema: $ref: "#/components/schemas/BlockTransactionPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Block not found headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Blocks /v1/{chain}/tx/previews: post: summary: Batch transaction previews by hash security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - $ref: "#/components/parameters/RequestIdHeader" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/TransactionPreviewBatchRequest" responses: "200": description: Ordered transaction preview results content: application/json: schema: $ref: "#/components/schemas/TransactionPreviewBatchView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: advanced-utility x-mezcal-key-tier: utility description: Advanced utility route. This helper is externally supported, but it requires a broader utility-access key than the baseline read tier and is not the default starting point for new integrations. tags: - Utilities /v1/{chain}/tx/{tx_hash}: get: summary: Transaction detail by hash security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: tx_hash in: path required: true schema: type: string - name: logLimit in: query description: Maximum number of event logs returned in the transaction detail payload. Defaults to `96` when omitted. schema: type: integer format: int32 default: 96 minimum: 1 maximum: 256 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Transaction detail content: application/json: schema: $ref: "#/components/schemas/TransactionDetailView" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Transaction not found headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: certified x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Transactions /v1/{chain}/txs: get: summary: Paginated latest transactions feed security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: cursor in: query description: Optional cursor encoded as `block:tx`. schema: type: string - name: limit in: query description: Page size (clamped to 1..200). schema: type: integer format: int32 minimum: 1 maximum: 200 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Chain transactions page content: application/json: schema: $ref: "#/components/schemas/ChainTransactionListPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Transactions /v1/{chain}/messages: get: summary: Paginated canonical cross-layer messages description: Global cross-layer message feed served only from indexed StarknetCore protocol message facts. Rows are keyed by protocol message hash, not token-transfer or bridge-adapter activity. Coverage metadata is explicit because a data plane may still be backfilling protocol message facts. security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: direction in: query description: Optional message direction filter. schema: type: string enum: - all - l1_to_l2 - l2_to_l1 - name: txHash in: query description: Optional transaction hash filter. schema: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ - name: messageHash in: query description: Optional protocol message hash filter. schema: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ - name: cursor in: query description: | Optional opaque cursor returned unchanged from `nextCursor`. New responses use `m1:block:tx:message:tx_hash:message_hash:direction:source_tier` so pagination remains stable when multiple messages share the same numeric tuple. Legacy `block:tx:message` cursors remain accepted for older clients. schema: type: string pattern: ^(m1:[0-9]+:[0-9]+:[0-9]+:0[xX][0-9a-fA-F]+:0[xX][0-9a-fA-F]+:(l1_to_l2|l2_to_l1):(head|finalized)|[0-9]+:[0-9]+:[0-9]+)$ - name: limit in: query description: Page size (clamped to 1..100). schema: type: integer format: int32 minimum: 1 maximum: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Global message page with explicit coverage metadata content: application/json: schema: $ref: "#/components/schemas/MessagePage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Reference /v1/{chain}/message/{message_hash}: get: summary: Canonical cross-layer message detail description: Message detail served only from indexed StarknetCore protocol message facts. Bridge adapter lifecycle facts and token-transfer-derived bridge activity are excluded. security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: message_hash in: path required: true schema: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ - name: cursor in: query description: Optional opaque cursor returned from `nextCursor` when a message hash has more lifecycle rows. schema: type: string pattern: ^(m1:[0-9]+:[0-9]+:[0-9]+:0[xX][0-9a-fA-F]+:0[xX][0-9a-fA-F]+:(l1_to_l2|l2_to_l1):(head|finalized)|[0-9]+:[0-9]+:[0-9]+)$ - name: limit in: query description: Page size for lifecycle rows (clamped to 1..100, default 100). schema: type: integer format: int32 default: 100 minimum: 1 maximum: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Message detail with explicit coverage metadata content: application/json: schema: $ref: "#/components/schemas/MessageDetailView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Message hash has no indexed StarknetCore protocol lifecycle rows headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Reference /v1/{chain}/tx/{tx_hash}/trace: get: summary: Transaction Cairo trace by hash security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: tx_hash in: path required: true schema: type: string - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Transaction trace payload content: application/json: schema: $ref: "#/components/schemas/ContractTransactionTraceView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Transaction trace not found headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Transactions /v1/{chain}/address/{address}: get: summary: Address aggregate summary security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true schema: type: string - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Address summary content: application/json: schema: $ref: "#/components/schemas/AddressSummaryView" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Addresses /v1/{chain}/address/summaries: post: summary: Batch address aggregate summaries security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - $ref: "#/components/parameters/RequestIdHeader" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AddressSummaryBatchRequest" responses: "200": description: Ordered address summary results content: application/json: schema: $ref: "#/components/schemas/AddressSummaryBatchView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: advanced-utility x-mezcal-key-tier: utility description: Advanced utility route. This helper is externally supported, but it requires a broader utility-access key than the baseline read tier and is not the default starting point for new integrations. tags: - Utilities /v1/{chain}/address/{address}/transactions: get: summary: Paginated transaction summaries touching one address security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true schema: type: string - name: cursor in: query description: Optional cursor encoded as `block:tx:log:transfer[:kind[:txHash[:source]]]`. schema: type: string - name: limit in: query description: Page size (clamped to 1..100). schema: type: integer format: int32 minimum: 1 maximum: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Address transaction page content: application/json: schema: $ref: "#/components/schemas/AddressTransactionPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Addresses /v1/{chain}/address/{address}/token-holdings: get: summary: Indexed token holdings for one owner address description: Wallet-first indexed holdings snapshot. Use `completeness` to decide whether the response is complete enough for portfolio parity checks. Use `GET /v1/{chain}/token/{token}/balance-of/{address}` for an exact spot read when the token contract is already known. security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true schema: type: string - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Address token holdings snapshot content: application/json: schema: $ref: "#/components/schemas/AddressTokenHoldingsView" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Addresses /v1/{chain}/contract/{address}/verification: get: summary: Contract verification detail security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true schema: type: string - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Contract verification record content: application/json: schema: $ref: "#/components/schemas/ContractVerificationView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Contract verification record not found headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Contracts /v1/{chain}/contract/{address}/entrypoints: get: summary: Contract class entrypoints security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true schema: type: string - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Contract entrypoint selectors grouped by type content: application/json: schema: $ref: "#/components/schemas/ContractEntrypointsView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Contract/class not found headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Contracts /v1/{chain}/contract/{address}/events: get: summary: Paginated contract event logs description: Canonical paginated event/log surface for one contract. Use server-side topic and block filters before applying client-side protocol interpretation. Results are returned newest first in deterministic on-chain order (`blockNumber` DESC, `txIndex` DESC, `logIndex` DESC). Topic filters in this route are exact single-value matches (`topic0..topic3`), not OR-array combinations. The request `cursor` is exclusive and resumes after the last seen `(blockNumber, txIndex, logIndex)` tuple. Pass `nextCursor` from the previous response to continue without gaps or duplicates. security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true schema: type: string - name: topic0 in: query description: Optional exact single-value match for the first log topic. Empty strings are invalid. schema: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ - name: topic1 in: query description: Optional exact single-value match for the second log topic. Empty strings are invalid. schema: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ - name: topic2 in: query description: Optional exact single-value match for the third log topic. Empty strings are invalid. schema: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ - name: topic3 in: query description: Optional exact single-value match for the fourth log topic. Empty strings are invalid. schema: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ - name: from_block in: query description: Optional inclusive lower block bound. schema: type: integer format: int64 minimum: 0 - name: to_block in: query description: Optional inclusive upper block bound. schema: type: integer format: int64 minimum: 0 - name: cursor in: query description: Optional cursor in `block:tx:log` numeric format. schema: type: string pattern: ^[0-9]+:[0-9]+:[0-9]+$ - name: limit in: query description: Page size (clamped to 1..100). schema: type: integer format: int32 minimum: 1 maximum: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Contract event page content: application/json: schema: $ref: "#/components/schemas/ContractEventPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Contracts /v1/{chain}/contract/{address}/messages: get: summary: Paginated canonical messages for one contract description: Contract-scoped cross-layer message rows served only from indexed StarknetCore protocol message facts. Mezcal does not infer Messages rows from bridge adapter pairing facts, generic transactions, events, or token transfers. Coverage metadata is explicit because a data plane may still be backfilling protocol message facts. security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true schema: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ - name: direction in: query description: Optional message direction filter. schema: type: string enum: - all - l1_to_l2 - l2_to_l1 - name: txHash in: query description: Optional transaction hash filter. schema: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ - name: messageHash in: query description: Optional protocol message hash filter. schema: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ - name: cursor in: query description: | Optional opaque cursor returned unchanged from `nextCursor`. New responses use `m1:block:tx:message:tx_hash:message_hash:direction:source_tier` so pagination remains stable when multiple messages share the same numeric tuple. Legacy `block:tx:message` cursors remain accepted for older clients. schema: type: string pattern: ^(m1:[0-9]+:[0-9]+:[0-9]+:0[xX][0-9a-fA-F]+:0[xX][0-9a-fA-F]+:(l1_to_l2|l2_to_l1):(head|finalized)|[0-9]+:[0-9]+:[0-9]+)$ - name: limit in: query description: Page size (clamped to 1..100). schema: type: integer format: int32 minimum: 1 maximum: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Contract message page with explicit coverage metadata content: application/json: schema: $ref: "#/components/schemas/MessagePage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: beta x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Contracts /v1/{chain}/contract/{address}/account-calls: get: summary: Paginated trace-backed account calls for one contract description: Account-call rows are returned only from indexed transaction trace facts. Mezcal does not infer call frames from generic transaction, event, or address-activity rows because those heuristics are not production-correct. Empty pages return a machine-readable coverage reason such as `no_matching_trace_rows`; absence of rows is not claimed as proof the contract had no calls. security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true schema: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ - name: cursor in: query description: Optional cursor in `block:tx:call` numeric format. schema: type: string pattern: ^[0-9]+:[0-9]+:[0-9]+$ - name: limit in: query description: Page size (clamped to 1..100). schema: type: integer format: int32 minimum: 1 maximum: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Contract account-call page with explicit coverage metadata content: application/json: schema: $ref: "#/components/schemas/ContractAccountCallPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: unsupported x-mezcal-stability: beta x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Contracts /v1/{chain}/contract/{address}/bridge-transactions: get: summary: Paginated canonical bridge message rows for one contract description: Returns canonical bridge rows keyed by indexed message hash or paired adapter facts. Adapter lifecycle events without pairing facts are not returned from this endpoint; contracts without indexed pairing facts return an explicit unavailable coverage page with `items=[]` and `nextCursor=null` until those canonical facts are indexed. Use bridge-signals for the live unpaired L2-side activity feed. security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true schema: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ - name: cursor in: query description: Optional cursor in `block:tx:log` or `block:tx:log:transfer` numeric format. schema: type: string pattern: ^[0-9]+:[0-9]+:[0-9]+(:[0-9]+)?$ - name: limit in: query description: Page size (clamped to 1..100). schema: type: integer format: int32 minimum: 1 maximum: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Contract bridge transaction page with explicit coverage metadata content: application/json: schema: $ref: "#/components/schemas/ContractBridgeTransactionPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: unsupported x-mezcal-stability: beta x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Contracts /v1/{chain}/contract/{address}/bridge-signals: get: summary: Paginated L2 bridge signal activity for one contract description: Returns low-latency bridge rows derived from indexed L2 token-transfer bridge signals, bridge registry matches, and bridge-asset mint/burn signals. This endpoint explicitly reports `coverage.status=partial` until L1 message pairing and cross-layer completion facts are indexed; clients must not treat these rows as complete L1/L2 lifecycle records. security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true schema: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ - name: cursor in: query description: Optional cursor in `block:tx:log:transfer` numeric format. schema: type: string pattern: ^[0-9]+:[0-9]+:[0-9]+:[0-9]+$ - name: limit in: query description: Page size (clamped to 1..100). schema: type: integer format: int32 minimum: 1 maximum: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Contract bridge signal page with explicit coverage metadata content: application/json: schema: $ref: "#/components/schemas/ContractBridgeTransactionPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: beta x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Contracts /v1/{chain}/contract/{address}/read: get: summary: Read-only contract call security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true schema: type: string - name: selector in: query required: true description: 0x-prefixed entrypoint selector felt schema: type: string - name: calldata in: query description: Optional felt/decimal calldata values (repeat key for multiple values). schema: type: array maxItems: 1024 items: type: string style: form explode: true - name: block_tag in: query description: State tag used for call execution. schema: type: string enum: - latest - pending default: latest - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Read call result content: application/json: schema: $ref: "#/components/schemas/ContractReadResultView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Contract or entrypoint not found headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Contracts /v1/{chain}/address/{address}/activity: get: summary: Paginated address activity security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true schema: type: string - name: cursor in: query description: | Optional cursor in `block:tx:log:transfer` format. Must be a numeric string cursor (e.g. `100:2:-1:-1` or `100:2:3:4`). schema: type: string pattern: ^[0-9]+:[0-9]+:(-1|[0-9]+):(-1|[0-9]+)$ - name: limit in: query description: Page size (clamped to 1..100). schema: type: integer format: int32 minimum: 1 maximum: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Address activity page content: application/json: schema: $ref: "#/components/schemas/AddressActivityPage" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Addresses /v1/{chain}/token/{token}: get: summary: Token aggregate summary security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: token in: path required: true schema: type: string - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Token summary content: application/json: schema: $ref: "#/components/schemas/TokenSummaryView" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Token not found headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Tokens /v1/{chain}/token/{token}/total-supply: get: summary: Standard-token totalSupply read security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: token in: path required: true schema: type: string - name: block_tag in: query description: State tag used for call execution. schema: type: string enum: - latest - pending default: latest - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Standard-token totalSupply result content: application/json: schema: $ref: "#/components/schemas/TokenTotalSupplyView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Contract does not expose a supported totalSupply selector headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-mezcal-audience: public-core x-mezcal-certification: certified x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Tokens /v1/{chain}/token/{token}/balance-of/{address}: get: summary: Standard-token balanceOf read security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: token in: path required: true schema: type: string - name: address in: path required: true schema: type: string - name: block_tag in: query description: State tag used for call execution. schema: type: string enum: - latest - pending default: latest - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Standard-token balanceOf result content: application/json: schema: $ref: "#/components/schemas/TokenBalanceOfView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Contract does not expose a supported balanceOf selector headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-mezcal-audience: public-core x-mezcal-certification: certified x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Tokens /v1/{chain}/token/{token}/holders: get: summary: Paginated token holders with indexed balances description: |- Partner-tier endpoint for token-contract-first holder analytics. Results are served from materialized fungible-balance snapshots, not transfer-history scans. Partner-tier route backed by materialized serving tables. It is intended for bounded indexed reads and must not run request-time scans or repairs. security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: token in: path required: true schema: type: string - name: cursor in: query description: Optional opaque cursor returned unchanged from `nextCursor` in the previous response. schema: type: string - name: limit in: query description: Page size (clamped to 1..100). schema: type: integer format: int32 minimum: 1 maximum: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Token holder page content: application/json: schema: $ref: "#/components/schemas/TokenHolderPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Token contract not found or not recognized as a fungible token. headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: partner x-mezcal-key-tier: partner tags: - Tokens /v1/{chain}/token/{token}/holders/analytics: get: summary: Cached token holder concentration analytics description: |- Returns the latest operator-materialized holder concentration snapshot; the request path does not compute holder analytics. Partner-tier route backed by materialized serving tables. It is intended for bounded indexed reads and must not run request-time scans or repairs. security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: token in: path required: true schema: type: string - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Token holder analytics snapshot content: application/json: schema: $ref: "#/components/schemas/TokenHolderAnalyticsSnapshot" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Token contract not found or not recognized as a fungible token. headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: partner x-mezcal-key-tier: partner tags: - Tokens /v1/{chain}/token/{token}/controls: get: summary: Indexed token control facts description: Returns the latest operator-materialized token control snapshot. Results are served from `token_controls_snapshot`; the request path does not run live RPC, public explorer calls, request-time ABI probes, or Account Calls. security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: token in: path required: true schema: type: string - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Token controls snapshot or a typed not-indexed response content: application/json: schema: $ref: "#/components/schemas/TokenControlsView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Token contract not found or not recognized as a fungible token. headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Tokens /v1/{chain}/token/{token}/markets/pools: get: summary: Materialized token DEX pool facts description: |- Partner-tier endpoint for token-contract-first pool facts. Rows are served from `token_market_pool_snapshot`; token-level totals are served from the materialized rollup and are not recomputed on request. The route never performs request-time DEX, RPC, transfer, or Account Calls probes. Partner-tier route backed by materialized serving tables. It is intended for bounded indexed reads and must not run request-time scans or repairs. security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: token in: path required: true schema: type: string - name: limit in: query description: Page size (clamped to 1..100). schema: type: integer format: int32 minimum: 1 maximum: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Token market pool page content: application/json: schema: $ref: "#/components/schemas/TokenMarketPoolPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Token contract not found or not recognized as a fungible token. headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: partner x-mezcal-key-tier: partner tags: - Tokens /v1/{chain}/token/{token}/transfers: get: summary: Paginated token transfers with optional address and block filters security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: token in: path required: true schema: type: string - name: address in: query description: Optional repeated wallet/address filter; matches transfers where either side is in the supplied set. schema: type: array maxItems: 128 items: type: string style: form explode: true - name: from_block in: query description: Optional inclusive lower block bound. schema: type: integer format: int64 minimum: 0 - name: to_block in: query description: Optional inclusive upper block bound. schema: type: integer format: int64 minimum: 0 - name: cursor in: query description: Optional cursor in `block:tx:log:transfer` numeric format. schema: type: string pattern: ^[0-9]+:[0-9]+:[0-9]+:[0-9]+$ - name: limit in: query description: Page size (clamped to 1..100). schema: type: integer format: int32 minimum: 1 maximum: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Token transfer page content: application/json: schema: $ref: "#/components/schemas/TokenTransferPage" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Tokens /v1/{chain}/events: get: summary: Paginated raw events with optional address, topic0, and block filters security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: query description: Optional repeated contract/address filter. schema: type: array maxItems: 128 items: type: string style: form explode: true - name: topic0 in: query description: Optional repeated event-selector filter. schema: type: array maxItems: 128 items: type: string style: form explode: true - name: from_block in: query description: Optional inclusive lower block bound. schema: type: integer format: int64 minimum: 0 - name: to_block in: query description: Optional inclusive upper block bound. schema: type: integer format: int64 minimum: 0 - name: cursor in: query description: Optional cursor in `block:tx:log` numeric format. schema: type: string pattern: ^[0-9]+:[0-9]+:[0-9]+$ - name: limit in: query description: Page size (clamped to 1..100). schema: type: integer format: int32 minimum: 1 maximum: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Global raw event page content: application/json: schema: $ref: "#/components/schemas/GlobalEventPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Reference /v1/{chain}/transfers: get: summary: Paginated normalized transfers with optional address, token, and block filters security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: query description: Optional repeated wallet/address filter; matches transfers where either side is in the supplied set. schema: type: array maxItems: 128 items: type: string style: form explode: true - name: token in: query description: Optional repeated token-address filter. schema: type: array maxItems: 128 items: type: string style: form explode: true - name: from_block in: query description: Optional inclusive lower block bound. schema: type: integer format: int64 minimum: 0 - name: to_block in: query description: Optional inclusive upper block bound. schema: type: integer format: int64 minimum: 0 - name: cursor in: query description: Optional cursor in `block:tx:log:transfer` numeric format. schema: type: string pattern: ^[0-9]+:[0-9]+:[0-9]+:[0-9]+$ - name: limit in: query description: Page size (clamped to 1..100). schema: type: integer format: int32 minimum: 1 maximum: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Global transfer page content: application/json: schema: $ref: "#/components/schemas/GlobalTransferPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Reference /v1/me/api-keys: get: summary: List self-serve API keys for the authenticated workspace description: Returns metadata for the current workspace's self-serve Mezcal API keys. Secrets are never returned by this route. Hosted browser sessions may authenticate this safe read with Better Auth cookies or an explicit bearer session token. security: - SelfServeSession: [] - SelfServeSessionCookie: [] - SelfServeSessionCookieSecure: [] responses: "200": description: Self-serve API key list content: application/json: schema: $ref: "#/components/schemas/SelfServeApiKeyListResponse" "401": $ref: "#/components/responses/UnauthorizedSelfServeSession" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: self-serve x-mezcal-key-tier: session parameters: - $ref: "#/components/parameters/RequestIdHeader" tags: - Account post: summary: Issue or rotate the default self-serve API key for the authenticated workspace description: "Issues a live read-only API key for the current workspace. If an active default key already exists, the old key is revoked and replaced in the same operation. This mutating route requires `Authorization: Bearer ` and rejects cookie-only calls." security: - SelfServeSession: [] responses: "200": description: Issued self-serve API key content: application/json: schema: $ref: "#/components/schemas/SelfServeIssueApiKeyResult" "401": $ref: "#/components/responses/UnauthorizedSelfServeSession" "403": $ref: "#/components/responses/ForbiddenSelfServeMutation" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: self-serve x-mezcal-key-tier: session parameters: - $ref: "#/components/parameters/RequestIdHeader" tags: - Account /v1/me/api-keys/{public_id}: delete: summary: Revoke one self-serve API key for the authenticated workspace description: "Revokes the selected self-serve API key and returns its final metadata snapshot. This mutating route requires `Authorization: Bearer ` and rejects cookie-only calls." security: - SelfServeSession: [] parameters: - name: public_id in: path required: true schema: type: string - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Revoked self-serve API key content: application/json: schema: $ref: "#/components/schemas/SelfServeApiKeyDeleteResponse" "401": $ref: "#/components/responses/UnauthorizedSelfServeSession" "403": $ref: "#/components/responses/ForbiddenSelfServeMutation" "404": description: Self-serve API key not found headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: self-serve x-mezcal-key-tier: session tags: - Account /v1/me/usage: get: summary: Load recent self-serve API usage for the authenticated workspace description: Returns a recent usage window, per-key aggregates, recent requests, and recent failures for the current self-serve workspace. Hosted browser sessions may authenticate this safe read with Better Auth cookies or an explicit bearer session token. security: - SelfServeSession: [] - SelfServeSessionCookie: [] - SelfServeSessionCookieSecure: [] responses: "200": description: Self-serve usage snapshot content: application/json: schema: $ref: "#/components/schemas/SelfServeUsageSnapshot" "401": $ref: "#/components/responses/UnauthorizedSelfServeSession" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: self-serve x-mezcal-key-tier: session parameters: - $ref: "#/components/parameters/RequestIdHeader" tags: - Account /v1/{chain}/search: get: summary: Universal search security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: q in: query description: | Optional prefix query. Missing or empty values return an empty result set. Exact hash/address-style queries resolve first match in this order: transaction hash -> address -> block hash (single category returned). Prefix address matching reads address-activity tables only; addresses that appear exclusively in token-transfer activity remain accessible via `/v1/{chain}/address/{address}` but are not returned by `/search`. schema: type: string - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Search results content: application/json: schema: $ref: "#/components/schemas/SearchView" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-mezcal-audience: public-core x-mezcal-certification: beta x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Search components: securitySchemes: SelfServeSession: type: http scheme: bearer bearerFormat: Better Auth session token description: Session token for authenticated self-serve workspace routes. Hosted browser safe reads can also use Better Auth session cookies, but mutating /v1/me/* routes require an explicit bearer token. SelfServeSessionCookie: type: apiKey in: cookie name: better-auth.session_token description: Better Auth session cookie accepted for hosted same-origin safe reads on /v1/me/*. SelfServeSessionCookieSecure: type: apiKey in: cookie name: __Secure-better-auth.session_token description: Secure Better Auth session cookie accepted for hosted same-origin safe reads on /v1/me/*. MezcalApiKey: type: apiKey in: header name: X-Starkscan-Api-Key description: Starkscan API key for the public read contract. X-Mezcal-Api-Key remains accepted as a legacy alias. parameters: ChainParam: name: chain in: path required: true schema: type: string example: SN_MAIN RequestIdHeader: name: X-Request-Id in: header required: false description: Optional caller-supplied correlation ID echoed back in the response. schema: type: string responses: UnauthorizedText: description: Missing or invalid Mezcal credential. headers: X-Request-Id: $ref: "#/components/headers/RequestId" WWW-Authenticate: $ref: "#/components/headers/WwwAuthenticate" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" UnauthorizedSelfServeSession: description: Missing, invalid, or expired self-serve session. headers: X-Request-Id: $ref: "#/components/headers/RequestId" WWW-Authenticate: $ref: "#/components/headers/WwwAuthenticate" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" RateLimited: description: Rate limit hit for the current route class. headers: X-Request-Id: $ref: "#/components/headers/RequestId" Retry-After: $ref: "#/components/headers/RetryAfter" X-Mezcal-Route-Class: $ref: "#/components/headers/MezcalRouteClass" x-ratelimit-limit: $ref: "#/components/headers/RateLimitLimit" x-ratelimit-remaining: $ref: "#/components/headers/RateLimitRemaining" x-ratelimit-policy: $ref: "#/components/headers/RateLimitPolicy" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" BadRequest: description: Invalid request shape, path parameter, query parameter, or body. headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" ForbiddenText: description: Valid Mezcal credential lacks the required scope. headers: X-Request-Id: $ref: "#/components/headers/RequestId" WWW-Authenticate: $ref: "#/components/headers/WwwAuthenticate" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" ForbiddenSelfServeMutation: description: Cookie-authenticated mutations are not allowed on self-serve routes. headers: X-Request-Id: $ref: "#/components/headers/RequestId" WWW-Authenticate: $ref: "#/components/headers/WwwAuthenticate" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" NotFound: description: The requested route or resource was not found. headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" Conflict: description: The request conflicts with the current resource state. headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" ServiceUnavailable: description: The route is temporarily unavailable. headers: X-Request-Id: $ref: "#/components/headers/RequestId" Retry-After: $ref: "#/components/headers/RetryAfter" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" schemas: ErrorResponse: type: object description: | Machine-readable error envelope. JSON error responses also emit `X-Request-Id` as the canonical correlation header when the request has one; `requestId` mirrors it when available inside the handler. additionalProperties: false required: - code - message - docSlug - requestId properties: code: type: string enum: - invalid_request - unauthorized - forbidden - not_found - conflict - rate_limited - service_unavailable - internal_error - api_error message: type: string docSlug: type: string description: Stable docs slug agents can use for next-step guidance. requestId: type: - string - "null" description: Mirrors `X-Request-Id` when available inside the handler; the response header is canonical. AgentMemoryContract: type: object additionalProperties: true required: - kind - schemaVersion - generatedFor - auth - firstCalls - routeFamilies - workspaceMemory - operatingRules - issueReportContract properties: kind: type: string enum: - mezcal.agent_memory schemaVersion: type: string example: 2026-05-02 generatedFor: type: string enum: - agents auth: type: object additionalProperties: true required: - header - legacyHeader - externalBasePath - defaultChain properties: header: type: string example: X-Starkscan-Api-Key legacyHeader: type: string example: X-Mezcal-Api-Key externalBasePath: type: string example: /api/v1 defaultChain: type: string example: SN_MAIN firstCalls: type: array items: $ref: "#/components/schemas/AgentFirstCall" routeFamilies: type: array items: $ref: "#/components/schemas/AgentRouteFamily" workspaceMemory: $ref: "#/components/schemas/AgentWorkspaceMemoryContract" operatingRules: type: array items: type: string issueReportContract: $ref: "#/components/schemas/AgentIssueReportContract" AgentFirstCall: type: object additionalProperties: true required: - method - path - purpose properties: method: type: string example: GET path: type: string example: /api/v1/meta/capabilities purpose: type: string AgentRouteFamily: type: object additionalProperties: true required: - name - tier - routes - useWhen properties: name: type: string tier: type: string enum: - read - batch routes: type: array items: type: string useWhen: type: string MetaCapabilitiesView: type: object additionalProperties: true required: - kind - schemaVersion - defaultChain - authHeader - legacyAuthHeader - firstCalls - routeFamilies - operatingRules - issueReportContract description: | Authenticated capability view for agents and developers. properties: kind: type: string enum: - mezcal.meta.capabilities schemaVersion: type: string defaultChain: type: string authHeader: type: string example: X-Starkscan-Api-Key legacyAuthHeader: type: string example: X-Mezcal-Api-Key firstCalls: type: array items: $ref: "#/components/schemas/AgentFirstCall" routeFamilies: type: array items: $ref: "#/components/schemas/AgentRouteFamily" operatingRules: type: array items: type: string issueReportContract: $ref: "#/components/schemas/AgentIssueReportContract" MetaChainsView: type: object additionalProperties: true required: - kind - schemaVersion - defaultChain - chains properties: kind: type: string enum: - mezcal.meta.chains schemaVersion: type: string defaultChain: type: string chains: type: array items: type: object additionalProperties: true required: - chainId - statusPath - statusPathTemplate properties: chainId: type: string statusPath: type: string statusPathTemplate: type: string selectionRule: type: string MetaAgentContextView: type: object additionalProperties: true required: - kind - schemaVersion - agentMemory - workspaceMemory - preferredArtifactFormat properties: kind: type: string enum: - mezcal.meta.agent_context schemaVersion: type: string agentMemory: $ref: "#/components/schemas/AgentMemoryContract" workspaceMemory: $ref: "#/components/schemas/AgentWorkspaceMemoryContract" preferredArtifactFormat: type: string example: application/jsonl AgentWorkspaceMemoryContract: type: object additionalProperties: false required: - status - publicWriteApi - serverStoredArtifacts - writeSurface - localWorkspace - handoffContract properties: status: type: string enum: - no_public_write_api publicWriteApi: type: boolean enum: - false serverStoredArtifacts: type: string example: not available in this deployment writeSurface: type: string example: not exposed in this deployment localWorkspace: $ref: "#/components/schemas/AgentLocalWorkspaceContract" handoffContract: $ref: "#/components/schemas/AgentHandoffContract" rules: type: array items: type: string AgentLocalWorkspaceContract: type: object additionalProperties: false required: - status - defaultDirectory - artifactPattern - schemaPath - schemaUrl - guideUrl - validatorCommand - sampleCommand properties: status: type: string enum: - internal_local_only defaultDirectory: type: string example: .codex/handoffs/ artifactPattern: type: string example: .codex/handoffs/{taskId}.jsonl schemaPath: type: string example: docs/maintainers/schemas/agent-handoff-artifact.schema.json schemaUrl: type: string example: /agent-handoff-artifact.schema.json guideUrl: type: string example: /agent-workspace.md validatorCommand: type: string example: python3 scripts/ci/agent-handoff.py validate .codex/handoffs/{taskId}.jsonl sampleCommand: type: string example: python3 scripts/ci/agent-handoff.py sample --task-id --created-by AgentHandoffContract: type: object additionalProperties: false required: - sourceOfTruth - artifactKinds - requiredFields - evidenceRule - formats properties: sourceOfTruth: type: string example: typed JSON/JSONL artifacts, not chat history artifactKinds: type: array items: type: string requiredFields: type: array items: type: string evidenceRule: type: string formats: type: array items: type: string AgentIssueReportContract: type: object additionalProperties: false required: - requiredFields - rule properties: requiredFields: type: array items: type: string example: - route - queryParams - requestBody - responseStatus - responseSnippet - xRequestId rule: type: string HealthResponse: type: object additionalProperties: false required: - ok - databaseOk properties: ok: type: boolean databaseOk: type: boolean ReadyzResponse: type: object additionalProperties: false required: - ready - databaseOk properties: ready: type: boolean databaseOk: type: boolean LivezResponse: type: object additionalProperties: false required: - alive properties: alive: type: boolean ExplorerStatusView: type: object additionalProperties: false required: - chainId - headBlockNumber - headBlockHash - finalizedBlockNumber - latestIndexedBlockNumber - earliestIndexedBlockNumber - indexedBlockSpan - lagBlocks - l1SettlementLatencySeconds properties: chainId: type: string headBlockNumber: type: - integer - "null" format: int64 headBlockHash: type: - string - "null" finalizedBlockNumber: type: - integer - "null" format: int64 latestIndexedBlockNumber: type: - integer - "null" format: int64 earliestIndexedBlockNumber: type: - integer - "null" format: int64 indexedBlockSpan: type: - integer - "null" format: int64 lagBlocks: type: - integer - "null" format: int64 l1SettlementLatencySeconds: type: - integer - "null" format: int64 OAuthProtectedResourceMetadata: type: object additionalProperties: false required: - authorization_servers - resource - bearer_methods_supported - scopes_supported properties: authorization_servers: type: array items: type: string resource: type: string bearer_methods_supported: type: array items: type: string scopes_supported: type: array items: type: string ChainBlockListItem: type: object additionalProperties: false required: - blockNumber - blockHash - parentHash - timestampIso - txCount - finalityStatus properties: blockNumber: type: integer format: int64 blockHash: type: string parentHash: type: string timestampIso: type: string txCount: type: integer format: int64 finalityStatus: type: string ChainBlockListPage: type: object additionalProperties: false required: - items - nextCursor properties: items: type: array items: $ref: "#/components/schemas/ChainBlockListItem" nextCursor: type: - string - "null" ChainTransactionListItem: type: object additionalProperties: false required: - blockNumber - timestampIso - txHash - txIndex - txType - fromAddress - toAddress - executionStatus - finalityStatus properties: blockNumber: type: integer format: int64 timestampIso: type: string txHash: type: string txIndex: type: integer format: int32 txType: type: string fromAddress: type: - string - "null" toAddress: type: - string - "null" executionStatus: type: - string - "null" finalityStatus: type: string ChainTransactionListPage: type: object additionalProperties: false required: - items - nextCursor properties: items: type: array items: $ref: "#/components/schemas/ChainTransactionListItem" nextCursor: type: - string - "null" BlockTransactionView: type: object additionalProperties: false required: - txHash - txIndex - txCursor - fromAddress - toAddress - executionStatus - finalityStatus properties: txHash: type: string txIndex: type: integer format: int32 txCursor: type: string fromAddress: type: - string - "null" toAddress: type: - string - "null" executionStatus: type: - string - "null" finalityStatus: type: - string - "null" BlockView: type: object additionalProperties: false required: - chainId - blockNumber - blockHash - parentHash - timestampIso - txCount - rawObjectKey - transactions properties: chainId: type: string blockNumber: type: integer format: int64 blockHash: type: string parentHash: type: string timestampIso: type: string txCount: type: integer format: int64 rawObjectKey: type: string transactions: type: array maxItems: 200 items: $ref: "#/components/schemas/BlockTransactionView" BlockTransactionPage: type: object additionalProperties: false required: - items - nextCursor properties: items: type: array maxItems: 100 items: $ref: "#/components/schemas/BlockTransactionView" nextCursor: type: - string - "null" ExplorerLiveFeedSnapshot: type: object additionalProperties: false required: - schemaVersion - emittedAtIso - status - blocks properties: schemaVersion: type: integer format: int32 emittedAtIso: type: string status: $ref: "#/components/schemas/ExplorerStatusView" blocks: type: array maxItems: 25 items: $ref: "#/components/schemas/BlockView" TransactionReceiptView: type: object additionalProperties: false required: - executionStatus - finalityStatus - gasUsed - effectiveGasPrice properties: executionStatus: type: - string - "null" finalityStatus: type: - string - "null" gasUsed: type: - string - "null" effectiveGasPrice: type: - string - "null" TransactionLogView: type: object additionalProperties: false required: - logIndex - address - topic0 - topic1 - topic2 - topic3 - data properties: logIndex: type: integer format: int32 address: type: string topic0: type: - string - "null" topic1: type: - string - "null" topic2: type: - string - "null" topic3: type: - string - "null" data: type: array maxItems: 1024 items: type: string TransactionTransferView: type: object additionalProperties: false required: - logIndex - transferIndex - tokenAddress - fromAddress - toAddress - amount - tokenId - standard properties: logIndex: type: integer format: int32 transferIndex: type: integer format: int32 tokenAddress: type: string fromAddress: type: - string - "null" toAddress: type: - string - "null" amount: type: - string - "null" tokenId: type: - string - "null" standard: type: string BridgeIntentKind: type: string enum: - deposit - withdraw - bridge_unknown BridgeIntentConfidence: type: string description: | Confidence for emitted bridge intents. Low-confidence candidates are intentionally omitted from `bridgeIntent`. enum: - high - medium BridgeIntentView: type: object additionalProperties: false required: - kind - protocol - confidence - reasons properties: kind: $ref: "#/components/schemas/BridgeIntentKind" protocol: type: - string - "null" confidence: $ref: "#/components/schemas/BridgeIntentConfidence" reasons: type: array maxItems: 32 items: type: string TransactionPreviewLogView: type: object additionalProperties: false required: - logIndex - address - topic0 properties: logIndex: type: integer format: int32 address: type: string topic0: type: - string - "null" TransactionPreviewView: type: object additionalProperties: false required: - chainId - blockNumber - txIndex - txHash - txCursor - fromAddress - toAddress - executionStatus - finalityStatus - txType - transferCount - tokenTransfersTruncated - tokenTransfers properties: chainId: type: string blockNumber: type: integer format: int64 txIndex: type: integer format: int32 txHash: type: string txCursor: type: string fromAddress: type: - string - "null" toAddress: type: - string - "null" executionStatus: type: - string - "null" finalityStatus: type: - string - "null" txType: type: - string - "null" transferCount: type: integer format: int64 tokenTransfersTruncated: type: boolean tokenTransfers: type: array maxItems: 4096 items: $ref: "#/components/schemas/TransactionTransferView" hasBurnToZero: type: boolean hasMintFromZero: type: boolean bridgeSignalContracts: type: array maxItems: 256 items: type: string bridgeIntent: oneOf: - $ref: "#/components/schemas/BridgeIntentView" - type: "null" logCount: type: integer format: int64 logsTruncated: type: boolean logs: type: array maxItems: 4096 items: $ref: "#/components/schemas/TransactionPreviewLogView" TransactionPreviewBatchView: type: object additionalProperties: false required: - items properties: items: type: array maxItems: 128 items: $ref: "#/components/schemas/TransactionPreviewView" TransactionPreviewBatchRequest: type: object additionalProperties: false required: - hashes properties: hashes: type: array minItems: 1 maxItems: 128 items: type: string includeLogs: type: - boolean - "null" description: | Include bounded preview logs for each transaction. Defaults to `false` when omitted. includeLogCounts: type: - boolean - "null" description: | Include exact log counts even when logs are not requested. When omitted, defaults to the same value as `includeLogs`. includeBridgeSignals: type: - boolean - "null" default: true description: | Include bridge transfer signal detection (`hasMintFromZero`, `hasBurnToZero`, `bridgeSignalContracts`, `bridgeIntent`). Defaults to `true` when omitted. logLimitPerTx: type: - integer - "null" format: int32 default: 64 minimum: 1 maximum: 256 description: | Maximum number of logs returned per transaction when `includeLogs` is enabled. Defaults to `64` when omitted. TransactionDetailView: type: object additionalProperties: false required: - chainId - blockNumber - txIndex - txHash - txCursor - fromAddress - toAddress - executionStatus - finalityStatus - txType - rawObjectKey - calldata - receipt - logsTruncated - logs - tokenTransfers - messages - messagesCoverage - bridgeIntent properties: chainId: type: string blockNumber: type: integer format: int64 timestampIso: type: - string - "null" format: date-time txIndex: type: integer format: int32 txHash: type: string txCursor: type: string fromAddress: type: - string - "null" toAddress: type: - string - "null" executionStatus: type: - string - "null" finalityStatus: type: - string - "null" txType: type: - string - "null" rawObjectKey: type: string receipt: oneOf: - $ref: "#/components/schemas/TransactionReceiptView" - type: "null" logsTruncated: type: boolean logs: type: array maxItems: 512 items: $ref: "#/components/schemas/TransactionLogView" calldata: type: array maxItems: 1024 items: type: string tokenTransfers: type: array maxItems: 4096 items: $ref: "#/components/schemas/TransactionTransferView" messages: type: array maxItems: 32 items: $ref: "#/components/schemas/MessageItem" messagesCoverage: $ref: "#/components/schemas/MessageCoverageView" bridgeIntent: oneOf: - $ref: "#/components/schemas/BridgeIntentView" - type: "null" AddressSummaryView: type: object additionalProperties: false required: - address - totalActivityCount - latestActivityBlock properties: address: type: string totalActivityCount: type: integer format: int64 latestActivityBlock: type: - integer - "null" format: int64 activityCountExact: type: - boolean - "null" classHash: type: - string - "null" description: Starknet contract class hash (0x-prefixed felt hex), null when unavailable. pattern: ^0x[0-9a-fA-F]{1,64}$ isAccount: type: - boolean - "null" description: True if the class behaves as an account contract, null when unknown. createdOnIso: type: - string - "null" deployedAtTxHash: type: - string - "null" deployedByAddress: type: - string - "null" AddressSummaryBatchRequest: type: object additionalProperties: false required: - addresses properties: addresses: type: array minItems: 1 maxItems: 128 items: type: string AddressSummaryBatchView: type: object additionalProperties: false required: - items properties: items: type: array maxItems: 128 items: $ref: "#/components/schemas/AddressSummaryView" ContractVerificationView: type: object additionalProperties: false required: - chainId - contractAddress - classHash - sourceRef - language - compilerVersion - verificationStatus - verificationError - requestedAtIso - verifiedAtIso - updatedAtIso - metadata properties: chainId: type: string contractAddress: type: string classHash: type: - string - "null" sourceRef: type: - string - "null" language: type: - string - "null" compilerVersion: type: - string - "null" verificationStatus: type: string enum: - pending - verified - failed verificationError: type: - string - "null" requestedAtIso: type: string verifiedAtIso: type: - string - "null" updatedAtIso: type: string metadata: type: object ContractVerificationUpsertRequest: type: object additionalProperties: false required: - verificationStatus properties: classHash: type: - string - "null" sourceRef: type: - string - "null" language: type: - string - "null" compilerVersion: type: - string - "null" verificationStatus: type: string enum: - pending - verified - failed verificationError: type: - string - "null" requestedAtIso: type: - string - "null" verifiedAtIso: type: - string - "null" metadata: type: object ContractEntrypointItem: type: object additionalProperties: false required: - selector - name - stateMutability properties: selector: type: string name: type: - string - "null" stateMutability: type: - string - "null" ContractEntrypointsView: type: object additionalProperties: false required: - chainId - contractAddress - external - constructor - l1Handler properties: chainId: type: string contractAddress: type: string external: type: array maxItems: 256 items: $ref: "#/components/schemas/ContractEntrypointItem" constructor: type: array maxItems: 16 items: $ref: "#/components/schemas/ContractEntrypointItem" l1Handler: type: array maxItems: 16 items: $ref: "#/components/schemas/ContractEntrypointItem" ContractEventItem: type: object additionalProperties: false required: - blockNumber - timestampIso - txHash - txIndex - logIndex - address - topic0 - topic1 - topic2 - topic3 - data properties: blockNumber: type: integer format: int64 timestampIso: type: string format: date-time txHash: type: string txIndex: type: integer format: int32 logIndex: type: integer format: int32 address: type: string topic0: type: - string - "null" topic1: type: - string - "null" topic2: type: - string - "null" topic3: type: - string - "null" data: type: array maxItems: 1024 items: type: string ContractEventPage: type: object additionalProperties: false required: - items - nextCursor properties: items: type: array maxItems: 100 items: $ref: "#/components/schemas/ContractEventItem" nextCursor: type: - string - "null" pattern: ^[0-9]+:[0-9]+:[0-9]+$ ContractAdvancedCoverageView: type: object additionalProperties: false required: - status - source - reasonCode - message properties: status: type: string enum: - exact - partial - unavailable source: type: string enum: - trace_facts - l2_bridge_signals - bridge_adapter_events - bridge_message_facts reasonCode: type: string enum: - indexed_trace_facts - no_matching_trace_rows - trace_tables_unavailable - trace_extraction_truncated - trace_projection_stale - indexed_bridge_pairing_facts - l1_pairing_not_indexed - bridge_message_facts_unavailable - adapter_pairing_facts_unavailable - query_timeout message: type: string latestIndexedBlockNumber: type: - integer - "null" format: int64 chainHeadBlockNumber: type: - integer - "null" format: int64 lagBlocks: type: - integer - "null" format: int64 ContractAccountCallItem: type: object additionalProperties: false required: - id - blockNumber - timestampIso - txIndex - callIndex - tracePath - txHash - methodName - entryPointSelector - senderAddress - callerAddress - calleeAddress - executionStatus - finalityStatus - sourceTier - extractionTruncated properties: id: type: string blockNumber: type: integer format: int64 timestampIso: type: - string - "null" format: date-time txIndex: type: integer format: int32 callIndex: type: integer format: int32 tracePath: type: - string - "null" txHash: type: string methodName: type: - string - "null" entryPointSelector: type: - string - "null" senderAddress: type: - string - "null" callerAddress: type: - string - "null" calleeAddress: type: string executionStatus: type: - string - "null" finalityStatus: type: - string - "null" sourceTier: type: string enum: - head - finalized extractionTruncated: type: boolean ContractAccountCallPage: type: object additionalProperties: false required: - chainId - contractAddress - items - nextCursor - coverage properties: chainId: type: string contractAddress: type: string items: type: array maxItems: 100 items: $ref: "#/components/schemas/ContractAccountCallItem" nextCursor: type: - string - "null" pattern: ^[0-9]+:[0-9]+:[0-9]+$ coverage: $ref: "#/components/schemas/ContractAdvancedCoverageView" ContractBridgeTransactionItem: type: object additionalProperties: false required: - id - blockNumber - timestampIso - txIndex - logIndex - transferIndex - txHash - status - direction - messageHash - l1Hash - l2Hash - l1ContractAddress - l2ContractAddress - tokenAddress - tokenSymbol - tokenDecimals - amountRaw - fromAddress - toAddress - pairingConfidence - sourceTier properties: id: type: string blockNumber: type: integer format: int64 timestampIso: type: - string - "null" format: date-time txIndex: type: integer format: int32 logIndex: type: integer format: int32 transferIndex: type: integer format: int32 txHash: type: string status: type: string direction: type: - string - "null" enum: - inbound - outbound - null messageHash: type: - string - "null" l1Hash: type: - string - "null" l2Hash: type: - string - "null" l1ContractAddress: type: - string - "null" l2ContractAddress: type: - string - "null" tokenAddress: type: - string - "null" tokenSymbol: type: - string - "null" tokenDecimals: type: - integer - "null" format: int32 amountRaw: type: - string - "null" fromAddress: type: - string - "null" toAddress: type: - string - "null" pairingConfidence: type: string enum: - message_pairing_fact - adapter_pairing_fact - unpaired_l2_only sourceTier: type: string enum: - head - finalized ContractBridgeTransactionPage: type: object additionalProperties: false required: - chainId - contractAddress - items - nextCursor - coverage properties: chainId: type: string contractAddress: type: string items: type: array maxItems: 100 items: $ref: "#/components/schemas/ContractBridgeTransactionItem" nextCursor: type: - string - "null" pattern: ^[0-9]+:[0-9]+:[0-9]+(:[0-9]+)?$ coverage: $ref: "#/components/schemas/ContractAdvancedCoverageView" MessageCoverageView: type: object additionalProperties: false required: - status - source - reasonCode - message properties: status: type: string enum: - exact - partial - unavailable source: type: string enum: - starknet_protocol_messages reasonCode: type: string enum: - indexed_protocol_message_facts - no_matching_message_rows - message_not_found - message_detail_page_exhausted - message_facts_unavailable - message_detail_truncated - transaction_messages_truncated - query_timeout message: type: string MessageItem: type: object additionalProperties: false required: - id - blockNumber - timestampIso - txIndex - logIndex - messageHash - direction - fromAddress - toAddress - txHash - l1Hash - l2Hash - l1BlockNumber - l1Fee - l1ContractAddress - l2ContractAddress - bridgeContractAddress - status - l1SentCount - l2SentCount - l1ConsumedCount - pendingCount - nonce - selector - payload - payloadTruncated - sourceTier properties: id: type: string blockNumber: type: integer format: int64 timestampIso: type: - string - "null" format: date-time txIndex: type: integer format: int32 logIndex: type: integer format: int32 messageHash: type: string direction: type: string enum: - l1_to_l2 - l2_to_l1 - unknown fromAddress: type: - string - "null" toAddress: type: - string - "null" txHash: type: string l1Hash: type: - string - "null" l2Hash: type: - string - "null" l1BlockNumber: type: - integer - "null" format: int64 minimum: 0 description: | Latest indexed canonical Ethereum block associated with this message hash. For L1-to-L2 messages where l1SentCount > 1, this is the latest indexed L1 send block. Null when the relevant L1 origin or consumption fact has not been indexed. l1Fee: type: - string - "null" pattern: ^0[xX][0-9a-fA-F]{1,64}$ description: | Canonical StarknetCore LogMessageToL2 fee for L1-to-L2 origins, encoded as a hex quantity when indexed. When l1SentCount > 1, this is the fee from the latest indexed L1 send, the same send reflected by l1BlockNumber. Null for L2-to-L1 messages or when no L1 origin has been indexed. l1ContractAddress: type: - string - "null" l2ContractAddress: type: - string - "null" bridgeContractAddress: type: - string - "null" status: type: string l1SentCount: type: integer format: int64 minimum: 0 description: Count of indexed canonical StarknetCore L1 origin logs sharing this L1-to-L2 message hash. l2SentCount: type: integer format: int64 minimum: 0 description: Count of indexed canonical L2 emissions sharing this message hash. l1ConsumedCount: type: integer format: int64 minimum: 0 description: Count of indexed canonical StarknetCore L1 consumption logs sharing this message hash. pendingCount: type: integer format: int64 minimum: 0 description: "Non-negative pending lifecycle count for this message hash: L1 origins minus L2 consumptions for L1-to-L2, or L2 emissions minus canonical L1 consumptions for L2-to-L1." nonce: type: - string - "null" selector: type: - string - "null" payload: type: array maxItems: 1024 items: type: string payloadTruncated: type: boolean sourceTier: type: string enum: - head - finalized MessagePage: type: object additionalProperties: false required: - chainId - contractAddress - items - nextCursor - coverage properties: chainId: type: string contractAddress: type: - string - "null" items: type: array maxItems: 100 items: $ref: "#/components/schemas/MessageItem" nextCursor: type: - string - "null" pattern: ^m1:[0-9]+:[0-9]+:[0-9]+:0[xX][0-9a-fA-F]+:0[xX][0-9a-fA-F]+:(l1_to_l2|l2_to_l1):(head|finalized)$ coverage: $ref: "#/components/schemas/MessageCoverageView" MessageDetailView: type: object additionalProperties: false required: - chainId - messageHash - items - nextCursor - coverage properties: chainId: type: string messageHash: type: string items: type: array maxItems: 100 items: $ref: "#/components/schemas/MessageItem" nextCursor: type: - string - "null" pattern: ^m1:[0-9]+:[0-9]+:[0-9]+:0[xX][0-9a-fA-F]+:0[xX][0-9a-fA-F]+:(l1_to_l2|l2_to_l1):(head|finalized)$ coverage: $ref: "#/components/schemas/MessageCoverageView" ContractReadResultView: type: object additionalProperties: false required: - chainId - contractAddress - selector - blockTag - result properties: chainId: type: string contractAddress: type: string selector: type: string blockTag: type: string enum: - latest - pending result: type: array maxItems: 1024 items: type: string ContractWritePayloadRequest: type: object additionalProperties: false required: - selector properties: selector: type: string calldata: type: array default: [] maxItems: 1024 items: type: string ContractWritePayloadView: type: object additionalProperties: false required: - chainId - contractAddress - selector - calldata - call properties: chainId: type: string contractAddress: type: string selector: type: string calldata: type: array maxItems: 1024 items: type: string call: type: object ContractTransactionTraceView: type: object additionalProperties: false required: - chainId - txHash - trace properties: chainId: type: string txHash: type: string trace: type: object AddressActivityItem: type: object additionalProperties: false required: - blockNumber - timestampIso - txIndex - logIndex - transferIndex - txHash - txCursor - kind - counterparty - tokenAddress - amount - tokenId properties: blockNumber: type: integer format: int64 timestampIso: type: - string - "null" format: date-time txIndex: type: integer format: int32 logIndex: type: - integer - "null" format: int32 transferIndex: type: - integer - "null" format: int32 txHash: type: string txCursor: type: string kind: type: string counterparty: type: - string - "null" tokenAddress: type: - string - "null" amount: type: - string - "null" tokenId: type: - string - "null" AddressActivityPage: type: object additionalProperties: false required: - items - nextCursor properties: items: type: array maxItems: 100 items: $ref: "#/components/schemas/AddressActivityItem" nextCursor: type: - string - "null" AddressTransactionListItem: type: object additionalProperties: false required: - blockNumber - timestampIso - txIndex - txHash - kinds - counterparty - txType - executionStatus - finalityStatus - fromAddress - toAddress - primaryMethod - callCount - methodsDiffer - transferCount - topTransferTokenAddress - topTransferAmount - topTransferStandard properties: blockNumber: type: integer format: int64 timestampIso: type: - string - "null" format: date-time txIndex: type: integer format: int32 txHash: type: string kinds: type: array maxItems: 16 items: type: string counterparty: type: - string - "null" txType: type: - string - "null" executionStatus: type: - string - "null" finalityStatus: type: - string - "null" fromAddress: type: - string - "null" toAddress: type: - string - "null" primaryMethod: type: - string - "null" callCount: type: - integer - "null" format: int32 methodsDiffer: type: - boolean - "null" transferCount: type: - integer - "null" format: int32 topTransferTokenAddress: type: - string - "null" topTransferAmount: type: - string - "null" topTransferStandard: type: - string - "null" AddressTransactionPage: type: object additionalProperties: false required: - items - nextCursor properties: items: type: array maxItems: 100 items: $ref: "#/components/schemas/AddressTransactionListItem" nextCursor: type: - string - "null" AddressTokenHoldingItemView: type: object additionalProperties: false required: - tokenAddress - normalizedTokenAddress - indexedBalanceRaw - symbol - name - decimals properties: tokenAddress: type: string description: Token contract address as stored by the indexed balance source. normalizedTokenAddress: type: string description: Lowercase compact `0x` token address for stable agent comparisons. indexedBalanceRaw: type: string description: Decimal (base-10) indexed balance string. symbol: type: - string - "null" description: Token symbol from trusted token-metadata data (token metadata indexes) or from known safe defaults when available. name: type: - string - "null" description: Token name from trusted token-metadata data (token metadata indexes) or from known safe defaults when available. decimals: type: - integer - "null" format: int32 description: Token decimals from trusted token-metadata data (token metadata indexes) or from known safe defaults when available. TokenHoldingsCompletenessReasonCode: type: string enum: - complete - indexLag - boundedComputation - responseCap - metadataPending - degradedFallback - unknown description: | `complete` means the holdings snapshot is complete enough for portfolio parity checks. Other values are useful evidence but not exact portfolio ground truth. `lagBlocks` is populated when incompleteness can be attributed to indexed-source lag. AddressTokenHoldingsCompletenessView: type: object additionalProperties: false required: - exact - truncated - complete - reasonCode - reason - lagBlocks - capped - cap properties: exact: type: boolean description: Mirrors the top-level `exact` field. truncated: type: boolean description: Mirrors the top-level `truncated` field. complete: type: boolean description: | True only when the response is exact, not truncated, and `reasonCode=complete`. reasonCode: $ref: "#/components/schemas/TokenHoldingsCompletenessReasonCode" reason: type: string description: Human-readable explanation for the current completeness state. lagBlocks: type: - integer - "null" format: int64 description: Indexed lag in blocks when known. Null means the route cannot attribute lag for this response. capped: type: boolean description: True when a response cap affected the result. cap: type: - integer - "null" format: int32 description: Effective response cap when capped, otherwise null. AddressTokenHoldingsView: type: object additionalProperties: false required: - chainId - ownerAddress - items - exact - truncated - completeness properties: chainId: type: string ownerAddress: type: string items: description: | Holdings are capped at 256 items. When `truncated` is true, older or lower-priority holdings were omitted from this response. type: array maxItems: 256 items: $ref: "#/components/schemas/AddressTokenHoldingItemView" exact: description: | Indexed portfolio-completeness flag. This is not the same as a fresh on-chain `balanceOf` read. Treat holdings as exact only when this is true, `truncated=false`, and `completeness.reasonCode=complete`. type: boolean truncated: description: True when the holdings list hit the 256-item safety cap. type: boolean completeness: $ref: "#/components/schemas/AddressTokenHoldingsCompletenessView" AddressPortfolioLiveRequest: type: object additionalProperties: false required: - tokenAddresses properties: tokenAddresses: type: array minItems: 1 maxItems: 16 items: type: string blockTag: oneOf: - type: string enum: - latest - pending - type: "null" PortfolioLiveBalanceStatus: type: string enum: - ok - unsupported - timeout - error PortfolioLiveBalanceItemView: type: object additionalProperties: false required: - tokenAddress - balanceRaw - status properties: tokenAddress: type: string balanceRaw: type: - string - "null" status: $ref: "#/components/schemas/PortfolioLiveBalanceStatus" AddressPortfolioLiveView: type: object additionalProperties: false required: - chainId - ownerAddress - blockTag - items - failedCount - partial properties: chainId: type: string ownerAddress: type: string blockTag: type: string items: type: array maxItems: 16 items: $ref: "#/components/schemas/PortfolioLiveBalanceItemView" failedCount: type: integer format: int64 partial: type: boolean ContractSnapshotView: type: object additionalProperties: false required: - chainId - address - summary - activityPage - transactionsPage - tokenHoldings - summaryCompleteness - activityCompleteness - holdingsCompleteness properties: chainId: type: string address: type: string summary: $ref: "#/components/schemas/AddressSummaryView" activityPage: $ref: "#/components/schemas/AddressActivityPage" transactionsPage: $ref: "#/components/schemas/AddressTransactionPage" tokenHoldings: $ref: "#/components/schemas/AddressTokenHoldingsView" summaryCompleteness: type: boolean activityCompleteness: type: boolean holdingsCompleteness: type: boolean TokenSummaryView: type: object additionalProperties: false required: - chainId - tokenAddress - symbol - name - decimals - standard - metadataUpdatedAtIso - summaryVersion - summaryVersionUpdatedAtIso - summaryCacheStatus - summaryCacheUpdatedAtIso - transferCount - distinctFromCount - distinctToCount - latestTransferBlock - totalSupplyRaw - totalSupplySource - totalSupplyBlockNumber - totalSupplyUpdatedAtIso properties: chainId: type: string tokenAddress: type: string symbol: type: - string - "null" name: type: - string - "null" decimals: type: - integer - "null" format: int32 standard: type: string metadataUpdatedAtIso: type: - string - "null" format: date-time summaryVersion: type: integer format: int64 summaryVersionUpdatedAtIso: type: - string - "null" format: date-time summaryCacheStatus: type: string enum: - current - stale - metadata_only - computed summaryCacheUpdatedAtIso: type: - string - "null" format: date-time transferCount: type: integer format: int64 distinctFromCount: type: integer format: int64 distinctToCount: type: integer format: int64 latestTransferBlock: type: - integer - "null" format: int64 totalSupplyRaw: type: - string - "null" description: Decimal string from the row-backed token_supply_snapshot read model when available. totalSupplySource: type: - string - "null" description: Source label for the row-backed total supply snapshot. totalSupplyBlockNumber: type: - integer - "null" format: int64 description: Block number associated with the total supply snapshot when available. totalSupplyUpdatedAtIso: type: - string - "null" format: date-time description: Timestamp when the total supply snapshot row was last updated. allOf: - oneOf: - required: - totalSupplyRaw - totalSupplySource - totalSupplyBlockNumber - totalSupplyUpdatedAtIso properties: totalSupplyRaw: type: string totalSupplySource: type: string totalSupplyBlockNumber: type: integer format: int64 totalSupplyUpdatedAtIso: type: string format: date-time - required: - totalSupplyRaw - totalSupplySource - totalSupplyBlockNumber - totalSupplyUpdatedAtIso properties: totalSupplyRaw: type: "null" totalSupplySource: type: "null" totalSupplyBlockNumber: type: "null" totalSupplyUpdatedAtIso: type: "null" TokenBalanceOfView: type: object additionalProperties: false required: - chainId - tokenAddress - ownerAddress - blockTag - balanceRaw properties: chainId: type: string tokenAddress: type: string ownerAddress: type: string blockTag: type: string enum: - latest - pending balanceRaw: type: string description: Decimal (base-10) string representation of the U256 balanceOf result. TokenTotalSupplyView: type: object additionalProperties: false required: - chainId - tokenAddress - blockTag - totalSupplyRaw properties: chainId: type: string tokenAddress: type: string blockTag: type: string enum: - latest - pending totalSupplyRaw: type: string description: Decimal (base-10) string representation of the U256 totalSupply result. TokenHolderItem: type: object additionalProperties: false required: - rank - address - balanceRaw - lastUpdatedBlock - lastUpdatedTimestampIso properties: rank: type: integer format: int64 description: One-based rank by descending indexed balance, then address ascending. address: type: string balanceRaw: type: string description: Decimal (base-10) indexed balance string. lastUpdatedBlock: type: integer format: int64 lastUpdatedTimestampIso: type: - string - "null" format: date-time TokenHolderSnapshot: type: object additionalProperties: false required: - asOfBlock - source - freshness properties: asOfBlock: type: - integer - "null" format: int64 source: type: string enum: - materialized_fungible_balances freshness: type: string enum: - head_plus_finalized - analytics_snapshot TokenHolderCompleteness: type: object additionalProperties: false required: - exact - truncated - reasonCode properties: exact: type: boolean truncated: type: boolean reasonCode: type: string enum: - materialized_snapshot TokenHolderLimits: type: object additionalProperties: false required: - maxPageSize - tier properties: maxPageSize: type: integer format: int64 maximum: 100 tier: type: string enum: - partner TokenHolderPage: type: object additionalProperties: false required: - chainId - tokenAddress - snapshot - holderCount - items - nextCursor - completeness - limits properties: chainId: type: string tokenAddress: type: string snapshot: $ref: "#/components/schemas/TokenHolderSnapshot" holderCount: type: integer format: int64 items: type: array maxItems: 100 items: $ref: "#/components/schemas/TokenHolderItem" nextCursor: type: - string - "null" completeness: $ref: "#/components/schemas/TokenHolderCompleteness" limits: $ref: "#/components/schemas/TokenHolderLimits" TokenControlFact: type: object additionalProperties: false required: - status - actor properties: status: type: string enum: - fixed - mintable - minter_detected - pausable - freezable - blocklist_detected - not_detected - admin_detected - renounced - proxy_admin_detected - immutable_class - unknown actor: type: - string - "null" description: Indexed actor address when the status has a proven controlling actor. TokenSupplyControlFact: allOf: - $ref: "#/components/schemas/TokenControlFact" - type: object properties: status: type: string enum: - fixed - mintable - minter_detected - unknown TokenTransferControlFact: allOf: - $ref: "#/components/schemas/TokenControlFact" - type: object properties: status: type: string enum: - pausable - freezable - blocklist_detected - not_detected - unknown TokenMetadataAdminControlFact: allOf: - $ref: "#/components/schemas/TokenControlFact" - type: object properties: status: type: string enum: - admin_detected - renounced - unknown TokenUpgradeControlFact: allOf: - $ref: "#/components/schemas/TokenControlFact" - type: object properties: status: type: string enum: - proxy_admin_detected - immutable_class - unknown TokenControlEvidenceItem: type: object additionalProperties: true required: - kind properties: kind: type: string description: Evidence record kind, for example cached selector read, ABI scan, or operator proof. source: type: - string - "null" contractAddress: type: - string - "null" selector: type: - string - "null" txHash: type: - string - "null" blockNumber: type: - integer - "null" format: int64 minimum: 0 block: type: - integer - "null" format: int64 minimum: 0 actor: type: - string - "null" status: type: - string - "null" note: type: - string - "null" TokenControlsSnapshot: type: object additionalProperties: false required: - supplyControl - transferControl - metadataAdmin - upgradeControl - evidence - asOfBlock - source - indexedAtIso properties: supplyControl: $ref: "#/components/schemas/TokenSupplyControlFact" transferControl: $ref: "#/components/schemas/TokenTransferControlFact" metadataAdmin: $ref: "#/components/schemas/TokenMetadataAdminControlFact" upgradeControl: $ref: "#/components/schemas/TokenUpgradeControlFact" evidence: type: array description: Compact provenance records collected outside the request path. items: $ref: "#/components/schemas/TokenControlEvidenceItem" asOfBlock: type: integer format: int64 minimum: 0 source: type: string indexedAtIso: type: string format: date-time TokenControlsView: type: object additionalProperties: false required: - chainId - tokenAddress - indexed - reasonCode - snapshot properties: chainId: type: string tokenAddress: type: string indexed: type: boolean reasonCode: type: string enum: - materialized_controls_snapshot - controls_snapshot_missing snapshot: oneOf: - $ref: "#/components/schemas/TokenControlsSnapshot" - type: "null" TokenMarketPoolItem: type: object additionalProperties: false required: - marketId - marketKind - poolKey - displayName - protocolSlug - protocolName - poolType - dex - poolAddress - pairedTokenAddress - pairedTokenSymbol - feeBps - priceUsd - tvlUsd - volume24hUsd - volume24hPrevUsd - volume24hChangeBps - trades24h - traders24h - lastTradeBlock - snapshotBlock - source - updatedAtIso properties: marketId: type: string description: Stable market identity. For singleton protocols this can identify a market inside the same pool contract. marketKind: type: string enum: - pool_contract - singleton_pool - orderbook poolKey: type: - string - "null" description: Protocol-native pool or market key when distinct from the contract address. displayName: type: - string - "null" description: Human label for the market when materialized offline. protocolSlug: type: - string - "null" protocolName: type: string poolType: type: - string - "null" enum: - cl - cpmm - stable - orderbook - unknown - null dex: type: string description: Legacy DEX label retained for compatibility; prefer protocolName/protocolSlug for new clients. poolAddress: type: string pairedTokenAddress: type: - string - "null" pairedTokenSymbol: type: - string - "null" feeBps: type: - integer - "null" format: int32 minimum: 0 priceUsd: type: - string - "null" description: Decimal USD price string from the materialized snapshot. tvlUsd: type: - string - "null" description: Decimal USD TVL string from the materialized snapshot. pattern: ^[0-9]+(\.[0-9]+)?$ volume24hUsd: type: - string - "null" description: Decimal USD 24h volume string from the materialized snapshot. pattern: ^[0-9]+(\.[0-9]+)?$ volume24hPrevUsd: type: - string - "null" description: Decimal USD previous-window 24h volume used for delta display. volume24hChangeBps: type: - integer - "null" format: int32 description: Signed basis-point change from previous 24h volume to current 24h volume. trades24h: type: - integer - "null" format: int64 minimum: 0 traders24h: type: - integer - "null" format: int64 minimum: 0 lastTradeBlock: type: - integer - "null" format: int64 minimum: 0 snapshotBlock: type: - integer - "null" format: int64 minimum: 0 source: type: string updatedAtIso: type: string format: date-time TokenMarketPoolCoverage: type: object additionalProperties: false required: - exact - reasonCode properties: exact: type: boolean reasonCode: type: string enum: - materialized_pool_snapshot - pool_snapshot_missing - pool_rollup_missing TokenMarketPoolLimits: type: object additionalProperties: false required: - maxPageSize - tier properties: maxPageSize: type: integer format: int64 maximum: 100 tier: type: string enum: - partner TokenMarketPoolPage: type: object additionalProperties: false required: - chainId - tokenAddress - totalPairs - totalTvlUsd - totalVolume24hUsd - items - coverage - limits properties: chainId: type: string tokenAddress: type: string totalPairs: type: - integer - "null" format: int64 minimum: 0 totalTvlUsd: type: - string - "null" description: Indexed total TVL from the materialized token market pool rollup for this token, or null when that rollup value is not materialized. totalVolume24hUsd: type: - string - "null" description: Indexed total 24h volume from the materialized token market pool rollup for this token, or null when that rollup window is not materialized. items: type: array maxItems: 100 items: $ref: "#/components/schemas/TokenMarketPoolItem" coverage: $ref: "#/components/schemas/TokenMarketPoolCoverage" limits: $ref: "#/components/schemas/TokenMarketPoolLimits" TokenHolderTierDistributionItem: type: object additionalProperties: false required: - tier - minShareBps - holderCount - shareBps properties: tier: type: string minShareBps: type: integer format: int64 holderCount: type: integer format: int64 shareBps: type: integer format: int64 TokenHolderThresholdCountItem: type: object additionalProperties: false required: - label - thresholdBps - holderCount properties: label: type: string thresholdBps: type: integer format: int64 holderCount: type: integer format: int64 TokenHolderAnalyticsMetrics: type: object additionalProperties: false required: - holderBalanceTotalRaw - top5BalanceRaw - top10BalanceRaw - top100BalanceRaw - top5ShareBps - top10ShareBps - top100ShareBps - whaleCount - whaleShareBps - giniScorePpm - nakamoto50Count - holdersAbove1Percent - tierDistribution - thresholdCounts properties: holderBalanceTotalRaw: type: string top5BalanceRaw: type: string top10BalanceRaw: type: string top100BalanceRaw: type: string top5ShareBps: type: integer format: int64 top10ShareBps: type: integer format: int64 top100ShareBps: type: integer format: int64 whaleCount: type: integer format: int64 whaleShareBps: type: integer format: int64 giniScorePpm: type: integer format: int64 nakamoto50Count: type: - integer - "null" format: int64 holdersAbove1Percent: type: integer format: int64 tierDistribution: type: array maxItems: 4 description: Fixed four-bucket holder concentration distribution. items: $ref: "#/components/schemas/TokenHolderTierDistributionItem" thresholdCounts: type: array maxItems: 3 description: Fixed three-threshold holder counts for >=1%, >=0.1%, and >=0.01%. items: $ref: "#/components/schemas/TokenHolderThresholdCountItem" TokenHolderAnalyticsSnapshot: type: object additionalProperties: false required: - chainId - tokenAddress - snapshot - holderCount - computedAt - metrics - completeness properties: chainId: type: string tokenAddress: type: string snapshot: $ref: "#/components/schemas/TokenHolderSnapshot" holderCount: type: integer format: int64 computedAt: type: - string - "null" format: date-time metrics: oneOf: - $ref: "#/components/schemas/TokenHolderAnalyticsMetrics" - type: "null" completeness: $ref: "#/components/schemas/TokenHolderCompleteness" SelfServeApiRateLimitPolicySummary: type: object additionalProperties: false required: - policyKey - policyDisplayName - lightPerMinute - heavyPerMinute - burst - maxActiveKeys properties: policyKey: type: string policyDisplayName: type: string lightPerMinute: type: integer format: int64 heavyPerMinute: type: integer format: int64 burst: type: integer format: int64 maxActiveKeys: type: integer format: int64 SelfServeApiKeySummary: type: object additionalProperties: false required: - publicId - label - environment - scopes - status - secretHint - maskedKey - rateLimitPolicy - createdAt - lastUsedAt - expiresAt - revokedAt properties: publicId: type: string label: type: string environment: type: string enum: - test - live scopes: type: array maxItems: 2 uniqueItems: true items: type: string enum: - read - batch status: type: string enum: - active - revoked secretHint: type: string maskedKey: type: string rateLimitPolicy: $ref: "#/components/schemas/SelfServeApiRateLimitPolicySummary" createdAt: type: string format: date-time lastUsedAt: type: - string - "null" format: date-time expiresAt: type: - string - "null" format: date-time revokedAt: type: - string - "null" format: date-time SelfServeIssueApiKeyResult: type: object additionalProperties: false required: - action - plaintextKey - apiKey - revokedPublicIds properties: action: type: string enum: - created - rotated plaintextKey: type: string apiKey: $ref: "#/components/schemas/SelfServeApiKeySummary" revokedPublicIds: type: array maxItems: 1 items: type: string SelfServeRateLimitState: type: object additionalProperties: false required: - loadClass - limitPerMinute - remaining - policy - retryAfterSeconds - observedAt properties: loadClass: type: string limitPerMinute: type: integer format: int64 remaining: type: integer format: int64 policy: type: string retryAfterSeconds: type: - integer - "null" format: int64 observedAt: type: string format: date-time SelfServeUsageEvent: type: object additionalProperties: false required: - requestId - apiKeyPublicId - apiKeyLabel - apiKeyEnvironment - apiKeyScopes - method - routePath - loadClass - statusCode - rateLimitState - observedAt properties: requestId: type: string apiKeyPublicId: type: string apiKeyLabel: type: string apiKeyEnvironment: type: string enum: - test - live apiKeyScopes: type: array maxItems: 2 uniqueItems: true items: type: string enum: - read - batch method: type: string routePath: type: string loadClass: type: string statusCode: type: integer format: int64 rateLimitState: oneOf: - $ref: "#/components/schemas/SelfServeRateLimitState" - type: "null" observedAt: type: string format: date-time SelfServePerKeyUsage: type: object additionalProperties: false required: - apiKey - totalRequests - successCount - failureCount - lastRequestAt - lastFailureAt - latestRateLimitState properties: apiKey: $ref: "#/components/schemas/SelfServeApiKeySummary" totalRequests: type: integer format: int64 successCount: type: integer format: int64 failureCount: type: integer format: int64 lastRequestAt: type: - string - "null" format: date-time lastFailureAt: type: - string - "null" format: date-time latestRateLimitState: oneOf: - $ref: "#/components/schemas/SelfServeRateLimitState" - type: "null" SelfServeUsageSnapshot: type: object additionalProperties: false required: - windowStart - windowEnd - totalRequests - totalFailures - perKey - perKeyTruncated - recentRequests - recentRequestsTruncated - recentFailures - recentFailuresTruncated properties: windowStart: type: string format: date-time windowEnd: type: string format: date-time totalRequests: type: integer format: int64 totalFailures: type: integer format: int64 perKey: type: array maxItems: 100 description: Per-key aggregates for the bounded recent usage window. items: $ref: "#/components/schemas/SelfServePerKeyUsage" perKeyTruncated: type: boolean description: True when older keys fell outside the bounded per-key window. recentRequests: type: array maxItems: 100 description: Most recent request events in the bounded usage window. items: $ref: "#/components/schemas/SelfServeUsageEvent" recentRequestsTruncated: type: boolean description: True when more recent request events exist outside the returned slice. recentFailures: type: array maxItems: 25 description: Most recent failure events in the bounded usage window. items: $ref: "#/components/schemas/SelfServeUsageEvent" recentFailuresTruncated: type: boolean description: True when more failure events exist outside the returned slice. SelfServeApiKeyListResponse: type: object additionalProperties: false required: - items - truncated properties: items: type: array maxItems: 100 description: Newest-first self-serve API key metadata slice for the authenticated workspace. items: $ref: "#/components/schemas/SelfServeApiKeySummary" truncated: type: boolean description: True when older historical keys exist outside the returned slice. SelfServeApiKeyDeleteResponse: type: object additionalProperties: false required: - apiKey properties: apiKey: $ref: "#/components/schemas/SelfServeApiKeySummary" TokenTransferItem: type: object additionalProperties: false required: - blockNumber - timestampIso - txIndex - logIndex - transferIndex - txHash - fromAddress - toAddress - amount - rawValue - tokenId - standard properties: blockNumber: type: integer format: int64 timestampIso: type: - string - "null" format: date-time txIndex: type: integer format: int32 logIndex: type: integer format: int32 transferIndex: type: integer format: int32 txHash: type: string fromAddress: type: - string - "null" toAddress: type: - string - "null" amount: type: - string - "null" rawValue: type: - string - "null" tokenId: type: - string - "null" standard: type: string TokenTransferPage: type: object additionalProperties: false required: - items - nextCursor properties: items: type: array maxItems: 100 items: $ref: "#/components/schemas/TokenTransferItem" nextCursor: type: - string - "null" GlobalTransferItem: type: object additionalProperties: false required: - blockNumber - timestampIso - txIndex - logIndex - transferIndex - txHash - tokenAddress - fromAddress - toAddress - amount - rawValue - tokenId - standard - sourceTier properties: blockNumber: type: integer format: int64 timestampIso: type: - string - "null" format: date-time txIndex: type: integer format: int32 logIndex: type: integer format: int32 transferIndex: type: integer format: int32 txHash: type: string tokenAddress: type: string fromAddress: type: - string - "null" toAddress: type: - string - "null" amount: type: - string - "null" rawValue: type: - string - "null" tokenId: type: - string - "null" standard: type: string sourceTier: type: string enum: - head - finalized GlobalTransferPage: type: object additionalProperties: false required: - items - nextCursor properties: items: type: array maxItems: 100 items: $ref: "#/components/schemas/GlobalTransferItem" nextCursor: type: - string - "null" pattern: ^[0-9]+:[0-9]+:[0-9]+:[0-9]+$ GlobalEventItem: type: object additionalProperties: false required: - blockNumber - timestampIso - txIndex - logIndex - txHash - address - topic0 - topic1 - topic2 - topic3 - data - sourceTier properties: blockNumber: type: integer format: int64 timestampIso: type: - string - "null" format: date-time txIndex: type: integer format: int32 logIndex: type: integer format: int32 txHash: type: string address: type: string topic0: type: - string - "null" topic1: type: - string - "null" topic2: type: - string - "null" topic3: type: - string - "null" data: type: array maxItems: 1024 items: type: string sourceTier: type: string enum: - head - finalized GlobalEventPage: type: object additionalProperties: false required: - items - nextCursor properties: items: type: array maxItems: 100 items: $ref: "#/components/schemas/GlobalEventItem" nextCursor: type: - string - "null" pattern: ^[0-9]+:[0-9]+:[0-9]+$ StrkbtcShieldEventItem: type: object additionalProperties: false required: - blockNumber - txIndex - logIndex - txHash - contractAddress - topic0 - direction - commitmentOrNullifier - publicAmount properties: blockNumber: type: integer format: int64 txIndex: type: integer format: int32 logIndex: type: integer format: int32 txHash: type: string contractAddress: type: string topic0: type: string direction: type: string enum: - shield - unshield commitmentOrNullifier: type: string publicAmount: type: - string - "null" StrkbtcShieldEventPage: type: object additionalProperties: false required: - items - nextCursor properties: items: type: array maxItems: 100 items: $ref: "#/components/schemas/StrkbtcShieldEventItem" nextCursor: type: - string - "null" StrkbtcCommitmentItem: type: object additionalProperties: false required: - blockNumber - txIndex - logIndex - txHash - commitmentHash properties: blockNumber: type: integer format: int64 txIndex: type: integer format: int32 logIndex: type: integer format: int32 txHash: type: string commitmentHash: type: string StrkbtcCommitmentPage: type: object additionalProperties: false required: - items - nextCursor properties: items: type: array maxItems: 100 items: $ref: "#/components/schemas/StrkbtcCommitmentItem" nextCursor: type: - string - "null" StrkbtcNullifierItem: type: object additionalProperties: false required: - blockNumber - txIndex - logIndex - txHash - nullifierHash properties: blockNumber: type: integer format: int64 txIndex: type: integer format: int32 logIndex: type: integer format: int32 txHash: type: string nullifierHash: type: string StrkbtcNullifierPage: type: object additionalProperties: false required: - items - nextCursor properties: items: type: array maxItems: 100 items: $ref: "#/components/schemas/StrkbtcNullifierItem" nextCursor: type: - string - "null" StrkbtcPoolStatusView: type: object additionalProperties: false required: - chainId - commitmentCount - nullifierCount - netOpenCount - version - updatedAtIso properties: chainId: type: string commitmentCount: type: integer format: int64 nullifierCount: type: integer format: int64 netOpenCount: type: integer format: int64 version: type: integer format: int64 updatedAtIso: type: string PrivacyPoolPublicVisibility: type: string enum: - public - partial - hidden_by_design PrivacyPoolTokenView: type: object additionalProperties: false required: - address - symbol - name - decimals properties: address: type: string symbol: type: - string - "null" name: type: - string - "null" decimals: type: - integer - "null" format: int32 PrivacyPoolPublicFieldsView: type: object additionalProperties: false required: - visibility - actorAddress - toAddress - token - amountRaw - noteId - nullifier - auditorPublicKey properties: visibility: $ref: "#/components/schemas/PrivacyPoolPublicVisibility" actorAddress: type: - string - "null" toAddress: type: - string - "null" token: oneOf: - $ref: "#/components/schemas/PrivacyPoolTokenView" - type: "null" amountRaw: type: - string - "null" noteId: type: - string - "null" nullifier: type: - string - "null" auditorPublicKey: type: - string - "null" PrivacyPoolFeeEvidenceView: type: object additionalProperties: false required: - tokenAddress - amountRaw - collectorAddress - transferLogIndex - transferIndex - feeCollectorConfigBlockNumber - feeCollectorConfigTxIndex - feeCollectorConfigLogIndex - feeAmountConfigBlockNumber - feeAmountConfigTxIndex - feeAmountConfigLogIndex properties: tokenAddress: type: string amountRaw: type: string collectorAddress: type: string transferLogIndex: type: integer format: int32 transferIndex: type: integer format: int32 feeCollectorConfigBlockNumber: type: integer format: int64 feeCollectorConfigTxIndex: type: integer format: int32 feeCollectorConfigLogIndex: type: integer format: int32 feeAmountConfigBlockNumber: type: integer format: int64 feeAmountConfigTxIndex: type: integer format: int32 feeAmountConfigLogIndex: type: integer format: int32 PrivacyPoolEventItem: type: object additionalProperties: false required: - blockNumber - timestampIso - txIndex - logIndex - txHash - contractAddress - topic0 - eventName - key1 - key2 - data0 - data1 - data2 - keys - data - publicFields - privacyFees properties: blockNumber: type: integer format: int64 timestampIso: type: - string - "null" format: date-time description: UTC block timestamp when the indexed block is available. txIndex: type: integer format: int32 logIndex: type: integer format: int32 txHash: type: string contractAddress: type: string topic0: type: string eventName: type: string description: Indexed snake_case privacy-pool event name. maxLength: 32 pattern: ^[a-z0-9_]+$ examples: - deposit - withdrawal - proof_validity_blocks_set - protocol_event key1: type: - string - "null" key2: type: - string - "null" data0: type: - string - "null" data1: type: - string - "null" data2: type: - string - "null" keys: type: array description: Raw Starknet event keys as stored by the indexer. Payload-backed rows expose the full receipt keys array with the selector at index 0. Legacy rows without payload arrays expose only the indexed selector/key subset and must not be treated as receipt-complete evidence until verified against the transaction receipt. minItems: 1 maxItems: 1024 items: type: string data: type: array description: Raw Starknet event data as stored by the indexer. Payload-backed rows expose the full receipt data array. Legacy rows without payload arrays expose only the indexed data subset and must not be treated as receipt-complete evidence until verified against the transaction receipt. maxItems: 1024 items: type: string publicFields: $ref: "#/components/schemas/PrivacyPoolPublicFieldsView" privacyFees: type: array description: Public fee-transfer evidence for the same transaction, deduped per Activity row; empty when no configured privacy-pool fee transfer is present. maxItems: 64 items: $ref: "#/components/schemas/PrivacyPoolFeeEvidenceView" PrivacyPoolEventPage: type: object additionalProperties: false required: - items - nextCursor properties: items: type: array maxItems: 100 items: $ref: "#/components/schemas/PrivacyPoolEventItem" nextCursor: type: - string - "null" PrivacyPoolCommitmentFactItem: type: object additionalProperties: false required: - blockNumber - txIndex - logIndex - txHash - poolContractAddress - eventName - commitmentHash - tokenAddress - amountRaw properties: blockNumber: type: integer format: int64 txIndex: type: integer format: int32 logIndex: type: integer format: int32 txHash: type: string poolContractAddress: type: string eventName: type: string commitmentHash: type: string tokenAddress: type: - string - "null" amountRaw: type: - string - "null" PrivacyPoolCommitmentFactPage: type: object additionalProperties: false required: - items - nextCursor properties: items: type: array maxItems: 100 items: $ref: "#/components/schemas/PrivacyPoolCommitmentFactItem" nextCursor: type: - string - "null" pattern: ^[0-9]+:[0-9]+:[0-9]+$ PrivacyPoolNullifierFactItem: type: object additionalProperties: false required: - blockNumber - txIndex - logIndex - txHash - poolContractAddress - eventName - nullifierHash properties: blockNumber: type: integer format: int64 txIndex: type: integer format: int32 logIndex: type: integer format: int32 txHash: type: string poolContractAddress: type: string eventName: type: string nullifierHash: type: string PrivacyPoolNullifierFactPage: type: object additionalProperties: false required: - items - nextCursor properties: items: type: array maxItems: 100 items: $ref: "#/components/schemas/PrivacyPoolNullifierFactItem" nextCursor: type: - string - "null" pattern: ^[0-9]+:[0-9]+:[0-9]+$ PrivacyPoolRootFactItem: type: object additionalProperties: false required: - blockNumber - txIndex - logIndex - txHash - poolContractAddress - eventName - rootHash - treeSize properties: blockNumber: type: integer format: int64 txIndex: type: integer format: int32 logIndex: type: integer format: int32 txHash: type: string poolContractAddress: type: string eventName: type: string rootHash: type: string treeSize: type: - string - "null" PrivacyPoolRootFactPage: type: object additionalProperties: false required: - items - nextCursor properties: items: type: array maxItems: 100 items: $ref: "#/components/schemas/PrivacyPoolRootFactItem" nextCursor: type: - string - "null" pattern: ^[0-9]+:[0-9]+:[0-9]+$ PrivacyPoolStatusView: type: object additionalProperties: false required: - chainId - totalEvents - depositCount - withdrawalCount - openNoteCreatedCount - openNoteDepositedCount - encNoteCreatedCount - noteUsedCount - auditorPublicKeySetCount - viewingKeySetCount - registeredUserCount - noteState - eventBreakdown - latestEventBlock - latestEventTxIndex - latestEventLogIndex - latestEventCursor - latestDecodedEventBlock - latestDecodedEventTxIndex - latestDecodedEventLogIndex - latestDecodedEventCursor - latestRawEventBlock - latestRawEventTxIndex - latestRawEventLogIndex - latestRawEventCursor - eventLagBlocks - materializationFresh properties: chainId: type: string totalEvents: type: integer format: int64 depositCount: type: integer format: int64 withdrawalCount: type: integer format: int64 openNoteCreatedCount: type: integer format: int64 openNoteDepositedCount: type: integer format: int64 encNoteCreatedCount: type: integer format: int64 noteUsedCount: type: integer format: int64 auditorPublicKeySetCount: type: integer format: int64 viewingKeySetCount: type: integer format: int64 description: Number of indexed public ViewingKeySet event rows. registeredUserCount: type: integer format: int64 description: Distinct public user addresses that registered a viewing key. noteState: $ref: "#/components/schemas/PrivacyPoolNoteStateView" eventBreakdown: type: array description: Complete partition of indexed privacy-pool events by event name. items: $ref: "#/components/schemas/PrivacyPoolCountView" latestEventBlock: type: - integer - "null" format: int64 description: Backwards-compatible alias for the latest decoded/materialized privacy-pool event block. latestEventTxIndex: type: - integer - "null" format: int32 description: Backwards-compatible alias for the latest decoded/materialized privacy-pool event transaction index. latestEventLogIndex: type: - integer - "null" format: int32 description: Backwards-compatible alias for the latest decoded/materialized privacy-pool event log index. latestEventCursor: type: - string - "null" pattern: ^[0-9]+:[0-9]+:[0-9]+$ description: Backwards-compatible alias for the latest decoded/materialized privacy-pool event cursor as block:tx:log. latestDecodedEventBlock: type: - integer - "null" format: int64 description: Latest privacy-pool event block that has passed decoding and materialization. latestDecodedEventTxIndex: type: - integer - "null" format: int32 description: Transaction index component of the latest decoded/materialized privacy-pool event cursor. latestDecodedEventLogIndex: type: - integer - "null" format: int32 description: Log index component of the latest decoded/materialized privacy-pool event cursor. latestDecodedEventCursor: type: - string - "null" pattern: ^[0-9]+:[0-9]+:[0-9]+$ description: Exact latest decoded/materialized privacy-pool event cursor as block:tx:log. latestRawEventBlock: type: - integer - "null" format: int64 description: Latest raw privacy-pool contract event block observed by the source-event filter, when available. latestRawEventTxIndex: type: - integer - "null" format: int32 description: Transaction index component of the latest raw privacy-pool source-event cursor, when available. latestRawEventLogIndex: type: - integer - "null" format: int32 description: Log index component of the latest raw privacy-pool source-event cursor, when available. latestRawEventCursor: type: - string - "null" pattern: ^[0-9]+:[0-9]+:[0-9]+$ description: Exact latest raw privacy-pool source-event cursor as block:tx:log, when available. eventLagBlocks: type: - integer - "null" format: int64 description: Raw-event block minus decoded/materialized event block when the raw source-event filter is available. materializationFresh: type: - boolean - "null" description: True when decoded privacy-pool materialization is caught up with raw event evidence; null when no raw source-event filter is configured. PrivacyPoolNoteStateView: type: object additionalProperties: false required: - commitmentCount - nullifierCount - openNoteCreatedCount - openNoteDepositedCount - encNoteCreatedCount - noteUsedCount - spentNoteProxyCount - unspentNoteProxyCount - source - caveat properties: commitmentCount: type: integer format: int64 minimum: 0 description: Count of public commitment facts indexed for the pool. nullifierCount: type: integer format: int64 minimum: 0 description: Count of public nullifier facts indexed for the pool. openNoteCreatedCount: type: integer format: int64 minimum: 0 openNoteDepositedCount: type: integer format: int64 minimum: 0 encNoteCreatedCount: type: integer format: int64 minimum: 0 noteUsedCount: type: integer format: int64 minimum: 0 spentNoteProxyCount: type: integer format: int64 minimum: 0 description: Public spent-note proxy equal to the nullifier count; notes are not linked. unspentNoteProxyCount: type: integer format: int64 minimum: 0 description: Public unspent-note proxy computed as commitments minus nullifiers, floored at zero. source: type: string enum: - public_decoded_event_rows caveat: type: string const: Public note/nullifier proxy only; not exact anonymity k; exact anonymity requires root-time state and denomination semantics. description: Explicit caveat that this is not exact anonymity k. PrivacyPoolCountView: type: object additionalProperties: false required: - name - count properties: name: type: string maxLength: 32 pattern: ^[a-z0-9_]+$ description: | Breakdown bucket name. Event breakdowns use indexed privacy-pool snake_case event names; visibility breakdowns use `public`, `partial`, or `hidden_by_design`. examples: - deposit - protocol_event - hidden_by_design count: type: integer format: int64 PrivacyPoolTokenFlowView: type: object additionalProperties: false required: - token - eventCount - depositEventCount - withdrawalEventCount - observableDepositAmountRaw - observableWithdrawalAmountRaw - observableNetAmountRaw - missingAmountEventCount properties: token: $ref: "#/components/schemas/PrivacyPoolTokenView" eventCount: type: integer format: int64 depositEventCount: type: integer format: int64 withdrawalEventCount: type: integer format: int64 observableDepositAmountRaw: type: string observableWithdrawalAmountRaw: type: string observableNetAmountRaw: type: string missingAmountEventCount: type: integer format: int64 PrivacyPoolUnavailableMetricView: type: object additionalProperties: false required: - metric - reasonCode - reason properties: metric: type: string enum: - tvlUsd - anonSwapVolume - exactAnonymitySet reasonCode: type: string enum: - requires_balance_and_price_snapshots - swap_attribution_unavailable - commitment_state_materializer_required reason: type: string PrivacyPoolMetricBucketItem: type: object additionalProperties: false required: - bucketStartIso - bucketGranularity - newViewingKeyWallets - cumulativeViewingKeyWallets - visibleDeposits - visibleWithdrawals - noteUsedEvents - latestBlockNumber properties: bucketStartIso: type: string format: date-time bucketGranularity: type: string enum: - day newViewingKeyWallets: type: integer format: int64 minimum: 0 cumulativeViewingKeyWallets: type: integer format: int64 minimum: 0 visibleDeposits: type: integer format: int64 minimum: 0 visibleWithdrawals: type: integer format: int64 minimum: 0 noteUsedEvents: type: integer format: int64 minimum: 0 latestBlockNumber: type: - integer - "null" format: int64 minimum: 0 PrivacyPoolMetricBucketPage: type: object additionalProperties: false required: - chainId - bucketGranularity - items properties: chainId: type: string bucketGranularity: type: string enum: - day items: type: array maxItems: 90 items: $ref: "#/components/schemas/PrivacyPoolMetricBucketItem" PrivacyPoolWalletMetricSeriesItem: type: object additionalProperties: false required: - bucketStartIso - bucketGranularity - newViewingKeyWallets - cumulativeViewingKeyWallets - latestBlockNumber properties: bucketStartIso: type: string format: date-time bucketGranularity: type: string enum: - hour - day - week newViewingKeyWallets: type: integer format: int64 minimum: 0 cumulativeViewingKeyWallets: type: integer format: int64 minimum: 0 latestBlockNumber: type: - integer - "null" format: int64 minimum: 0 PrivacyPoolShieldedSupplySeriesItem: type: object additionalProperties: false required: - bucketStartIso - bucketGranularity - tokenAddress - depositedRaw - withdrawnRaw - shieldedSupplyRaw - latestBlockNumber properties: bucketStartIso: type: string format: date-time bucketGranularity: type: string enum: - hour - day - week tokenAddress: type: string depositedRaw: type: string pattern: ^[0-9]+$ maxLength: 80 withdrawnRaw: type: string pattern: ^[0-9]+$ maxLength: 80 shieldedSupplyRaw: type: string pattern: ^[0-9]+$ maxLength: 80 latestBlockNumber: type: - integer - "null" format: int64 minimum: 0 PrivacyPoolFeeMetricSeriesItem: type: object additionalProperties: false required: - bucketStartIso - bucketGranularity - tokenAddress - feeAmountRaw - cumulativeFeeAmountRaw - feeTransferCount - latestBlockNumber properties: bucketStartIso: type: string format: date-time bucketGranularity: type: string enum: - hour - day - week tokenAddress: type: string feeAmountRaw: type: string pattern: ^[0-9]+$ maxLength: 80 cumulativeFeeAmountRaw: type: string pattern: ^[0-9]+$ maxLength: 80 feeTransferCount: type: integer format: int64 minimum: 0 latestBlockNumber: type: - integer - "null" format: int64 minimum: 0 PrivacyPoolMetricSeriesPage: type: object additionalProperties: false required: - chainId - range - bucketGranularity - token - walletSeries - shieldedSupplySeries - privacyFeeSeries properties: chainId: type: string range: type: string enum: - 24h - 7d - 30d - all bucketGranularity: type: string enum: - hour - day - week token: $ref: "#/components/schemas/PrivacyPoolTokenView" walletSeries: type: array maxItems: 720 items: $ref: "#/components/schemas/PrivacyPoolWalletMetricSeriesItem" shieldedSupplySeries: type: array maxItems: 720 items: $ref: "#/components/schemas/PrivacyPoolShieldedSupplySeriesItem" privacyFeeSeries: type: array maxItems: 720 items: $ref: "#/components/schemas/PrivacyPoolFeeMetricSeriesItem" PrivacyPoolAnalyticsView: type: object additionalProperties: false required: - chainId - totalEvents - uniqueTransactionCount - contractCount - latestEventBlock - eventBreakdown - visibilityBreakdown - tokenFlows - tokenFlowsLimit - tokenFlowsTruncated - tokenFlowSourceEventLimit - tokenFlowSourceEventsTruncated - missingAmountEventCount - strkbtcObserved - unknownTokenCount - unavailableMetrics properties: chainId: type: string totalEvents: type: integer format: int64 uniqueTransactionCount: type: integer format: int64 contractCount: type: integer format: int64 latestEventBlock: type: - integer - "null" format: int64 eventBreakdown: type: array items: $ref: "#/components/schemas/PrivacyPoolCountView" visibilityBreakdown: type: array items: $ref: "#/components/schemas/PrivacyPoolCountView" tokenFlows: type: array items: $ref: "#/components/schemas/PrivacyPoolTokenFlowView" tokenFlowsLimit: type: integer format: int64 tokenFlowsTruncated: type: boolean tokenFlowSourceEventLimit: type: integer format: int64 description: | Source event window used to derive tokenFlows. A value of 0 means the route is using all-history indexed public token-flow facts instead of deriving metrics from a bounded recent event sample. tokenFlowSourceEventsTruncated: type: boolean description: | True when tokenFlows were derived from a clipped source event window. False for all-history fact-backed token-flow metrics. missingAmountEventCount: type: integer format: int64 strkbtcObserved: type: boolean unknownTokenCount: type: integer format: int64 unavailableMetrics: type: array items: $ref: "#/components/schemas/PrivacyPoolUnavailableMetricView" SearchBlockItem: type: object additionalProperties: false required: - blockNumber - blockHash properties: blockNumber: type: integer format: int64 blockHash: type: string SearchTransactionItem: type: object additionalProperties: false required: - txHash - blockNumber - txIndex properties: txHash: type: string blockNumber: type: integer format: int64 txIndex: type: integer format: int32 SearchView: type: object additionalProperties: false required: - blocks - transactions - addresses properties: blocks: type: array maxItems: 5 items: $ref: "#/components/schemas/SearchBlockItem" transactions: type: array maxItems: 10 items: $ref: "#/components/schemas/SearchTransactionItem" addresses: type: array maxItems: 10 items: type: string headers: RequestId: description: Canonical request correlation header for support and tracing. schema: type: string WwwAuthenticate: description: Authentication or scope hint when the request is rejected. schema: type: string RetryAfter: description: Seconds to wait before retrying this route class. schema: type: integer format: int64 MezcalRouteClass: description: Route budget class for class-specific backoff. schema: type: string enum: - light - list - heavy - profile - batch RateLimitLimit: description: Maximum request budget for the current route-class window. schema: type: integer format: int64 RateLimitRemaining: description: Remaining request budget for the current route-class window. schema: type: integer format: int64 RateLimitPolicy: description: Opaque rate-limit policy identifier for the current route class. schema: type: string x-mezcal-audience: public-core tags: - name: Account description: Session-authenticated self-serve API-key lifecycle and usage routes for workspace operators. - name: Addresses - name: Blocks - name: Contracts - name: Reference description: Low-level explorer read surfaces that stay public but sit outside the default block/transaction/address entrypoints. - name: Search - name: Status - name: Tokens - name: Transactions - name: Utilities description: Supported helper routes that remain external, but are not the default public API starting point and can require broader utility-access keys.