AtlasYield Scores API

openapi: 3.2.0
info:
  title: AtlasYield Scores API
  version: '1.0'
  description: 'Read-only access to the Atlas Score Index: neutral 16-factor vault scores across four pillars — Yield, Safety, Liquidity, Sustainability — plus the tracked vault catalog and the Atlas Engine, which turns those scores into a risk-adjusted allocation. Research and information, not investment advice.

    Every endpoint in this spec is public and keyless, limited to 60 requests per minute per IP. An optional partner key sent in the `x-api-key` header moves the caller to its own bucket of 100 requests per minute and unlocks two endpoints that are not part of this spec (every vault''s factor breakdown in one call, and score history). A key is never required: an unknown or retired key sent to a public endpoint is ignored, and only the two partner endpoints reject it, with a 401. How to get one: https://docs.atlasyield.club/partner-access'
servers:
- url: https://api.atlasyield.club/v1
security:
- {}
- PartnerKey: []
tags:
- name: Scores
paths:
  /scores:
    get:
      operationId: getScores
      summary: Latest scores
      description: The most recent composite + pillar scores for every tracked vault — one row per vault, newest first.
      parameters:
      - name: chainId
        in: query
        required: false
        schema:
          type: integer
        description: Filter to one EVM chain id.
        example: 8453
      - name: protocolId
        in: query
        required: false
        schema:
          type: string
        description: Filter to one protocol slug.
        example: morpho
      - name: address
        in: query
        required: false
        schema:
          type: string
        description: One vault by on-chain address (last segment of vaultId, case-insensitive). Returns at most one row per chain.
        example: '0xbeeF010f9cb27031ad51e3333f9aF9C6B1228183'
      - name: asset
        in: query
        required: false
        schema:
          type: string
        description: 'Underlying asset symbol, case-insensitive exact match. Accepts a comma list of up to 10 (USDC,USDT0). Exact means exact: USDC does not match syrupUSDC. Use explain=true to see near-miss symbols.'
        example: USDC
      - name: minScore
        in: query
        required: false
        schema:
          type: number
          minimum: 0
          maximum: 100
        description: Keep vaults with composite >= this value.
      - name: minTvl
        in: query
        required: false
        schema:
          type: number
          minimum: 0
        description: Keep vaults whose LIVE TVL (USD) is >= this value.
      - name: minApy
        in: query
        required: false
        schema:
          type: number
          minimum: 0
        description: Keep vaults whose LIVE APY (percentage points) is >= this value. A vault with no APY never clears it.
      - name: routable
        in: query
        required: false
        schema:
          type: string
          enum:
          - 'true'
        description: Only vaults a deposit can reach. Excludes vaults flagged unroutable and, failing closed, vaults missing from the live catalog. Only the value true is accepted.
      - name: excludeFallback
        in: query
        required: false
        schema:
          type: string
          enum:
          - 'true'
        description: Exclude rows scored on fallback data (dataQuality = fallback).
      - name: explain
        in: query
        required: false
        schema:
          type: string
          enum:
          - 'true'
        description: 'Adds an explain block saying what the filters removed: counts per filter, the dropped vaults and why (best-ranked first, with up to 2 slots held for vaults dropped as unreachable or low-confidence), and near-miss asset symbols. Counts are per filter, so a vault failing two filters is counted under both.'
      - name: sort
        in: query
        required: false
        schema:
          type: string
          enum:
          - composite
          - apy
          - tvl
        description: Sort descending by this field (apy and tvl are the live values). Omit to keep the default order.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
        description: Return at most this many rows, applied after filtering and sorting.
      - name: fields
        in: query
        required: false
        schema:
          type: string
          enum:
          - compact
        description: compact returns the small CompactScore row instead of the full Score.
      responses:
        '200':
          description: Latest scores for the tracked vaults that match.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  scorerVersion:
                    type: string
                    example: 2.2.0
                  count:
                    type: integer
                    example: 570
                    description: Rows returned.
                  total:
                    type: integer
                    example: 570
                    description: Rows matching the filters before limit is applied.
                  applied:
                    type: object
                    description: Every filter this server honoured, echoed back. If you sent a parameter and it is missing here, the API predates it and the rows are not filtered by it.
                    additionalProperties: true
                  ignoredParams:
                    type: array
                    description: 'Query keys this endpoint does not recognise, sorted, at most 20 of at most 64 characters. Present only when there is at least one. An unknown key is not an error: it is ignored, so a typo such as minAPY returns 200 with the rows NOT filtered by it. If you expected a filter to apply, check that its name is not listed here.'
                    items:
                      type: string
                  explain:
                    type: object
                    description: Only with explain=true.
                    properties:
                      universe:
                        type: integer
                        description: Deduped vaults scored.
                      candidates:
                        type: integer
                        description: Vaults passing chainId, protocolId, address and asset.
                      matched:
                        type: integer
                      returned:
                        type: integer
                      truncated:
                        type: boolean
                        description: More matched than limit returned.
                      failed:
                        type: object
                        description: Candidates failing each requested filter. Not exclusive.
                        properties:
                          belowMinScore:
                            type: integer
                          belowMinTvl:
                            type: integer
                          belowMinApy:
                            type: integer
                          noDepositRoute:
                            type: integer
                            description: Route screen says a deposit cannot be exited.
                          noLiveEntry:
                            type: integer
                            description: Not in the live catalog (fails closed). A high count here with a low liveCatalogEntries means a cold cache, not blocked routes.
                          fallbackData:
                            type: integer
                      liveCatalogEntries:
                        type: integer
                      notable:
                        type: array
                        description: Up to 5 dropped vaults with the reasons, ordered by the active sort. Up to 2 slots are reserved for vaults dropped for a safety reason (noDepositRoute, noLiveEntry, fallbackData) so they cannot be crowded out by higher-ranked misses; the rest are the best-ranked drops.
                        items:
                          type: object
                          properties:
                            vaultId:
                              type: string
                            name:
                              type:
                              - string
                              - 'null'
                            composite:
                              type: number
                            apy:
                              type:
                              - number
                              - 'null'
                            tvl:
                              type:
                              - number
                              - 'null'
                            reasons:
                              type: array
                              items:
                                type: string
                      similarAssets:
                        type: array
                        description: Symbols containing a queried symbol that the exact match left out.
                        items:
                          type: object
                          properties:
                            asset:
                              type: string
                            count:
                              type: integer
                  disclaimer:
                    type: string
                    example: Research and information, not investment advice.
                  data:
                    type: array
                    items:
                      oneOf:
                      - $ref: '#/components/schemas/Score'
                      - $ref: '#/components/schemas/CompactScore'
      tags:
      - Scores
