Verdict

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/hostdefi/json-schema/hostdefi-verdict-schema.json",
  "title": "Verdict",
  "description": "The graded Safety Read for one token — identical to the grade rendered on the HostDeFi token pages.",
  "x-generated": "2026-11-09",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/hostdefi-token-risk-api-openapi.yml#/components/schemas/Verdict",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    },
    "token": {
      "type": "object",
      "properties": {
        "chain": {
          "type": [
            "string",
            "null"
          ],
          "description": "Resolved chain id (e.g. solana, ethereum), or null if undeterminable."
        },
        "address": {
          "type": "string"
        },
        "name": {
          "type": [
            "string",
            "null"
          ]
        },
        "symbol": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    },
    "risk": {
      "$ref": "#/$defs/RiskBlock"
    },
    "signals": {
      "description": "Chain-dependent raw signals behind the grade.",
      "oneOf": [
        {
          "$ref": "#/$defs/SolanaSignals"
        },
        {
          "$ref": "#/$defs/EvmSignals"
        }
      ]
    },
    "meta": {
      "type": "object",
      "properties": {
        "checkedAt": {
          "type": "string",
          "format": "date-time"
        },
        "sources": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "geckoterminal",
              "verixia-onchain",
              "goplus"
            ]
          }
        },
        "partial": {
          "type": "boolean",
          "description": "True when the chain's security/authority source was unavailable and the verdict degraded rather than blocked."
        },
        "plan": {
          "type": "string",
          "description": "free, or the calling key's plan id (week/month/year). Not set on batch items (the batch envelope carries it)."
        },
        "remaining": {
          "type": "integer",
          "description": "Calls remaining on the caller's tier. Not set on batch items."
        }
      }
    }
  },
  "$defs": {
    "EvmSignals": {
      "type": "object",
      "description": "EVM signal set (present when the token resolved to an EVM chain). `evmSecurity` is always emitted (all-null flags when the security source was unavailable) and is what distinguishes this branch from SolanaSignals.",
      "required": [
        "evmSecurity"
      ],
      "properties": {
        "market": {
          "$ref": "#/$defs/MarketSignals"
        },
        "evmSecurity": {
          "type": "object",
          "description": "Contract security flags. Null = the check could not be evaluated.",
          "properties": {
            "honeypot": {
              "type": [
                "boolean",
                "null"
              ]
            },
            "buyTaxPct": {
              "type": [
                "integer",
                "null"
              ]
            },
            "sellTaxPct": {
              "type": [
                "integer",
                "null"
              ]
            },
            "mintable": {
              "type": [
                "boolean",
                "null"
              ]
            },
            "pausable": {
              "type": [
                "boolean",
                "null"
              ]
            },
            "blacklist": {
              "type": [
                "boolean",
                "null"
              ]
            },
            "proxy": {
              "type": [
                "boolean",
                "null"
              ]
            },
            "hiddenOwner": {
              "type": [
                "boolean",
                "null"
              ]
            },
            "openSource": {
              "type": [
                "boolean",
                "null"
              ]
            }
          }
        }
      }
    },
    "MarketSignals": {
      "type": "object",
      "properties": {
        "liquidityUsd": {
          "type": [
            "number",
            "null"
          ]
        },
        "volume24h": {
          "type": [
            "number",
            "null"
          ]
        },
        "priceUsd": {
          "type": [
            "number",
            "null"
          ]
        }
      }
    },
    "RiskBlock": {
      "type": "object",
      "description": "Graded verdict, or an honest refusal to grade (`graded: false`) when the token is too new or under-described — the API never fakes a grade.",
      "properties": {
        "graded": {
          "type": "boolean"
        },
        "score": {
          "type": [
            "integer",
            "null"
          ],
          "minimum": 0,
          "maximum": 97,
          "description": "Safety score, higher is safer. The engine clamps emitted scores to 2–97 (a perfect score is unreachable by design). Null when ungraded."
        },
        "grade": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "A+",
            "A",
            "B",
            "C",
            "D",
            "F",
            null
          ],
          "description": "Letter grade band over the score (A+ ≥ 90, A ≥ 82, B ≥ 72, C ≥ 60, D ≥ 35, else F)."
        },
        "tier": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "low",
            "med",
            "high",
            null
          ],
          "description": "Risk tier: low (A+/A/B), med (C), high (D/F)."
        },
        "verdict": {
          "type": [
            "string",
            "null"
          ],
          "description": "Deterministic one-paragraph verdict prose (no LLM involved)."
        },
        "knowns": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Verified facts the grade rests on."
        },
        "unknowns": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Checks that could not be verified."
        },
        "notGradedReason": {
          "type": [
            "string",
            "null"
          ],
          "description": "Why no grade was emitted (only when graded is false)."
        }
      }
    },
    "SolanaSignals": {
      "type": "object",
      "description": "Solana signal set (present when the token resolved to Solana). `authorities` is always emitted (null-valued when the on-chain read was unavailable) and is what distinguishes this branch from EvmSignals.",
      "required": [
        "authorities"
      ],
      "properties": {
        "authorities": {
          "type": "object",
          "properties": {
            "mintDisabled": {
              "type": [
                "boolean",
                "null"
              ]
            },
            "freezeDisabled": {
              "type": [
                "boolean",
                "null"
              ]
            }
          }
        },
        "token2022Extensions": {
          "type": "object",
          "description": "Token-2022 trap flags. All false for classic SPL tokens.",
          "properties": {
            "transferFee": {
              "type": "boolean"
            },
            "defaultAccountState": {
              "type": "boolean"
            },
            "nonTransferable": {
              "type": "boolean"
            },
            "permanentDelegate": {
              "type": "boolean"
            },
            "transferHook": {
              "type": "boolean"
            },
            "pausable": {
              "type": "boolean"
            }
          }
        },
        "holders": {
          "type": "object",
          "properties": {
            "top10Pct": {
              "type": [
                "number",
                "null"
              ],
              "description": "Top-10 holder share of supply, percent."
            },
            "curveExcluded": {
              "type": [
                "boolean",
                "null"
              ],
              "description": "Whether bonding-curve/pool accounts were excluded from the concentration read."
            }
          }
        },
        "launch": {
          "type": "object",
          "properties": {
            "bundled": {
              "type": [
                "boolean",
                "null"
              ],
              "description": "Bundled-launch detection."
            },
            "firstSlotTxs": {
              "type": [
                "integer",
                "null"
              ]
            },
            "preGraduation": {
              "type": "boolean",
              "description": "True when the token exists on-chain but has no DEX pair yet."
            }
          }
        },
        "market": {
          "$ref": "#/$defs/MarketSignals"
        }
      }
    }
  }
}