{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/cleartracedata-com/json-schema/cleartracedata-com-tx-attribution-response-schema.json",
  "title": "TxAttributionResponse",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/cleartracedata-com-openapi.yml#/components/schemas/TxAttributionResponse",
  "properties": {
    "tx_hash": {
      "type": "string",
      "title": "Tx Hash",
      "description": "The queried transaction hash (lower-cased)."
    },
    "chain": {
      "type": "string",
      "title": "Chain",
      "description": "The blockchain the lookup ran against."
    },
    "found": {
      "type": "boolean",
      "title": "Found",
      "description": "Whether the transaction was found and classified."
    },
    "status": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "title": "Status",
      "description": "On-chain receipt status (1 = success, 0 = reverted)."
    },
    "primary_vector": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Primary Vector",
      "description": "The dominant attribution vector: proxy, aggregator, fee_recipient, calldata_suffix, direct, or unclassified."
    },
    "vectors": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "title": "Vectors",
      "description": "All attribution vectors this transaction matches."
    },
    "originator": {
      "anyOf": [
        {
          "$ref": "#/$defs/TxOriginator"
        },
        {
          "type": "null"
        }
      ],
      "description": "The contract that originated the trade (tx_to) and its resolved name."
    },
    "is_direct": {
      "type": "boolean",
      "title": "Is Direct",
      "description": "Whether the caller hit a DEX pool directly.",
      "default": false
    },
    "is_proxy": {
      "type": "boolean",
      "title": "Is Proxy",
      "description": "Whether the trade routed through a proxy/router (hidden-frontend signal).",
      "default": false
    },
    "is_aggregator": {
      "type": "boolean",
      "title": "Is Aggregator",
      "description": "Whether a known aggregator router was involved.",
      "default": false
    },
    "aggregator_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Aggregator Name",
      "description": "Name of the matched aggregator, if any."
    },
    "has_calldata_suffix": {
      "type": "boolean",
      "title": "Has Calldata Suffix",
      "description": "Whether the calldata carries a non-ABI-aligned suffix fingerprint.",
      "default": false
    },
    "fee_recipients": {
      "items": {
        "$ref": "#/$defs/TxFeeRecipient"
      },
      "type": "array",
      "title": "Fee Recipients",
      "description": "Addresses that skimmed a fee out of the swap."
    },
    "pools": {
      "items": {
        "type": "string"
      },
      "type": "array",
      "title": "Pools",
      "description": "Liquidity pools (Swap-event emitters) touched by the transaction."
    },
    "routing_legs": {
      "type": "integer",
      "title": "Routing Legs",
      "description": "Number of Swap events (pool legs) in the transaction.",
      "default": 0
    },
    "sandwiched": {
      "type": "boolean",
      "title": "Sandwiched",
      "description": "Whether this transaction appears as a victim in our detected sandwich set.",
      "default": false
    },
    "trace_used": {
      "type": "boolean",
      "title": "Trace Used",
      "description": "Whether internal traces were used to refine the classification (deep mode).",
      "default": false
    },
    "deep": {
      "type": "boolean",
      "title": "Deep",
      "description": "Whether deep (trace-based) classification was requested.",
      "default": false
    },
    "estimated_volume_usd": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "title": "Estimated Volume Usd",
      "description": "Best-effort, APPROXIMATE USD trade size (dominant priced leg, DefiLlama spot price). Null when pricing was not requested or no leg could be priced. Never use as a settlement figure."
    },
    "volume_estimate_basis": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Volume Estimate Basis",
      "description": "How estimated_volume_usd was derived, when present."
    },
    "price": {
      "type": "boolean",
      "title": "Price",
      "description": "Whether best-effort USD sizing was requested.",
      "default": false
    },
    "cached": {
      "type": "boolean",
      "title": "Cached",
      "description": "Whether this result was served from cache.",
      "default": false
    },
    "originating_frontend": {
      "anyOf": [
        {
          "$ref": "#/$defs/OriginatingFrontend"
        },
        {
          "type": "null"
        }
      ],
      "description": "The trade's originating frontend, mapped onto the ClearTrace taxonomy (the spine). Derived from the attribution vectors."
    },
    "note": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Note",
      "description": "Diagnostic note (e.g. when Alchemy is unconfigured or the tx is unknown)."
    }
  },
  "type": "object",
  "required": [
    "tx_hash",
    "chain",
    "found"
  ],
  "$defs": {
    "OriginatingFrontend": {
      "properties": {
        "bucket": {
          "type": "string",
          "title": "Bucket",
          "description": "Taxonomy class: named_frontend, aggregator_api_direct, wallet_embedded, bots_mev, or unattributed."
        },
        "frontend_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Frontend Name",
          "description": "Resolved frontend/aggregator identity, when confident."
        },
        "method": {
          "type": "string",
          "title": "Method",
          "description": "How the frontend was attributed: calldata_suffix, fee_recipient, aggregator, router_heuristic, or none."
        },
        "confidence": {
          "type": "string",
          "title": "Confidence",
          "description": "Attribution-method strength: high (suffix), medium (router/fee), low (inferred), or none."
        },
        "attributed": {
          "type": "boolean",
          "title": "Attributed",
          "description": "True when the swap was confidently placed into a class (bucket != unattributed)."
        },
        "fingerprinted": {
          "type": "boolean",
          "title": "Fingerprinted",
          "description": "True when a calldata fingerprint proves a frontend tagged the swap but its identity could not be resolved.",
          "default": false
        }
      },
      "type": "object",
      "required": [
        "bucket",
        "method",
        "confidence",
        "attributed"
      ],
      "title": "OriginatingFrontend"
    },
    "TxFeeRecipient": {
      "properties": {
        "address": {
          "type": "string",
          "title": "Address",
          "description": "The fee-collecting address."
        },
        "name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Name",
          "description": "Resolved label for the recipient, if known."
        },
        "token_contract": {
          "type": "string",
          "title": "Token Contract",
          "description": "The ERC-20 contract the fee was paid in."
        },
        "raw_amount": {
          "type": "string",
          "title": "Raw Amount",
          "description": "Exact token amount transferred (raw integer, no decimals/USD applied)."
        }
      },
      "type": "object",
      "required": [
        "address",
        "token_contract",
        "raw_amount"
      ],
      "title": "TxFeeRecipient"
    },
    "TxOriginator": {
      "properties": {
        "address": {
          "type": "string",
          "title": "Address",
          "description": "The contract the transaction called (tx_to)."
        },
        "name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Name",
          "description": "Resolved label for that contract, if known."
        }
      },
      "type": "object",
      "required": [
        "address"
      ],
      "title": "TxOriginator"
    }
  }
}