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: /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" x-mezcal-audience: public-core x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Status /v1/{chain}/analytics/kpis: get: summary: Daily chain KPIs security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: days in: query description: Number of daily KPI rows to return (clamped to 1..90). schema: type: integer format: int32 minimum: 1 maximum: 90 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Recent daily KPI rows for one chain content: application/json: schema: $ref: "#/components/schemas/ChainKpiSeriesView" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" x-mezcal-audience: public-core x-mezcal-stability: preview-caveat x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read description: "Preview confidence note: this route is still being revalidated for stable non-empty payloads and should be treated as exploratory." tags: - Analytics /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 - name: tx_limit in: query description: Max block transactions returned (clamped to 1..200). schema: type: integer format: int32 minimum: 1 maximum: 200 - $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 content: text/plain: schema: type: string x-mezcal-audience: public-core 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 - 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 blocks page content: application/json: schema: $ref: "#/components/schemas/ChainBlockListPage" "400": description: Invalid list cursor input content: text/plain: schema: type: string "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" x-mezcal-audience: public-core 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 - name: cursor in: query description: Optional transaction index cursor for reverse pagination. schema: type: integer format: int32 minimum: 0 - 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: Block transaction page content: application/json: schema: $ref: "#/components/schemas/BlockTransactionPage" "400": description: Invalid block number input content: text/plain: schema: type: string "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Block not found content: text/plain: schema: type: string x-mezcal-audience: public-core 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": description: Invalid preview batch request payload content: text/plain: schema: type: string "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" x-mezcal-audience: public-core 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/details: post: summary: Batch transaction details by hash description: |- Ordered batch hydration for transaction detail payloads. This heavier route is capped more tightly than `tx/previews`, and each item can mark `logsTruncated` or `tokenTransfersTruncated` when bounded child data was clipped for predictable latency. 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. security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - $ref: "#/components/parameters/RequestIdHeader" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/TransactionDetailBatchRequest" responses: "200": description: Ordered transaction detail results content: application/json: schema: $ref: "#/components/schemas/TransactionDetailBatchView" "400": description: Invalid detail batch request payload content: text/plain: schema: type: string "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" x-mezcal-audience: public-core x-mezcal-stability: stable x-mezcal-surface-tier: advanced-utility x-mezcal-key-tier: utility 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 content: text/plain: schema: type: string x-mezcal-audience: public-core 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": description: Invalid list cursor input content: text/plain: schema: type: string "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" x-mezcal-audience: public-core x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Transactions /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": description: Invalid chain or transaction hash content: text/plain: schema: type: string "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Transaction trace not found content: text/plain: schema: type: string x-mezcal-audience: public-core 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" x-mezcal-audience: public-core x-mezcal-stability: preview-caveat x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read description: "Preview confidence note: do not rely on this route as the freshest latest-activity source for automation. Prefer address activity, token holdings, and exact token reads when freshness matters." tags: - Addresses /v1/{chain}/address/summaries: post: summary: Batch address aggregate summaries description: |- Ordered batch hydration for address summary payloads. This advanced utility is optimized for controlled navigation and partner batch workflows; it can return honest inexact activity counts instead of chasing expensive raw-count proofs. Use single-address activity and token-holdings routes when freshest per-address evidence is required. 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. 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": description: Invalid address summary batch request payload content: text/plain: schema: type: string "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" x-mezcal-audience: public-core x-mezcal-stability: stable x-mezcal-surface-tier: advanced-utility x-mezcal-key-tier: utility 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": description: Invalid cursor input content: text/plain: schema: type: string "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" x-mezcal-audience: public-core x-mezcal-stability: preview-caveat x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read description: "Preview confidence note: transaction rows can omit timestampIso on preview. Prefer address activity when you need per-row timestamps." tags: - Addresses /v1/{chain}/address/{address}/token-holdings: get: summary: Indexed token holdings for one owner address description: Preferred wallet-state and wallet-screening surface on Mezcal's public API. Use this route for portfolio checks, skip lists, and "does this wallet hold this asset class?" decisions. For definitive screening, treat the response as complete only when `exact=true` and `truncated=false`. On very hot wallets, separate `latest` calls to this route and `token/{token}/balance-of/{address}` can drift numerically if the chain moved between requests; a missing core-token row on a completed holdings response is the stronger correctness signal. 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" x-mezcal-audience: public-core x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Addresses /v1/{chain}/address/{address}/nft-holdings: get: summary: Indexed NFT holdings for one owner address description: Lazy NFT asset-tab surface. Returns current indexed NFT holdings without token_uri, external metadata JSON, or image fetches on the contract page critical path. Item metadata may be pending while deterministic collection/token-id rows still render. security: - MezcalApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true schema: type: string - name: cursor in: query description: Opaque cursor from 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 - name: contractAddress in: query description: Optional NFT collection address filter. If contract_address is also provided, both canonicalized values must match. schema: type: string - name: contract_address in: query description: Optional snake_case alias for contractAddress. If both spellings are provided, both canonicalized values must match. schema: type: string - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Address NFT holdings page content: application/json: schema: $ref: "#/components/schemas/AddressNftHoldingsView" "400": description: Invalid cursor or contract address input content: text/plain: schema: type: string "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" x-mezcal-audience: public-core 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": description: Invalid chain or contract address content: text/plain: schema: type: string "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Contract verification record not found content: text/plain: schema: type: string x-mezcal-audience: public-core 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 description: Lists contract selectors grouped by Starknet entrypoint type. The `external` list may include both read-only view selectors and write-capable external selectors. Do not assume every `external` selector is valid for `GET /v1/{chain}/contract/{address}/read`; use `stateMutability=view` as the positive signal for read-safe selectors, and provide calldata when the selector requires inputs. 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": description: Invalid chain or contract address content: text/plain: schema: type: string "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Contract/class not found content: text/plain: schema: type: string x-mezcal-audience: public-core 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": description: Invalid address, topic, cursor, or block-range input content: text/plain: schema: type: string "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" x-mezcal-audience: public-core x-mezcal-stability: stable 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 description: Executes a read-only Starknet call. Use selectors that are explicitly read-safe for the contract ABI, typically those surfaced by `/contract/{address}/entrypoints` with `stateMutability=view`. Selectors that are write-capable, constructor-only, or missing required calldata return typed client errors instead of generic server faults. 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": description: Malformed request input such as missing selector or unsupported block_tag content: application/json: schema: $ref: "#/components/schemas/ContractReadErrorEnvelope" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Contract or entrypoint not found content: application/json: schema: $ref: "#/components/schemas/ContractReadErrorEnvelope" "422": description: Selector/calldata combination is not valid for a read-only call content: application/json: schema: $ref: "#/components/schemas/ContractReadErrorEnvelope" "500": description: Internal contract-read failure content: application/json: schema: $ref: "#/components/schemas/ContractReadErrorEnvelope" "503": description: Contract read timed out or is temporarily unavailable headers: Retry-After: schema: type: integer format: int64 minimum: 1 content: application/json: schema: $ref: "#/components/schemas/ContractReadErrorEnvelope" x-mezcal-audience: public-core 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 description: Freshest indexed wallet-history surface on the public API. Prefer this route when automations need latest activity or timestamped wallet history. Use it together with `address/{address}/token-holdings` for current wallet state; do not rely on `GET /v1/{chain}/address/{address}` alone as your freshest latest-activity source. 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" x-mezcal-audience: public-core 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 content: text/plain: schema: type: string x-mezcal-audience: public-core x-mezcal-stability: preview-caveat x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read description: "Preview confidence note: treat aggregate transfer counters on this route as provisional. Use the token transfers route as the source of truth for transfer history." 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": description: Invalid block_tag input content: text/plain: schema: type: string "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Contract does not expose a supported totalSupply selector content: text/plain: schema: type: string "503": description: Upstream RPC temporarily unavailable headers: Retry-After: schema: type: integer format: int64 content: text/plain: schema: type: string x-mezcal-audience: public-core 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 description: Exact-token balance read. Use this route only when you already know the precise token contract you want to query. On Starknet, one symbol can map to multiple live token contracts or aliases, so a single `balance-of` can legitimately return `0` while the wallet still holds another variant. For wallet screening or broader wallet-state checks, prefer `address/{address}/token-holdings` and `address/{address}/activity`. This is a token-specific spot read, not a guaranteed shared-snapshot companion for separate `token-holdings` requests on fast-moving wallets. 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": description: Invalid block_tag input content: text/plain: schema: type: string "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Contract does not expose a supported balanceOf selector content: text/plain: schema: type: string "503": description: Upstream RPC temporarily unavailable headers: Retry-After: schema: type: integer format: int64 content: text/plain: schema: type: string x-mezcal-audience: public-core x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read 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" x-mezcal-audience: public-core x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Tokens /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). This route is identifier-first, not ticker or symbol search, and returned hashes/addresses can be normalized into canonical padded felt forms. 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" x-mezcal-audience: public-core x-mezcal-stability: stable x-mezcal-surface-tier: official-public-api x-mezcal-key-tier: read tags: - Search components: securitySchemes: MezcalApiKey: type: apiKey in: header name: X-Mezcal-Api-Key description: Mezcal API key for the public read contract. parameters: ChainParam: name: chain in: path required: true schema: type: string 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: description: Canonical request correlation header for support and tracing. schema: type: string WWW-Authenticate: description: Auth error details when the request is rejected. schema: type: string content: text/plain: schema: type: string example: Unauthorized ForbiddenText: description: Valid Mezcal credential lacks the required scope. headers: X-Request-Id: description: Canonical request correlation header for support and tracing. schema: type: string WWW-Authenticate: description: Scope hint when the caller lacks required access. schema: type: string content: text/plain: schema: type: string example: Forbidden schemas: ExplorerStatusView: type: object additionalProperties: false required: - chainId - headBlockNumber - headBlockHash - finalizedBlockNumber - latestIndexedBlockNumber - earliestIndexedBlockNumber - indexedBlockSpan - lagBlocks 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 ChainKpiDayView: type: object additionalProperties: false required: - dayIso - txCount - gasUsedNumeric - activeAddresses - computedAtIso properties: dayIso: type: string txCount: type: integer format: int64 gasUsedNumeric: type: string activeAddresses: type: integer format: int64 computedAtIso: type: string medianFeeWei: type: - string - "null" p95FeeWei: type: - string - "null" newContracts24h: type: - integer - "null" format: int64 l1SettlementLatencySeconds: type: - integer - "null" format: int64 ChainKpiSeriesView: type: object additionalProperties: false required: - chainId - items properties: chainId: type: string items: type: array maxItems: 90 items: $ref: "#/components/schemas/ChainKpiDayView" 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" 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`. Compact previews therefore report `logCount=0` unless you request counts or logs explicitly. 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. TransactionDetailBatchView: type: object additionalProperties: false required: - items properties: items: description: | Transaction detail results returned in the same order as the submitted `hashes` list, preserving a one-to-one positional mapping between request entries and response items. type: array maxItems: 32 items: $ref: "#/components/schemas/TransactionDetailView" TransactionDetailBatchRequest: type: object additionalProperties: false required: - hashes properties: hashes: description: | Ordered transaction hashes to hydrate. Exact duplicates are rejected by schema validation, and the service also rejects hashes that normalize to the same lowercase logical value after trim/padding compaction so the request preserves a one-to-one ordered mapping to response items. type: array minItems: 1 maxItems: 32 uniqueItems: true items: type: string logLimitPerTx: type: - integer - "null" format: int32 default: 96 minimum: 1 maximum: 256 description: | Maximum number of event logs returned per transaction detail item. Defaults to `96` when omitted. TransactionDetailView: type: object additionalProperties: false required: - chainId - blockNumber - txIndex - txHash - txCursor - fromAddress - toAddress - executionStatus - finalityStatus - txType - rawObjectKey - calldata - receipt - logsTruncated - logs - tokenTransfersTruncated - tokenTransfers properties: chainId: type: string blockNumber: type: integer format: int64 timestampIso: type: - string - "null" 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 calldata: type: array maxItems: 1024 items: type: string receipt: oneOf: - $ref: "#/components/schemas/TransactionReceiptView" - type: "null" logsTruncated: type: boolean logs: type: array maxItems: 512 items: $ref: "#/components/schemas/TransactionLogView" tokenTransfers: type: array maxItems: 128 description: | Transfer rows included in this bounded detail response. Check `tokenTransfersTruncated` before treating this array as exhaustive. items: $ref: "#/components/schemas/TransactionTransferView" tokenTransfersTruncated: type: boolean description: | `true` when this transaction detail response clipped token transfers to keep response size predictable. bridgeIntent: oneOf: - $ref: "#/components/schemas/BridgeIntentView" - type: "null" description: | Bridge intent inferred from the visible transfer set. When `tokenTransfersTruncated` is `true`, this field is null or absent instead of guessing from a partial transfer slice. ContractReadErrorBody: type: object additionalProperties: false required: - code - message properties: code: type: string message: type: string retryAfterSeconds: type: integer format: int64 minimum: 1 details: $ref: "#/components/schemas/ContractReadErrorDetails" ContractReadErrorDetails: type: object additionalProperties: false required: - contractAddress - selector properties: contractAddress: type: string selector: type: string requiresCalldata: type: boolean ContractReadErrorEnvelope: type: object additionalProperties: false required: - error properties: error: $ref: "#/components/schemas/ContractReadErrorBody" 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 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]+$ 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 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 - 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 - txIndex - txHash - kinds - counterparty properties: blockNumber: type: integer format: int64 txIndex: type: integer format: int32 txHash: type: string kinds: type: array maxItems: 16 items: type: string counterparty: 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 - indexedBalanceRaw properties: tokenAddress: type: string indexedBalanceRaw: type: string AddressTokenHoldingsView: type: object additionalProperties: false required: - chainId - ownerAddress - items - exact - truncated 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: False when the response fell back to a degraded or capped holdings path. type: boolean truncated: description: True when the holdings list hit the 256-item safety cap. type: boolean AddressNftHoldingItemView: type: object additionalProperties: false required: - collectionAddress - tokenId - standard - balanceRaw - lastTransferBlockNumber - lastTransferTimestampIso - lastTransferTxHash - collectionName - collectionSymbol - itemName - itemDescription - metadataStatus - verified properties: collectionAddress: type: string tokenId: type: string standard: type: string balanceRaw: type: string lastTransferBlockNumber: type: integer format: int64 lastTransferTimestampIso: type: - string - "null" format: date-time lastTransferTxHash: type: string collectionName: type: - string - "null" collectionSymbol: type: - string - "null" itemName: type: - string - "null" itemDescription: type: - string - "null" metadataStatus: type: string enum: - pending - ready - error verified: type: boolean AddressNftHoldingsView: type: object additionalProperties: false required: - chainId - ownerAddress - items - nextCursor - exact - truncated properties: chainId: type: string ownerAddress: type: string items: type: array maxItems: 100 items: $ref: "#/components/schemas/AddressNftHoldingItemView" nextCursor: type: - string - "null" exact: description: False when the response fell back to a degraded NFT holdings path. type: boolean truncated: description: True only when a degraded or safety-capped response intentionally cut rows. Ordinary pagination uses nextCursor. type: boolean TokenSummaryView: type: object additionalProperties: false required: - chainId - tokenAddress - symbol - name - decimals - standard - transferCount - distinctFromCount - distinctToCount - latestTransferBlock properties: chainId: type: string tokenAddress: type: string symbol: type: - string - "null" name: type: - string - "null" decimals: type: - integer - "null" format: int32 standard: type: string transferCount: type: integer format: int64 distinctFromCount: type: integer format: int64 distinctToCount: type: integer format: int64 latestTransferBlock: type: - integer - "null" format: int64 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. 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" 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 x-mezcal-audience: public-core tags: - name: Addresses - name: Analytics - name: Blocks - name: Contracts - 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.