components:
  schemas:
    CompactScore:
      type: object
      description: Returned by GET /scores when fields=compact. About 410 bytes per row (a full Score is about 820). No pillar, factor-quality or admin blobs. Fetch /vaults/{chainId}/{address}/factors for the breakdown.
      properties:
        vaultId:
          type: string
          example: morpho:8453:0xbbb2
        chainId:
          type: integer
          example: 8453
        protocolId:
          type: string
          example: morpho
        name:
          type:
          - string
          - 'null'
        asset:
          type:
          - string
          - 'null'
          example: USDC
        composite:
          type: number
          example: 80
        label:
          type: string
          example: Good
        apy:
          type:
          - number
          - 'null'
          description: Live APY in percentage points.
        tvl:
          type:
          - number
          - 'null'
          description: Live TVL in USD.
        dataQuality:
          type: string
          enum:
          - sufficient
          - partial
          - fallback
        routable:
          type: boolean
          description: True when the vault is in the live catalog and not flagged unroutable by the route screen. A vault missing from the live catalog is false (fail closed).
        flags:
          type: array
          description: Cautions computed from fields we already hold. A flag is a prompt to look closer, never a verdict, and an empty list is not a statement of safety. thin_tvl (live TVL under $2M, or unknown); apy_outlier (live APY at least 10 and at least 3x the median of its chain and asset peers, with at least 5 peers); fallback_data and partial_data (dataQuality); stale_score (scored more than 8 hours ago).
          items:
            type: string
            enum:
            - thin_tvl
            - apy_outlier
            - fallback_data
            - partial_data
            - stale_score
        scoredAt:
          type: string
          format: date-time
        pageUrl:
          type: string
          description: Citable vault page.
          example: https://atlasyield.club/vaults/morpho/8453/0xbbb2
    Score:
      type: object
      properties:
        vaultId:
          type: string
          description: 'Stable identifier: protocol:chainId:address.'
          example: aave-v3:8453:0x4e65fe4dba92790696d040ac24aa414708f5c0ab
        chainId:
          type: integer
          description: Chain id. EVM chains use their EIP-155 id (1 Ethereum, 8453 Base, 42161 Arbitrum); Solana is 792703809 (Relay's id).
          example: 8453
        protocolId:
          type: string
          description: Adapter/protocol slug. Currently one of beefy, yearn-v3, morpho, pendle, aave-v3, euler, etherfi, ethena, kamino. New adapters are added over time — treat this as an open set rather than a fixed enum.
          example: aave-v3
        name:
          type: string
          nullable: true
          description: Human-readable vault name, the same string /catalog reports, so no join is needed. Null only when the vault is absent from the live catalog cache.
          example: Aave V3 USDC
        onchainId:
          type: string
          nullable: true
          description: The vault address with its original case. vaultId is lowercased, which is lossless for 0x addresses but not for Solana base58, so use this field to look a vault up on-chain. Null only when the vault is absent from the live cache.
          example: '0x4e65fE4DbA92790696d040ac24Aa414708F5c0AB'
        adminTopology:
          type: object
          nullable: true
          description: 'AY-269: per-vault admin setup, read daily. Null when the vault is not screened (Aave, Pendle, EtherFi, Ethena, and BNB vaults) and scores on protocol metadata instead. `class` is one of immutable, timelock_long_multisig_strong (7+ day delay, a 3+ threshold multisig that is also a majority of signers), timelock_short_multisig_weak, multisig_only, eoa (a single admin key), or unknown. For an `eoa` vault, `curatorRating` decides the score directly: 40 when the curator is rated established, 10 when unknown or new; every class floors at 10. `roles` never carries an address, only kind (none, eoa, safe, dao, unrecognised) plus threshold/owners for a safe. `dao` is on-chain governance (a token-vote governor or Sky), scored like a strong multisig; a dao with `unverifiedGovernance` (Aragon, plugin not inspected) is scored like a weak one. `delaySeconds` is the delay a timelock or supervisor adds in front of that role, on top of the vault''s own `timelockSeconds`.'
          properties:
            class:
              type: string
              enum:
              - immutable
              - timelock_long_multisig_strong
              - timelock_short_multisig_weak
              - multisig_only
              - eoa
              - unknown
            curatorId:
              type: string
              nullable: true
            curatorRating:
              type: string
              nullable: true
              enum:
              - established
              - unknown_new
            timelockSeconds:
              type: number
              nullable: true
            roles:
              type: array
              items:
                type: object
                properties:
                  role:
                    type: string
                  kind:
                    type: string
                    enum:
                    - none
                    - eoa
                    - safe
                    - dao
                    - unrecognised
                  threshold:
                    type: number
                  owners:
                    type: number
                  delaySeconds:
                    type: number
                  unverifiedGovernance:
                    type: boolean
            checkedAt:
              type: string
              format: date-time
        asset:
          type: string
          description: Underlying asset symbol.
          example: USDC
        assetClass:
          type: string
          nullable: true
          enum:
          - stablecoin
          - stablecoin-yield
          - eth
          - btc
          - top50
          - usd-exotic
          - other
          description: Asset class bucket used to contextualise the yield factors. May be null.
          example: stablecoin
        composite:
          type: number
          description: 0–100 composite Atlas Score.
          example: 87.5
        label:
          type: string
          enum:
          - Conservative
          - Balanced
          - Aggressive
          description: Risk-posture band for the composite.
        pillarScores:
          type: object
          description: The four pillar scores, 0–100 each.
          properties:
            yield:
              type: number
              example: 82
            safety:
              type: number
              example: 90
            liquidity:
              type: number
              example: 88
            sustainability:
              type: number
              example: 85
        apy:
          type: number
          nullable: true
          description: Current APY in percentage points (5.21 = 5.21%). May be null.
          example: 5.21
        tvl:
          type: number
          nullable: true
          description: Total value locked, USD. May be null.
          example: 1250400
        dataQuality:
          type: string
          enum:
          - sufficient
          - partial
          - fallback
          description: How complete the inputs were.
        scoredAt:
          type: string
          format: date-time
          description: ISO-8601 UTC timestamp the score was computed (ex-ante, immutable).
        scorerVersion:
          type: string
          description: Scoring engine version that produced the row.
          example: 2.2.0
  securitySchemes:
    PartnerKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Optional. Not needed for any endpoint in this spec. Unlocks the partner-only endpoints and a 100 requests per minute bucket (public limit is 60 per IP).