HostDeFi Token Risk API

openapi: 3.2.0
info:
  title: HostDeFi Token Risk API
  version: 1.0.0
  description: 'Public product surface of the scam-check-api service: the /v1 Token Risk API (same proprietary A+–F Safety Read rendered on the HostDeFi token pages, plus pre-graduation on-chain signals for Solana), key purchase/usage endpoints, and the free contract scanner at POST /analyze-token. Keyless callers get a per-IP fair-use tier of 100 calls/day on the verdict endpoints; paid API keys (bought with SOL via POST /v1/keys) raise the quota and unlock batch. Send an API key as the `x-api-key` header.'
  contact:
    url: https://hostdefi.com/docs/api/
    email: trustdex.app@gmail.com
servers:
- url: https://hostdefi.com/api
  description: 'Canonical branded base — /v1/* served via the hostdefi.com edge (use this in new integrations). Note: /analyze-token is exposed here as POST /api/scan.'
- url: https://awake-integrity-production-faa0.up.railway.app
  description: Origin host (Railway) — keeps working for existing integrations; all paths incl. /analyze-token.
security:
- {}
- ApiKeyHeader: []
tags:
- name: Token Risk
paths:
  /v1/token-risk/{chain}/{address}:
    get:
      summary: Token risk verdict by explicit chain + address
      operationId: getTokenRisk
      security:
      - {}
      - ApiKeyHeader: []
      parameters:
      - name: chain
        in: path
        required: true
        schema:
          type: string
        description: Chain id, e.g. solana, ethereum, bsc, base, arbitrum, optimism, polygon, avalanche.
        example: solana
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: Token contract address (Solana mint or 0x EVM address).
        example: DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
      responses:
        '200':
          description: Verdict. Cacheable for 60s (`public` when keyless, `private` when keyed).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Verdict'
        '400':
          $ref: '#/components/responses/V1Error'
        '401':
          $ref: '#/components/responses/V1Error'
        '429':
          $ref: '#/components/responses/V1RateLimited'
        '500':
          $ref: '#/components/responses/V1Error'
      tags:
      - Token Risk
  /v1/token-risk:
    post:
      summary: Token risk verdict by free-form query (address or name/ticker)
      operationId: postTokenRisk
      security:
      - {}
      - ApiKeyHeader: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: A token contract address, or a name/ticker (resolved to the deepest-liquidity match). `address` is accepted as an alias.
                address:
                  type: string
                  description: Alias for `query`.
            example:
              query: BONK
      responses:
        '200':
          description: Verdict. Cacheable for 60s (`public` when keyless, `private` when keyed).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Verdict'
        '400':
          $ref: '#/components/responses/V1Error'
        '401':
          $ref: '#/components/responses/V1Error'
        '404':
          $ref: '#/components/responses/V1Error'
        '429':
          $ref: '#/components/responses/V1RateLimited'
        '500':
          $ref: '#/components/responses/V1Error'
      tags:
      - Token Risk
  /v1/token-risk/batch:
    post:
      summary: Batch token risk verdicts (Pro/Scale plans only)
      description: 'Up to 10 items per call, keyed plans with batch access only (Pro and Scale — `batch: true` in /v1/health''s plan table). Each attempted item counts against the key quota (an item rejected up front for a missing address is not metered). Results preserve input order; a failing item becomes a per-item error object instead of failing the whole batch. Keyless callers get 402; keyed plans without batch get 403.'
      operationId: postTokenRiskBatch
      security:
      - ApiKeyHeader: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - items
              properties:
                items:
                  type: array
                  minItems: 1
                  maxItems: 10
                  items:
                    type: object
                    required:
                    - address
                    properties:
                      chain:
                        type:
                        - string
                        - 'null'
                        description: Optional chain id; inferred from the address/market data when omitted.
                      address:
                        type: string
                        description: Token contract address.
            example:
              items:
              - chain: solana
                address: DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263
              - chain: ethereum
                address: '0x6982508145454Ce325dDbE47a25d4ec3d2311933'
      responses:
        '200':
          description: 'Per-item results in input order. `Cache-Control: private, max-age=60`.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    const: true
                  plan:
                    type: string
                    description: Plan id of the calling key (month or year).
                  remaining:
                    type: integer
                    description: Calls remaining on the key's quota after this batch.
                  results:
                    type: array
                    description: One entry per input item, same order. Either a full verdict or a per-item error object.
                    items:
                      oneOf:
                      - $ref: '#/components/schemas/Verdict'
                      - $ref: '#/components/schemas/BatchItemError'
        '400':
          $ref: '#/components/responses/V1Error'
        '401':
          $ref: '#/components/responses/V1Error'
        '402':
          description: No API key — batch is a paid feature (Pro/Scale). See https://hostdefi.com/docs/api/.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1ErrorBody'
        '403':
          description: Keyed plan without batch access (Builder). See https://hostdefi.com/docs/api/.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V1ErrorBody'
        '429':
          $ref: '#/components/responses/V1RateLimited'
        '500':
          $ref: '#/components/responses/V1Error'
      tags:
      - Token Risk
components:
  schemas:
    Verdict:
      type: object
      description: The graded Safety Read for one token — identical to the grade rendered on the HostDeFi token pages.
      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: '#/components/schemas/RiskBlock'
        signals:
          description: Chain-dependent raw signals behind the grade.
          oneOf:
          - $ref: '#/components/schemas/SolanaSignals'
          - $ref: '#/components/schemas/EvmSignals'
        meta:
          type: object
          properties:
            checkedAt:
              type: string
              format: date-time
            sources:
              type: array
              items:
                type: string
                enum:
                - dexscreener
                - 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.
    V1ErrorBody:
      type: object
      properties:
        ok:
          type: boolean
          const: false
        error:
          type: string
        pending:
          type: boolean
          description: Present on 202 from /v1/keys while the payment is unconfirmed.
        resetsAt:
          type: integer
          description: Unix ms timestamp when the limit resets (present on some 429s).
        details:
          type: string
      required:
      - ok
      - error
    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: '#/components/schemas/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'
    BatchItemError:
      type: object
      description: Per-item failure inside a batch — the other items still return verdicts.
      properties:
        ok:
          type: boolean
          const: false
        error:
          type: string
        details:
          type: string
      required:
      - ok
      - error
    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: '#/components/schemas/MarketSignals'
    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).
    MarketSignals:
      type: object
      properties:
        liquidityUsd:
          type:
          - number
          - 'null'
        volume24h:
          type:
          - number
          - 'null'
        priceUsd:
          type:
          - number
          - 'null'
  responses:
    V1RateLimited:
      description: 'Rate limited: keyless daily fair-use reached, plan quota reached, or per-key burst ceiling (~5 req/s). `Cache-Control: no-store`.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/V1ErrorBody'
    V1Error:
      description: 'Error. `Cache-Control: no-store`.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/V1ErrorBody'
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: API key from POST /v1/keys (vx_ + 32 hex chars). Omit it to use the keyless free tier (100 calls/day per IP).