WealthVille — DeFi Liquidity Pool Scores API (Solana & EVM) Scores API

openapi: 3.2.0
info:
  title: Wealthville Public Data Scores API
  version: 1.0.0
  description: 'Public, read-only API for Wealthville pool scores (Enter/Hold/Exit + composite Wealthville Score, 0–100), the published-signal feed, and the live track record. Anonymous access is open at 60 requests/min per IP; partners can request an API key (sent as the `x-api-key` header) for a higher, per-key allowance. Methodology: https://www.wealthville.net/learn/wealthville-score'
  termsOfService: https://wealthville.net/terms
  contact:
    name: Wealthville Support
    url: https://www.wealthville.net/developers
    email: support@wealthville.net
  license:
    name: Proprietary — see Terms of Service
    url: https://wealthville.net/terms
servers:
- url: https://wealthville.net
security:
- {}
- ApiKeyAuth: []
tags:
- name: Scores
paths:
  /api/v1/scores/top:
    get:
      summary: Top pools ranked by Wealthville Score
      description: Freshly scored pools (verdicts computed within the last 6 hours), ranked by composite score. Cached 5 minutes.
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      - name: chain
        in: query
        schema:
          type: string
          default: solana
        description: '"solana" (default), "evm" (all EVM chains), or one EVM chain name (e.g. "ethereum", "base")'
      responses:
        '200':
          description: Ranked scores
          content:
            application/json:
              schema:
                type: object
                properties:
                  as_of:
                    type: string
                    format: date-time
                  methodology:
                    type: string
                  scores:
                    type: array
                    items:
                      $ref: '#/components/schemas/ScoreRow'
      tags:
      - Scores
  /api/v1/scores/{poolAddress}:
    get:
      summary: Scores for one pool
      parameters:
      - name: poolAddress
        in: path
        required: true
        schema:
          type: string
        description: Solana base58 address, or an EVM 0x address / DefiLlama pool UUID
      responses:
        '200':
          description: Score row
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScoreRow'
        '400':
          description: Invalid pool address
        '404':
          description: Pool not scored
      tags:
      - Scores
components:
  schemas:
    ScoreRow:
      type: object
      properties:
        pool_address:
          type: string
          description: Pool address (Solana base58; EVM rows are keyed by DefiLlama pool UUID)
        pool_name:
          type: string
          description: Token pair, e.g. "SOL/USDC" (falls back to the address when token metadata is unavailable)
        protocol:
          type: string
          example: orca-whirlpool
        chain:
          type: string
          example: solana
        verdict:
          type: string
          enum:
          - ENTER
          - INCREASE
          - HOLD
          - REDUCE
          - EXIT
          - AVOID
          - INSUFFICIENT_DATA
        confidence:
          type: string
          description: Verdict confidence, 0–1 (stringified numeric)
        enter_score:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 100
        hold_score:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 100
        exit_score:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 100
        wealthville_score:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 100
          description: Composite quality score (0.55·enter + 0.45·hold)
        computed_at:
          type: string
          format: date-time
        reasons:
          type: array
          items:
            type: string
        data_tier:
          type:
          - integer
          - 'null'
          description: 'Data-collection cadence bucket behind this score (Solana only): 0 ≈ 15 min, 1 ≈ 1 h, 2 ≈ 6 h, 3 ≈ 24 h. Scores are never penalized or boosted for tier — this field exists so consumers can apply their own freshness policy.'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Optional partner key — raises the rate limit and identifies the caller.