{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/blockvectra/json-schema/blockvectra-dex-swap-list-envelope-schema.json",
  "title": "DexSwapListEnvelope",
  "description": "`next_cursor` is present only when the page returned exactly `limit` rows.",
  "x-generated": "2026-11-02",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/data.yaml#/components/schemas/DexSwapListEnvelope",
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/DexSwap"
      }
    },
    "next_cursor": {
      "type": "string",
      "description": "Opaque pagination token from the previous response's `next_cursor`; pass it back unchanged."
    },
    "meta": {
      "$ref": "#/$defs/Meta"
    }
  },
  "$defs": {
    "Address": {
      "type": "string",
      "description": "20-byte address, canonical form always `0x` + 40 lowercase hex digits.",
      "pattern": "^0x[0-9a-f]{40}$"
    },
    "DexSwap": {
      "type": "object",
      "required": [
        "protocol",
        "pool_key",
        "amount0",
        "amount1",
        "sqrt_price_x96",
        "liquidity",
        "tick",
        "lp_fee",
        "sender",
        "recipient",
        "block_number",
        "block_timestamp",
        "tx_hash",
        "tx_index",
        "log_index"
      ],
      "properties": {
        "protocol": {
          "type": "string",
          "description": "e.g. \"uniswap_v3\"."
        },
        "pool_key": {
          "$ref": "#/$defs/Hash32",
          "description": "32-byte key; a V2/V3 pool address is left-zero-padded into this shape."
        },
        "amount0": {
          "$ref": "#/$defs/Int256String"
        },
        "amount1": {
          "$ref": "#/$defs/Int256String"
        },
        "sqrt_price_x96": {
          "$ref": "#/$defs/UInt256String"
        },
        "liquidity": {
          "$ref": "#/$defs/UInt256String"
        },
        "tick": {
          "type": "integer",
          "format": "int32"
        },
        "lp_fee": {
          "oneOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ]
        },
        "sender": {
          "$ref": "#/$defs/Address"
        },
        "recipient": {
          "oneOf": [
            {
              "$ref": "#/$defs/Address"
            },
            {
              "type": "null"
            }
          ]
        },
        "block_number": {
          "type": "integer",
          "format": "int64"
        },
        "block_timestamp": {
          "$ref": "#/$defs/Timestamp"
        },
        "tx_hash": {
          "$ref": "#/$defs/Hash32"
        },
        "tx_index": {
          "type": "integer"
        },
        "log_index": {
          "type": "integer"
        }
      }
    },
    "Hash32": {
      "type": "string",
      "description": "32-byte hash/topic, canonical form always `0x` + 64 lowercase hex digits.",
      "pattern": "^0x[0-9a-f]{64}$"
    },
    "Int256String": {
      "type": "string",
      "description": "Signed integer that may exceed +-2^53, rendered as a plain decimal string, optionally sign-prefixed.",
      "pattern": "^-?[0-9]+$"
    },
    "Meta": {
      "type": "object",
      "description": "Metadata present on every success response.",
      "required": [
        "chain",
        "chain_slug",
        "chain_external_id",
        "as_of_block",
        "safe_block",
        "finalized_block",
        "coverage",
        "refreshed_at"
      ],
      "properties": {
        "chain": {
          "type": "string",
          "description": "Chain identifier; the value of the `{chain}` path parameter."
        },
        "chain_slug": {
          "type": "string",
          "description": "Canonical uppercase chain slug; `chain` is always its lowercase form."
        },
        "chain_external_id": {
          "type": "string",
          "description": "CAIP-2 formatted external chain identifier (`eip155:{chain_id}`)."
        },
        "as_of_block": {
          "type": "integer",
          "format": "int64",
          "description": "The newest fully written block (the `blocks` table's maximum height); the only serving bound for block-scoped endpoints. For snapshot endpoints (balances, holders, nfts, dex prices, stocks) it is the service's current indexed head, not the block height of the snapshot: read the snapshot time from `meta.refreshed_at`, and treat the data as stale when `refreshed_at` is `null`."
        },
        "safe_block": {
          "type": [
            "integer",
            "null"
          ],
          "format": "int64",
          "description": "A marker only: the node's consensus `safe` block. Always present; `null` while no value is known (the node has no such tag, or the indexer has not read one yet). Only grows, never below `finalized_block`, and may be above or below `as_of_block`. It never truncates, rejects or bounds a response; see Finality in the API description."
        },
        "finalized_block": {
          "type": [
            "integer",
            "null"
          ],
          "format": "int64",
          "description": "A marker only: the node's consensus `finalized` block. Always present; `null` while no value is known (the node has no such tag, or the indexer has not read one yet). Only grows, and may be above or below `as_of_block`. It never truncates, rejects or bounds a response; see Finality in the API description."
        },
        "coverage": {
          "type": "string",
          "enum": [
            "full",
            "partial"
          ],
          "description": "`\"partial\"` appears only from `GET /{chain}/addresses/{address}/transactions` and `GET /{chain}/addresses/{address}/transfers`, when `clamp=true` narrowed the served window, and from those two, `GET /{chain}/tokens/{token}/transfers` and `GET /{chain}/dex/swaps` when the block window starts before the lower bound of the dataset the endpoint reads -- the chain's first indexed block, or higher while that dataset is still being backfilled (see Coverage in the API description and each endpoint's window description). Every other endpoint reports `\"full\"`."
        },
        "refreshed_at": {
          "description": "When the data behind this response was last updated (UTC): the timestamp of `as_of_block` for block-based endpoints, the latest snapshot time for snapshot endpoints, and the last update time for token metadata and status. `null` means the snapshot's update time is currently unknown: treat the data as stale; it never means \"just refreshed\".",
          "oneOf": [
            {
              "$ref": "#/$defs/Timestamp"
            },
            {
              "type": "null"
            }
          ]
        }
      }
    },
    "Timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "`YYYY-MM-DDTHH:MM:SSZ`, UTC, second precision."
    },
    "UInt256String": {
      "type": "string",
      "description": "Non-negative integer that may exceed 2^53, rendered as a plain decimal string — never a JSON number, never scientific or hex notation.",
      "pattern": "^[0-9]+$"
    }
  }
}