{
  "swagger": "2.0",
  "info": {
    "title": "ChainAware Enterprise API",
    "version": "1.0.2",
    "description": "AI-powered fraud detection, wallet auditing, rug pull screening, user segmentation, and credit scoring for DeFi protocols. All endpoints operate in real time against on-chain data — no off-chain identity or KYC data required.\n\n**Base URL:** `https://enterprise.api.chainaware.ai`\n\n**Authentication:** Pass your API key as the `x-api-key` request header. Get your key at [chainaware.ai/profile](https://chainaware.ai/profile).\n\n**Further reading:**\n- [Fraud Detector Guide](https://chainaware.ai/blog/chainaware-fraud-detector-guide/)\n- [Rug Pull Detector Guide](https://chainaware.ai/blog/chainaware-rugpull-detector-guide/)\n- [Web3 Behavioral User Analytics Guide](https://chainaware.ai/blog/chainaware-web3-behavioral-user-analytics-guide/)\n- [Credit Score Guide](https://chainaware.ai/blog/chainaware-credit-score-the-complete-guide-to-web3-credit-scoring-in-2026/)\n- [Transaction Monitoring Guide](https://chainaware.ai/blog/chainaware-transaction-monitoring-guide/)\n- [12 Blockchain Capabilities Any AI Agent Can Use](https://chainaware.ai/blog/12-blockchain-capabilities-any-ai-agent-can-use-mcp-integration-guide/)"
  },
  "host": "enterprise.api.chainaware.ai",
  "basePath": "/",
  "schemes": ["https"],
  "consumes": ["application/json"],
  "produces": ["application/json"],
  "securityDefinitions": {
    "ApiKeyAuth": {
      "type": "apiKey",
      "in": "header",
      "name": "x-api-key",
      "description": "Your ChainAware API key. Available at chainaware.ai/profile. Keep it private — do not expose it in client-side code or public repositories."
    }
  },
  "security": [
    { "ApiKeyAuth": [] }
  ],
  "paths": {
    "/fraud/check": {
      "post": {
        "summary": "Calculate fraud probability of a wallet address",
        "description": "Returns a fraud probability score for a given wallet address. Use this endpoint for real-time risk gating — for example, at wallet-connect to decide whether to allow or flag a user before they interact with your protocol.\n\n**Response latency:** under 100ms.\n\n**Subscription:** Business or Enterprise.\n\n**Further reading:** [Fraud Detector Guide](https://chainaware.ai/blog/chainaware-fraud-detector-guide/)",
        "tags": ["Fraud API"],
        "parameters": [
          {
            "in": "body",
            "name": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/FraudCheckRequestBody"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Fraud check result",
            "schema": {
              "$ref": "#/definitions/FraudCheckResponse"
            }
          },
          "400": {
            "description": "Bad request — missing or invalid fields in the request body"
          },
          "401": {
            "description": "Unauthorised — API key missing or invalid"
          },
          "404": {
            "description": "Wallet not found"
          },
          "429": {
            "description": "Rate limit exceeded"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
      "/fraud/audit": {
        "post": {
          "summary": "Full behavioural profile and intent prediction for a wallet address",
          "description": "Profiles a wallet's complete on-chain history and predicts what it is likely to do next. Returns wallet categorisation, experience level, intent probabilities, personalisation recommendations, protocol history, and risk profiling.\n\nUse this endpoint to personalise a user's onboarding journey, route wallets to the right product flow, or conduct targeted segmentation.\n\n**Subscription:** Business or Enterprise.\n\n**Supported networks:** `ETH`, `BNB`, `BASE`, `HAQQ`, `SOLANA`.\n\n**Further reading:** [Web3 Behavioral User Analytics Guide](https://chainaware.ai/blog/chainaware-web3-behavioral-user-analytics-guide/)",
          "tags": ["Behaviour Prediction API"],
          "parameters": [
            {
              "in": "body",
              "name": "body",
              "required": true,
              "schema": {
                "$ref": "#/definitions/WalletAuditRequestBody"
              }
            }
          ],
          "responses": {
            "200": {
              "description": "Wallet behavioural profile",
              "schema": {
                "$ref": "#/definitions/WalletAuditResponse"
              }
            },
            "400": {
              "description": "Bad request — missing or invalid fields in the request body"
            },
            "401": {
              "description": "Unauthorised — API key missing or invalid"
            },
            "404": {
              "description": "Wallet not found"
            },
            "429": {
              "description": "Rate limit exceeded"
            },
            "500": {
              "description": "Internal server error"
            }
          }
        }
      },
    "/rug/pull-check": {
      "post": {
        "summary": "Calculate rug pull probability of a contract address",
        "description": "Returns a rug pull probability score for a given contract address. Evaluates the contract itself, the deployer's cross-chain behavioural history, and the behaviour of associated liquidity providers.\n\nUse this endpoint to screen liquidity pools, token contracts, or DeFi protocol contracts before your users interact with them — or to power a rug pull alert feature in your product.\n\nChainAware's rug pull model achieves **90% accuracy on new pools**, detecting preparation patterns before a documented rug event occurs.\n\n**Subscription:** Business or Enterprise.\n\n**Supported networks:** `ETH`, `BNB`, `BASE`, `HAQQ`.\n\n**Further reading:** [Rug Pull Detector Guide](https://chainaware.ai/blog/chainaware-rugpull-detector-guide/)",
        "tags": ["Fraud API"],
        "parameters": [
          {
            "in": "body",
            "name": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/RugPullRequestBody"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Rug pull check result",
            "schema": {
              "$ref": "#/definitions/RugPullResponse"
            }
          },
          "400": {
            "description": "Bad request — missing or invalid fields in the request body"
          },
          "401": {
            "description": "Unauthorised — API key missing or invalid"
          },
          "404": {
            "description": "Contract not found"
          },
          "429": {
            "description": "Rate limit exceeded"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/segmentation/wallet-segment": {
      "post": {
        "summary": "Get wallet behaviour segment and quality score",
        "description": "Classifies a wallet address into a quality segment (A, B, or C) based on its on-chain behaviour history, and returns a 0–100 quality score for finer-grained ranking.\n\nUse this endpoint to distinguish high-value users from low-value or low-intent users at the moment they connect to your protocol — without requiring any off-chain identity data.\n\n**Subscription:** Enterprise.\n\n**Supported networks:** `ETH`, `BNB`, `BASE`, `HAQQ`, `SOLANA` .\n\n**Further reading:** [Web3 Behavioral User Analytics Guide](https://chainaware.ai/blog/chainaware-web3-behavioral-user-analytics-guide/)",
        "tags": ["Behaviour Prediction API"],
        "parameters": [
          {
            "in": "body",
            "name": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/WalletSegmentRequestBody"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Wallet segment and quality score",
            "schema": {
              "$ref": "#/definitions/WalletSegmentResponse"
            }
          },
          "400": {
            "description": "Bad request — missing or invalid fields in the request body"
          },
          "401": {
            "description": "Unauthorised — API key missing or invalid"
          },
          "404": {
            "description": "Wallet not found"
          },
          "429": {
            "description": "Rate limit exceeded"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/users/credit-score": {
      "post": {
        "summary": "Get AI-driven crypto trust score for a wallet address",
        "description": "Returns an AI-driven crypto trust score (1–9) for any wallet address, combining on-chain inflow/outflow analysis, fraud probability, and social graph signals. Designed for DeFi lending protocols that need to differentiate reliable borrowers from high-risk wallets before originating loans — without requiring identity data.\n\n**Response latency:** under 100ms.\n\n**Subscription:** Enterprise.\n\n**Supported networks:** `ETH`, `BNB`, `POLYGON`, `TON`, `BASE`, `HAQQ`.\n\n**Further reading:** [Credit Score Guide](https://chainaware.ai/blog/chainaware-credit-score-the-complete-guide-to-web3-credit-scoring-in-2026/)",
        "tags": ["Credit Score API"],
        "parameters": [
          {
            "in": "body",
            "name": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/CreditScoreRequestBody"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Credit score result",
            "schema": {
              "$ref": "#/definitions/CreditScoreResponse"
            }
          },
          "400": {
            "description": "Bad request — missing or invalid fields in the request body"
          },
          "401": {
            "description": "Unauthorised — API key missing or invalid"
          },
          "404": {
            "description": "Wallet not found"
          },
          "429": {
            "description": "Rate limit exceeded"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    }
  },
  "definitions": {
    "FraudCheckRequestBody": {
      "type": "object",
      "required": ["network", "walletAddress"],
      "properties": {
        "network": {
          "type": "string",
          "description": "Blockchain network to query.",
          "enum": ["ETH", "BNB","POLYGON","TON","BASE", "TRON", "HAQQ"],
          "example": "ETH"
        },
        "walletAddress": {
          "type": "string",
          "description": "The wallet address to screen.",
          "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
        },
        "calculate": {
          "type": "boolean",
          "description": "Boolean indicating whether to perform a full realtime recalculation",
          "example": false
        }
      }
    },
    "FraudCheckResponse": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string",
          "description": "Result status message.",
          "example": "Success"
        },

        "walletAddress": {
          "type": "string",
          "description": "Blockchain wallet address analyzed.",
          "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
        },

        "chain": {
          "type": "string",
          "description": "Blockchain network identifier.",
          "example": "ETH"
        },

        "status": {
          "type": "string",
          "description": "Risk classification of the wallet.",
          "enum": ["Not Fraud", "Fraud", "New Address"],
          "example": "Not Fraud"
        },

        "probabilityFraud": {
          "type": "string",
          "description": "Fraud probability score between 0.00 and 1.00, returned as string to preserve precision.",
          "example": "0.0421858616"
        },

        "token": {
          "type": "string",
          "nullable": true,
          "description": "Optional token associated with the wallet analysis.",
          "example": null
        },

        "lastChecked": {
          "type": "string",
          "format": "date-time",
          "description": "Last time the wallet fraud analysis was executed.",
          "example": "2026-02-20T14:05:17.000Z"
        },

        "forensic_details": {
          "type": "object",
          "description": "Forensic indicators contributing to fraud classification.",
          "properties": {
            "cybercrime": {
              "type": "string",
              "example": "0"
            },
            "money_laundering": {
              "type": "string",
              "example": "0"
            },
            "number_of_malicious_contracts_created": {
              "type": "string",
              "example": "0"
            },
            "gas_abuse": {
              "type": "string",
              "example": "0"
            },
            "financial_crime": {
              "type": "string",
              "example": "0"
            },
            "darkweb_transactions": {
              "type": "string",
              "example": "0"
            },
            "reinit": {
              "type": "string",
              "example": "0"
            },
            "phishing_activities": {
              "type": "string",
              "example": "0"
            },
            "fake_kyc": {
              "type": "string",
              "example": "0"
            },
            "blacklist_doubt": {
              "type": "string",
              "example": "0"
            },
            "fake_standard_interface": {
              "type": "string",
              "example": "0"
            },
            "data_source": {
              "type": "string",
              "example": ""
            },
            "stealing_attack": {
              "type": "string",
              "example": "0"
            },
            "blackmail_activities": {
              "type": "string",
              "example": "0"
            },
            "sanctioned": {
              "type": "string",
              "example": "0"
            },
            "malicious_mining_activities": {
              "type": "string",
              "example": "0"
            },
            "mixer": {
              "type": "string",
              "example": "0"
            },
            "fake_token": {
              "type": "string",
              "example": "0"
            },
            "honeypot_related_address": {
              "type": "string",
              "example": "0"
            }
          }
        },

        "checked_times": {
          "type": "integer",
          "description": "Number of times this wallet has been analyzed.",
          "example": 2134
        },

        "createdAt": {
          "type": "string",
          "format": "date-time",
          "description": "Record creation timestamp.",
          "example": "2023-10-12T11:46:55.000Z"
        },

        "updatedAt": {
          "type": "string",
          "format": "date-time",
          "description": "Last update timestamp.",
          "example": "2026-03-09T12:45:19.000Z"
        },

        "sanctionData": {
          "type": "array",
          "description": "Sanctions intelligence associated with this wallet.",
          "items": {
            "type": "object",
            "properties": {
              "category": {
                "type": "string",
                "nullable": true,
                "example": null
              },
              "name": {
                "type": "string",
                "nullable": true,
                "example": null
              },
              "description": {
                "type": "string",
                "nullable": true,
                "example": null
              },
              "url": {
                "type": "string",
                "nullable": true,
                "example": null
              },
              "isSanctioned": {
                "type": "boolean",
                "example": false
              },
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "example": "2026-03-09T12:45:19.000Z"
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2026-03-09T12:45:19.000Z"
              }
            }
          }
        }
      }
    },
    "WalletAuditRequestBody": {
      "type": "object",
      "required": ["network", "walletAddress"],
      "properties": {
        "network": {
          "type": "string",
          "description": "Blockchain network to query.",
          "enum": ["ETH", "BNB", "BASE", "HAQQ", "SOLANA"],
          "example": "ETH"
        },
        "walletAddress": {
          "type": "string",
          "description": "The wallet address to profile.",
          "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
        },
        "calculate": {
          "type": "boolean",
          "description": "Boolean indicating whether to perform a full realtime recalculation",
          "example": false
        }
      }
    },
    "WalletAuditResponse": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string",
          "description": "Result status message.",
          "example": "Success"
        },

        "walletAddress": {
          "type": "string",
          "description": "Blockchain wallet address analyzed.",
          "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
        },

        "status": {
          "type": "string",
          "description": "Fraud classification of the wallet.",
          "enum": ["Not Fraud", "Fraud", "New Address"],
          "example": "Not Fraud"
        },

        "probabilityFraud": {
          "type": "string",
          "description": "Fraud probability score between 0.00 and 1.00 returned as string for precision preservation.",
          "example": "0.0421858616"
        },

        "token": {
          "type": "string",
          "nullable": true,
          "description": "Optional token context associated with the wallet analysis.",
          "example": null
        },

        "chain": {
          "type": "string",
          "description": "Blockchain network identifier.",
          "example": "ETH"
        },

        "lastChecked": {
          "type": "string",
          "format": "date-time",
          "description": "Last time the wallet analysis was executed.",
          "example": "2026-02-20T14:05:17.000Z"
        },

        "forensic_details": {
          "type": "object",
          "description": "Forensic indicators contributing to fraud scoring.",
          "properties": {
            "cybercrime": { "type": "string", "example": "0" },
            "money_laundering": { "type": "string", "example": "0" },
            "number_of_malicious_contracts_created": { "type": "string", "example": "0" },
            "gas_abuse": { "type": "string", "example": "0" },
            "financial_crime": { "type": "string", "example": "0" },
            "darkweb_transactions": { "type": "string", "example": "0" },
            "reinit": { "type": "string", "example": "0" },
            "phishing_activities": { "type": "string", "example": "0" },
            "fake_kyc": { "type": "string", "example": "0" },
            "blacklist_doubt": { "type": "string", "example": "0" },
            "fake_standard_interface": { "type": "string", "example": "0" },
            "data_source": { "type": "string", "example": "" },
            "stealing_attack": { "type": "string", "example": "0" },
            "blackmail_activities": { "type": "string", "example": "0" },
            "sanctioned": { "type": "string", "example": "0" },
            "malicious_mining_activities": { "type": "string", "example": "0" },
            "mixer": { "type": "string", "example": "0" },
            "fake_token": { "type": "string", "example": "0" },
            "honeypot_related_address": { "type": "string", "example": "0" }
          }
        },

        "categories": {
          "type": "array",
          "description": "Wallet activity categories grouped by behavioral domain.",
          "items": {
            "type": "object",
            "properties": {
              "Category": {
                "type": "string",
                "example": "DeFi"
              },
              "Count": {
                "type": "integer",
                "example": 126
              }
            }
          }
        },

        "riskProfile": {
          "type": "array",
          "description": "Balance-age weighted exposure by category and risk distribution.",
          "items": {
            "type": "object",
            "properties": {
              "Category": {
                "type": "string",
                "example": "Risk_Profile"
              },
              "Balance_age": {
                "type": "number",
                "format": "float",
                "example": 3
              }
            }
          }
        },

        "segmentInfo": {
          "type": "string",
          "description": "Serialized JSON containing protocol engagement flags.",
          "example": "{\"Maker\":0,\"Aave_borrow\":0,\"Aave_lend\":1,\"Lido\":0,\"Uniswap\":1}"
        },

        "experience": {
          "type": "object",
          "description": "Wallet experience score derived from protocol diversity and longevity.",
          "properties": {
            "Type": {
              "type": "string",
              "example": "Experience"
            },
            "Value": {
              "type": "integer",
              "example": 10
            }
          }
        },

        "intention": {
          "type": "object",
          "description": "Predicted wallet behavioral intentions.",
          "properties": {
            "Type": {
              "type": "string",
              "example": "Intentions"
            },
            "Value": {
              "type": "object",
              "properties": {
                "Prob_Lend": { "type": "string", "example": "High" },
                "Prob_Trade": { "type": "string", "example": "High" },
                "Prob_Game": { "type": "string", "example": "Medium" },
                "Prob_NFT": { "type": "string", "example": "Medium" },
                "Prob_Stake_ETH": { "type": "string", "example": "Medium" },
                "Prob_Borrow": { "type": "string", "example": "Low" },
                "Prob_Gamble": { "type": "string", "example": "Low" },
                "Prob_Stake": { "type": "string", "example": "Low" },
                "Prob_Yield_Farm": { "type": "string", "example": "Low" },
                "Prob_Leveraged_Stake": { "type": "string", "example": "Low" },
                "Prob_Leveraged_Stake_ETH": { "type": "string", "example": "Low" },
                "Prob_Leveraged_Lend": { "type": "string", "example": "Low" },
                "Prob_Leverage_Long_ETH": { "type": "string", "example": "Low" },
                "Prob_Leverage_Long": { "type": "string", "example": "Low" }
              }
            }
          }
        },

        "protocols": {
          "type": "array",
          "description": "Protocols the wallet has interacted with.",
          "items": {
            "type": "object",
            "properties": {
              "Protocol": {
                "type": "string",
                "example": "uniswap"
              },
              "Count": {
                "type": "integer",
                "example": 25
              }
            }
          }
        },

        "userDetails": {
          "type": "object",
          "description": "Core wallet metrics.",
          "properties": {
            "wallet_age_days": {
              "type": "integer",
              "example": 3798
            },
            "total_balance_usd": {
              "type": "number",
              "format": "float",
              "example": 104859.49
            },
            "transaction_count": {
              "type": "integer",
              "example": 19972
            },
            "wallet_rank": {
              "type": "integer",
              "example": 20042
            }
          }
        },

        "riskCapability": {
          "type": "integer",
          "description": "Wallet risk capability score.",
          "example": 5
        },

        "recommendation": {
          "type": "object",
          "description": "Recommended investment or product fit suggestions.",
          "properties": {
            "Type": {
              "type": "string",
              "example": "Recommendation"
            },
            "Value": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "example": [
                "WBTC holding",
                "ETH holding",
                "Stablecoin lending"
              ]
            }
          }
        },

        "checked_times": {
          "type": "integer",
          "description": "Number of times wallet analysis has been executed.",
          "example": 2135
        },

        "createdAt": {
          "type": "string",
          "format": "date-time",
          "example": "2023-10-12T11:46:55.000Z"
        },

        "updatedAt": {
          "type": "string",
          "format": "date-time",
          "example": "2026-03-12T16:01:17.000Z"
        },

        "sanctionData": {
          "type": "array",
          "description": "Sanctions intelligence associated with this wallet.",
          "items": {
            "type": "object",
            "properties": {
              "category": {
                "type": "string",
                "nullable": true,
                "example": null
              },
              "name": {
                "type": "string",
                "nullable": true,
                "example": null
              },
              "description": {
                "type": "string",
                "nullable": true,
                "example": null
              },
              "url": {
                "type": "string",
                "nullable": true,
                "example": null
              },
              "isSanctioned": {
                "type": "boolean",
                "example": false
              },
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "example": "2026-03-12T16:01:18.000Z"
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2026-03-12T16:01:18.000Z"
              }
            }
          }
        }
      }
    },
    "RugPullRequestBody": {
      "type": "object",
      "required": ["network", "walletAddress"],
      "properties": {
        "network": {
          "type": "string",
          "description": "Blockchain network to query.",
          "enum": ["ETH", "BNB", "BASE", "HAQQ"],
          "example": "ETH"
        },
        "walletAddress": {
          "type": "string",
          "description": "The smart contract or liquidity pool address to screen. To check a wallet address instead, use `/fraud/check`.",
          "example": "0xContractAddressHere"
        }
      }
    },
    "RugPullResponse": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string",
          "description": "Result status message.",
          "example": "Success"
        },

        "contractAddress": {
          "type": "string",
          "description": "Smart contract address analyzed.",
          "example": "0x91dba2cd05c8a0227b48c3e426077145d23b21df"
        },

        "pairAddress": {
          "type": "string",
          "description": "Liquidity pair address on decentralized exchange.",
          "example": "0x290dd1e2e1856841b4ee4be8fd1aba51011c12e9"
        },

        "contractCreatorAddress": {
          "type": "string",
          "nullable": true,
          "description": "Creator address of the contract if available.",
          "example": null
        },

        "risk_score": {
          "type": "integer",
          "description": "Internal numerical contract risk score.",
          "example": 2
        },

        "risk_status": {
          "type": "string",
          "description": "Qualitative risk classification based on internal scoring.",
          "example": "Low Risk"
        },

        "risk_indicators": {
          "type": "object",
          "description": "Static smart contract security indicators used during contract analysis.",
          "properties": {
            "is_honeypot": { "type": "integer", "example": 0 },
            "honeypot_with_same_creator": { "type": "integer", "example": 0 },
            "can_take_back_ownership": { "type": "integer", "example": 0 },
            "is_mintable": { "type": "integer", "example": 0 },
            "hidden_owner": { "type": "integer", "example": 0 },

            "buy_tax": { "type": "integer", "example": 0 },
            "sell_tax": { "type": "integer", "example": 0 },

            "cannot_buy": { "type": "integer", "example": 0 },
            "cannot_sell_all": { "type": "integer", "example": 0 },

            "is_blacklisted": { "type": "integer", "example": 0 },
            "is_whitelisted": { "type": "integer", "example": 0 },

            "creator_percent": { "type": "integer", "example": 0 },
            "lp_holders_locked": { "type": "boolean", "example": false },

            "liquidity": {
              "type": "number",
              "format": "float",
              "description": "Current liquidity amount in base token.",
              "example": 14.38
            },

            "market_cap": {
              "type": "number",
              "description": "Estimated token market capitalization.",
              "example": 2062
            },

            "is_in_dex": { "type": "integer", "example": 1 },

            "slippage_modifiable": { "type": "integer", "example": 0 },
            "transfer_pausable": { "type": "integer", "example": 0 },
            "is_anti_whale": { "type": "integer", "example": 0 },
            "anti_whale_modifiable": { "type": "integer", "example": 0 },

            "trading_cooldown": { "type": "integer", "example": 0 },
            "personal_slippage_modifiable": { "type": "integer", "example": 0 },

            "is_open_source": { "type": "integer", "example": 1 },
            "is_proxy": { "type": "integer", "example": 0 },

            "owner_address": {
              "type": "string",
              "example": ""
            },

            "owner_change_balance": { "type": "integer", "example": 0 },
            "selfdestruct": { "type": "integer", "example": 0 },
            "external_call": { "type": "integer", "example": 0 },
            "gas_abuse": { "type": "integer", "example": 0 }
          }
        },

        "liquidityEvent": {
          "type": "array",
          "description": "Recent liquidity-related events associated with the token pool.",
          "items": {
            "type": "object",
            "properties": {
              "eventType": {
                "type": "string",
                "example": "remove"
              },
              "amount": {
                "type": "number",
                "format": "float",
                "example": 1.60228
              },
              "token": {
                "type": "string",
                "example": "wbnb"
              },
              "tx_hash": {
                "type": "string",
                "example": "0xed0a492f9e8021fd74a950237703ea0047223b4bd4c032810e02734c407e624a"
              },
              "from_address": {
                "type": "string",
                "example": "0x983fd7447391bae599ac38ea06cd9d60c89fbb66"
              },
              "from_fraud_probability": {
                "type": "number",
                "format": "float",
                "example": 1
              },
              "from_fraud_status": {
                "type": "string",
                "example": "Fraud"
              },
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "example": "2026-01-02T11:31:22.000Z"
              }
            }
          }
        },

        "status": {
          "type": "string",
          "description": "Overall fraud classification of the contract.",
          "enum": ["Not Fraud", "Fraud"],
          "example": "Fraud"
        },

        "probabilityFraud": {
          "type": "number",
          "format": "float",
          "description": "Fraud probability score between 0.00 and 1.00.",
          "example": 0.8350795507
        },

        "chain": {
          "type": "string",
          "description": "Blockchain network identifier.",
          "example": "BNB"
        },

        "lastChecked": {
          "type": "string",
          "format": "date-time",
          "description": "Last analysis execution timestamp.",
          "example": "2026-02-14T13:57:01.000Z"
        },

        "contractCreationTime": {
          "type": "string",
          "nullable": true,
          "format": "date-time",
          "description": "Smart contract deployment timestamp if available.",
          "example": null
        },

        "forensic_details": {
          "type": "object",
          "description": "Dynamic forensic indicators contributing to fraud probability.",
          "properties": {
            "owner": {
              "type": "object"
            },
            "privilege_withdraw": { "type": "integer", "example": 0 },
            "withdraw_missing": { "type": "integer", "example": 0 },
            "is_open_source": { "type": "integer", "example": 1 },
            "blacklist": { "type": "integer", "example": 0 },
            "contract_name": {
              "type": "string",
              "example": "PAPUToken"
            },
            "selfdestruct": { "type": "integer", "example": 0 },
            "is_proxy": { "type": "integer", "example": 0 },
            "approval_abuse": { "type": "integer", "example": 0 }
          }
        },

        "checked_times": {
          "type": "integer",
          "description": "Number of times this contract has been analyzed.",
          "example": 1
        },

        "createdAt": {
          "type": "string",
          "format": "date-time",
          "description": "Record creation timestamp.",
          "example": "2024-05-31T00:42:51.000Z"
        },

        "updatedAt": {
          "type": "string",
          "format": "date-time",
          "description": "Most recent record update timestamp.",
          "example": "2026-03-03T10:44:35.000Z"
        }
      }
    },
    "WalletSegmentRequestBody": {
      "type": "object",
      "required": ["walletAddress", "network"],
      "properties": {
        "walletAddress": {
          "type": "string",
          "description": "The wallet address to classify.",
          "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
        },
        "network": {
          "type": "string",
          "description": "Blockchain network to query.",
          "enum": ["ETH", "BNB", "BASE", "HAQQ", "SOLANA"],
          "example": "ETH"
        }
      }
    },
    "WalletSegmentResponse": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string",
          "description": "Result status message.",
          "example": "Wallet segment retrieved"
        },

        "walletAddress": {
          "type": "string",
          "description": "Blockchain wallet address analyzed.",
          "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
        },

        "walletQuality": {
          "type": "integer",
          "description": "Calculated wallet quality score from 0 to 100 derived from segment, protocol diversity, balance history, and wallet behavior.",
          "example": 87
        },

        "categories": {
          "type": "array",
          "description": "Wallet activity categories grouped by interaction domain.",
          "items": {
            "type": "object",
            "properties": {
              "Category": {
                "type": "string",
                "example": "DeFi"
              },
              "Count": {
                "type": "integer",
                "example": 142
              }
            }
          }
        },

        "riskProfile": {
          "type": "array",
          "description": "Balance-age weighted willingness-to-take-risk indicators.",
          "items": {
            "type": "object",
            "properties": {
              "Category": {
                "type": "string",
                "example": "Risk_Profile"
              },
              "Balance_age": {
                "type": "number",
                "format": "float",
                "example": 4
              }
            }
          }
        },

        "segmentInfo": {
          "type": "string",
          "description": "Serialized JSON containing protocol engagement flags used for segment classification.",
          "example": "{\"Maker\":0,\"Aave_borrow\":0,\"Aave_lend\":1,\"Lido\":0,\"Uniswap\":1}"
        },

        "experience": {
          "type": "object",
          "description": "Wallet experience score based on protocol depth and activity maturity.",
          "properties": {
            "Type": {
              "type": "string",
              "example": "Experience"
            },
            "Value": {
              "type": "integer",
              "example": 10
            }
          }
        },

        "intention": {
          "type": "object",
          "description": "Predicted next wallet actions.",
          "properties": {
            "Type": {
              "type": "string",
              "example": "Intentions"
            },
            "Value": {
              "type": "object",
              "properties": {
                "Prob_Lend": { "type": "string", "example": "High" },
                "Prob_Trade": { "type": "string", "example": "High" },
                "Prob_Game": { "type": "string", "example": "Medium" },
                "Prob_NFT": { "type": "string", "example": "Low" },
                "Prob_Stake_ETH": { "type": "string", "example": "Medium" },
                "Prob_Borrow": { "type": "string", "example": "Low" },
                "Prob_Gamble": { "type": "string", "example": "Low" },
                "Prob_Stake": { "type": "string", "example": "Medium" },
                "Prob_Yield_Farm": { "type": "string", "example": "Low" },
                "Prob_Leveraged_Stake": { "type": "string", "example": "Low" },
                "Prob_Leveraged_Stake_ETH": { "type": "string", "example": "Low" },
                "Prob_Leveraged_Lend": { "type": "string", "example": "Low" },
                "Prob_Leverage_Long_ETH": { "type": "string", "example": "Low" },
                "Prob_Leverage_Long": { "type": "string", "example": "Low" }
              }
            }
          }
        },

        "protocols": {
          "type": "array",
          "description": "Protocols the wallet has interacted with ordered by usage frequency.",
          "items": {
            "type": "object",
            "properties": {
              "Protocol": {
                "type": "string",
                "example": "uniswap"
              },
              "Count": {
                "type": "integer",
                "example": 34
              }
            }
          }
        },

        "userDetails": {
          "type": "object",
          "description": "Core wallet metrics used for segmentation.",
          "properties": {
            "wallet_age_days": {
              "type": "integer",
              "example": 3798
            },
            "total_balance_usd": {
              "type": "number",
              "format": "float",
              "example": 104859.49
            },
            "transaction_count": {
              "type": "integer",
              "example": 19972
            },
            "wallet_rank": {
              "type": "integer",
              "example": 20042
            }
          }
        },

        "recommendation": {
          "type": "object",
          "description": "Product fit or engagement recommendations based on wallet segment.",
          "properties": {
            "Type": {
              "type": "string",
              "example": "Recommendation"
            },
            "Value": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "example": [
                "WBTC holding",
                "ETH holding",
                "Stablecoin lending"
              ]
            }
          }
        },

        "sanctionData": {
          "type": "array",
          "description": "Sanctions screening associated with this wallet.",
          "items": {
            "type": "object",
            "properties": {
              "category": {
                "type": "string",
                "nullable": true,
                "example": null
              },
              "name": {
                "type": "string",
                "nullable": true,
                "example": null
              },
              "description": {
                "type": "string",
                "nullable": true,
                "example": null
              },
              "url": {
                "type": "string",
                "nullable": true,
                "example": null
              },
              "isSanctioned": {
                "type": "boolean",
                "example": false
              },
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "example": "2026-03-12T16:01:18.000Z"
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2026-03-12T16:01:18.000Z"
              }
            }
          }
        }
      }
    },
    "CreditScoreRequestBody": {
      "type": "object",
      "required": ["network", "walletAddress"],
      "properties": {
        "network": {
          "type": "string",
          "description": "Blockchain network to query.",
          "enum": ["ETH"],
          "example": "ETH"
        },
        "walletAddress": {
          "type": "string",
          "description": "The wallet address to score.",
          "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
        }
      }
    },
    "CreditScoreResponse": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string",
          "description": "Result status message.",
          "example": "Success"
        },
        "creditData": {
          "type": "object",
          "properties": {
            "walletAddress": {
              "type": "string",
              "description": "The queried wallet address.",
              "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
            },
            "riskRating": {
              "type": "integer",
              "description": "AI-driven crypto trust score from 1 (lowest trust) to 9 (highest trust). Combines on-chain inflow/outflow analysis, fraud probability, and social graph signals. Score guidance: 8–9 high trust, 6–7 above average, 4–5 average, 2–3 below average, 1 low trust.",
              "minimum": 1,
              "maximum": 9,
              "example": 7
            }
          }
        }
      }
    }
  }
}