{
  "openapi": "3.0.0",
  "info": {
    "title": "On-Chain Wallet Scoring API",
    "version": "1.0.0",
    "description": "Score blockchain wallet addresses across 6 dimensions: wallet age, transaction activity, protocol diversification, reputation (with flag detection), portfolio balance tier, and DeFi engagement. Returns an overall score (0–100), A+–F grade, trust level, wallet profile, and a credit score equivalent (300–850). Detects 10 suspicious patterns including mixer interactions, sanctioned address contacts, rug pull exposure, wash trading, and flash loan patterns. Supports 9 chains and 25+ DeFi protocols. Fully self-contained — no external blockchain API required."
  },
  "servers": [
    {
      "url": "https://onchain-wallet-scoring.vercel.app"
    }
  ],
  "paths": {
    "/": {
      "get": {
        "summary": "List all endpoints",
        "operationId": "listEndpoints",
        "responses": {
          "200": {
            "description": "Endpoint list"
          }
        }
      }
    },
    "/score": {
      "post": {
        "summary": "Score a wallet across all 6 dimensions",
        "operationId": "scoreWallet",
        "description": "Scores a wallet address across age, activity, diversification, reputation, balance, and DeFi engagement. Returns overall score, grade, trust level, profile type, credit score equivalent, flag detection, and per-dimension breakdowns.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "address": {
                    "type": "string",
                    "description": "Wallet address (for reference — scoring uses provided metrics)"
                  },
                  "chain": {
                    "type": "string",
                    "description": "ethereum|base|arbitrum|optimism|polygon|bsc|avalanche|solana|hyperliquid",
                    "default": "ethereum"
                  },
                  "first_tx_date": {
                    "type": "string",
                    "description": "ISO date of first transaction e.g. '2021-06-15'"
                  },
                  "tx_count": {
                    "type": "integer",
                    "description": "Total lifetime transaction count"
                  },
                  "unique_active_days": {
                    "type": "integer",
                    "description": "Number of unique days with at least one transaction"
                  },
                  "period_days": {
                    "type": "integer",
                    "description": "Observation period in days",
                    "default": 365
                  },
                  "protocols_used": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "DeFi protocol names e.g. ['uniswap','aave','lido']"
                  },
                  "chains_active": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Chains wallet is active on"
                  },
                  "portfolio_usd": {
                    "type": "number",
                    "description": "Total portfolio value in USD"
                  },
                  "native_balance": {
                    "type": "number",
                    "description": "Native token balance (ETH, SOL, etc.)"
                  },
                  "tvl_usd": {
                    "type": "number",
                    "description": "Total value locked in DeFi protocols"
                  },
                  "yield_farming": {
                    "type": "boolean",
                    "description": "Is the wallet actively yield farming?"
                  },
                  "governance_votes": {
                    "type": "integer",
                    "description": "Number of DAO governance votes cast"
                  },
                  "flags_input": {
                    "type": "object",
                    "properties": {
                      "interacted_with_mixers": {
                        "type": "boolean"
                      },
                      "interacted_with_sanctioned": {
                        "type": "boolean"
                      },
                      "rug_pull_tokens": {
                        "type": "integer"
                      },
                      "flash_loan_history": {
                        "type": "boolean"
                      },
                      "rapid_in_out_pattern": {
                        "type": "boolean"
                      },
                      "dust_received": {
                        "type": "boolean"
                      },
                      "honeypot_interactions": {
                        "type": "integer"
                      },
                      "wash_trade_signals": {
                        "type": "boolean"
                      },
                      "phishing_victim": {
                        "type": "boolean"
                      },
                      "high_risk_token_count": {
                        "type": "integer"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Wallet score result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "address": {
                      "type": "string"
                    },
                    "chain": {
                      "type": "string"
                    },
                    "overall": {
                      "type": "object",
                      "properties": {
                        "score": {
                          "type": "number"
                        },
                        "grade": {
                          "type": "string"
                        },
                        "profile": {
                          "type": "string"
                        },
                        "trust_level": {
                          "type": "string"
                        },
                        "recommendation": {
                          "type": "string"
                        }
                      }
                    },
                    "dimensions": {
                      "type": "object"
                    },
                    "flags": {
                      "type": "object"
                    },
                    "protocols": {
                      "type": "array"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/score/batch": {
      "post": {
        "summary": "Score up to 20 wallets in one call",
        "operationId": "scoreBatch",
        "description": "Batch score up to 20 wallets. Returns individual scores, a ranked leaderboard, aggregate stats, and the highest/lowest scoring wallet.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "wallets"
                ],
                "properties": {
                  "wallets": {
                    "type": "array",
                    "maxItems": 20,
                    "items": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch scores and leaderboard"
          }
        }
      }
    },
    "/score/compare": {
      "post": {
        "summary": "Compare 2–5 wallets side by side",
        "operationId": "compareWallets",
        "description": "Scores multiple wallets and returns a ranked comparison with winner, dimension-level differences, and full results for each.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "wallets"
                ],
                "properties": {
                  "wallets": {
                    "type": "array",
                    "minItems": 2,
                    "maxItems": 5,
                    "items": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Comparison with ranking"
          }
        }
      }
    },
    "/score/credit": {
      "post": {
        "summary": "Get DeFi credit score (300–850 scale)",
        "operationId": "creditScore",
        "description": "Scores a wallet and converts the result to a traditional credit score equivalent (300–850) for use in DeFi lending, undercollateralized loans, or credit scoring protocols.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "address": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Credit score result"
          }
        }
      }
    },
    "/flags/check": {
      "post": {
        "summary": "Check a wallet for suspicious activity flags only",
        "operationId": "checkFlags",
        "description": "Runs only the flag detection rules without full scoring. Returns severity-rated flags for AML/compliance screening.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "flags_input"
                ],
                "properties": {
                  "address": {
                    "type": "string"
                  },
                  "flags_input": {
                    "type": "object"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Flag check result"
          }
        }
      }
    },
    "/protocols": {
      "get": {
        "summary": "List all 25+ tracked DeFi protocols",
        "operationId": "listProtocols",
        "responses": {
          "200": {
            "description": "Protocol database"
          }
        }
      }
    },
    "/chains": {
      "get": {
        "summary": "List all 9 supported chains",
        "operationId": "listChains",
        "responses": {
          "200": {
            "description": "Chain data"
          }
        }
      }
    },
    "/flags": {
      "get": {
        "summary": "List all 10 suspicious pattern definitions",
        "operationId": "listFlags",
        "responses": {
          "200": {
            "description": "Flag definitions"
          }
        }
      }
    },
    "/rubric": {
      "get": {
        "summary": "Get scoring rubric and dimension weights",
        "operationId": "getRubric",
        "responses": {
          "200": {
            "description": "Rubric"
          }
        }
      }
    },
    "/openapi": {
      "get": {
        "summary": "OpenAPI specification",
        "operationId": "getOpenApiSpec",
        "responses": {
          "200": {
            "description": "OpenAPI 3.0 JSON"
          }
        }
      }
    }
  }
}