{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/cleartracedata-com/json-schema/cleartracedata-com-address-attribution-response-schema.json",
  "title": "AddressAttributionResponse",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/cleartracedata-com-openapi.yml#/components/schemas/AddressAttributionResponse",
  "properties": {
    "address": {
      "type": "string",
      "title": "Address",
      "description": "The queried address (lower-cased)."
    },
    "records": {
      "items": {
        "$ref": "#/$defs/AddressAttributionRecord"
      },
      "type": "array",
      "title": "Records",
      "description": "Per-chain attribution breakdown for this address, largest volume first."
    },
    "total_volume_usd": {
      "type": "number",
      "title": "Total Volume Usd",
      "description": "Total attributed volume for this address summed across all returned chains."
    },
    "chains_found": {
      "type": "integer",
      "title": "Chains Found",
      "description": "Number of chains on which this address has attributed volume."
    }
  },
  "type": "object",
  "required": [
    "address",
    "records",
    "total_volume_usd",
    "chains_found"
  ],
  "$defs": {
    "AddressAttributionRecord": {
      "properties": {
        "chain": {
          "type": "string",
          "title": "Chain",
          "description": "The blockchain network."
        },
        "resolved_contract_name": {
          "type": "string",
          "title": "Resolved Contract Name",
          "description": "The name the attribution engine assigned this address (often 'Unknown Proxy/Frontend (0x…)' for unlabeled contracts)."
        },
        "label": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Label",
          "description": "Human-readable label from the auto-labeling pipeline, if one exists for this address+chain."
        },
        "entity_type": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Entity Type",
          "description": "Classification from the labeling pipeline: token, router_or_proxy, contract, eoa, or delegated_eoa (EIP-7702)."
        },
        "label_source": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Label Source",
          "description": "Where the label came from (nansen, arkham, etherscan, alchemy-*)."
        },
        "confidence": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Confidence",
          "description": "Label confidence: high, medium, or low."
        },
        "total_volume_usd": {
          "type": "number",
          "title": "Total Volume Usd",
          "description": "Total USD volume attributed to this address on this chain. This is the sum of the four PARTITION columns (`aggregator_partner_volume_usd`, `aggregator_volume_usd`, `direct_volume_usd`, `proxy_volume_usd`) and deliberately EXCLUDES the overlay columns (`calldata_suffix_volume_usd`, `erc20_fee_volume_usd`), so summing every volume field double-counts."
        },
        "aggregator_partner_volume_usd": {
          "type": "number",
          "title": "Aggregator Partner Volume Usd",
          "description": "Volume explicitly tagged with an aggregator partner code."
        },
        "aggregator_volume_usd": {
          "type": "number",
          "title": "Aggregator Volume Usd",
          "description": "Standard aggregator volume."
        },
        "calldata_suffix_volume_usd": {
          "type": "number",
          "title": "Calldata Suffix Volume Usd",
          "description": "Volume attributed via calldata suffix fingerprinting. OVERLAY, not a component of `total_volume_usd`: it re-describes dollars already counted in the partition columns, seen through a different attribution vector, and is deliberately excluded from the total. It may therefore EXCEED `total_volume_usd`, which is correct and not a bug. Never add it to a partition column: that double-counts."
        },
        "direct_volume_usd": {
          "type": "number",
          "title": "Direct Volume Usd",
          "description": "Volume routed directly to DEX pools."
        },
        "erc20_fee_volume_usd": {
          "type": "number",
          "title": "Erc20 Fee Volume Usd",
          "description": "Volume attributed via secondary fee transfers: the fee-kickback vector credits the full trade amount to every intermediate transfer recipient in a transaction, so pools, vaults and multisigs accumulate large figures without being swap venues. OVERLAY, not a component of `total_volume_usd`: it re-describes dollars already counted in the partition columns, seen through a different attribution vector, and is deliberately excluded from the total. It may therefore EXCEED `total_volume_usd`, which is correct and not a bug. Never add it to a partition column: that double-counts."
        },
        "proxy_volume_usd": {
          "type": "number",
          "title": "Proxy Volume Usd",
          "description": "Volume routed through an unverified proxy before hitting DEX pools."
        }
      },
      "type": "object",
      "required": [
        "chain",
        "resolved_contract_name",
        "total_volume_usd",
        "aggregator_partner_volume_usd",
        "aggregator_volume_usd",
        "calldata_suffix_volume_usd",
        "direct_volume_usd",
        "erc20_fee_volume_usd",
        "proxy_volume_usd"
      ],
      "title": "AddressAttributionRecord"
    }
  }
}