AtlasYield Vaults API

openapi: 3.2.0
info:
  title: AtlasYield Vaults 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: Vaults
paths:
  /vaults/{chainId}/{address}/factors:
    get:
      operationId: getVaultFactors
      summary: 16-factor breakdown for one vault
      description: 'The "why" behind a composite: every one of the 16 factors (15 additive across four pillars plus the multiplicative exploit-history modifier) with its sub-score, weight, raw input and a plain-English label. Served from the stored score row, so it is exactly what the engine computed at `scoredAt`, not a recomputation.'
      parameters:
      - name: chainId
        in: path
        required: true
        schema:
          type: integer
        example: 8453
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: Vault contract address. Case-insensitive.
        example: '0x4e65fe4dba92790696d040ac24aa414708f5c0ab'
      responses:
        '200':
          description: The latest score row's factor breakdown.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  disclaimer:
                    type: string
                    example: Research and information, not investment advice.
                  data:
                    $ref: '#/components/schemas/VaultFactors'
        '400':
          $ref: '#/components/responses/ValidationError'
        '404':
          description: The vault is not in the scored universe.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: No score found for this vault
      tags:
      - Vaults
  /vaults/{chainId}/{address}/metrics:
    get:
      operationId: getVaultMetrics
      summary: Live risk metrics for one vault
      description: 'Tier 1 live metrics for a single vault: yield quality and exit safety, each with the reason it was assigned. These are **separate from the Atlas Score** and are never folded into it — the composite answers "how good is this vault", these two answer "is the yield real" and "can I get out".


        Both values are nullable and are never fabricated: when the underlying inputs are missing, the value is `null` and the reason says why. Metrics are recomputed on a ~24h cadence, so `scorerRunDate` is the day the values were produced.'
      parameters:
      - name: chainId
        in: path
        required: true
        schema:
          type: integer
        description: EVM chain id the vault lives on.
        example: 8453
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: Vault contract address. Case-insensitive.
        example: '0x4e65fe4dba92790696d040ac24aa414708f5c0ab'
      responses:
        '200':
          description: The most recent metrics row for the vault.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  disclaimer:
                    type: string
                    example: Research and information, not investment advice.
                  data:
                    $ref: '#/components/schemas/VaultMetrics'
        '400':
          $ref: '#/components/responses/ValidationError'
        '404':
          description: No metrics have been computed for this vault.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Risk metrics not found for this vault
      tags:
      - Vaults
  /vaults/{chainId}/{address}/route:
    get:
      operationId: getVaultRoute
      summary: Route-survival verdict for one vault
      description: 'The wedge, not the score. An agent about to move real money needs "can I get out at size, measured today" more than "is this good". This is the same verdict `refreshAllRouteScreens` writes daily and the live engine uses to gate deposits — exposed read-only. Round trip, on the protocol''s own execution path, so no pricing oracle is involved: USDC compared against USDC.


        A vault that has never been screened returns `screened: false` with every measurement field `null` — never a fabricated verdict. Route tracking covers EVM chains only: a Solana vault returns `tracked: false` (not tracked, which is neither a pass nor a failure).'
      parameters:
      - name: chainId
        in: path
        required: true
        schema:
          type: integer
        description: EVM chain id the vault lives on.
        example: 1
      - name: address
        in: path
        required: true
        schema:
          type: string
        description: Vault contract address. Case-insensitive.
        example: '0x5949c3bfdf9babd8bf011d9d8dbb1a2c3e10d8b8'
      - name: notional
        in: query
        required: false
        description: USD size to cost the round trip at. 10 to 10,000,000, default 5,000.
        schema:
          type: number
          minimum: 10
          maximum: 10000000
          default: 5000
      responses:
        '200':
          description: The most recent route-survival verdict for the vault, or the unscreened shape.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  disclaimer:
                    type: string
                    example: Research and information, not investment advice.
                  data:
                    $ref: '#/components/schemas/VaultRoute'
        '400':
          $ref: '#/components/responses/ValidationError'
      tags:
      - Vaults
components:
  schemas:
    RouteCost:
      type: object
      nullable: true
      description: 'Estimated round-trip execution cost at `notionalUsd`, same-chain, on the named router. fixedUsd = (vault entry + exit + swap + router approvals) gas × USD per gas; allInBps = fixedUsd / notional + proportional (router fee + price impact). An ESTIMATE at the stated gas basis: realised cost varies with gas at execution time. Null when the vault never completed a round trip. Unmeasured inputs are listed in `missing`; where a component is known to be missing, the figure is marked `floor: true` (a lower bound).'
      properties:
        notionalUsd:
          type: number
          example: 10000
        router:
          type: string
          enum:
          - lifi
          - pendle-convert
          - none
          description: '`none` = same token in and out, nothing swapped. Costs differ by router: the Atlas app deposits via Relay.'
        gasBasis:
          type: string
          enum:
          - p50_7d
          description: Headline basis. Trailing 7-day median
          so a single spike cannot set it.: null
        fixedUsd:
          type: object
          properties:
            current:
              type: number
              nullable: true
            p50_7d:
              type: number
              nullable: true
            p90_7d:
              type: number
              nullable: true
            floor:
              type: boolean
              description: 'True when a component is known to be missing (L1 data fee on L2s (Base, Optimism, Arbitrum), or router gas not reported): the true figure is higher.'
        gasUnits:
          type: object
          properties:
            swap:
              type: integer
              nullable: true
            vaultEntry:
              type: integer
            vaultExit:
              type: integer
            approvals:
              type: integer
              description: USDC->router on entry + underlying->router on exit. LiFi only; 0 for Pendle Convert or a same-token round trip.
            total:
              type: integer
            vaultGasSource:
              type: string
              enum:
              - observed
              - assumed
              description: '`observed` = median of real transactions; `assumed` = no transaction exists yet.'
            highVariance:
              type: boolean
              description: True when the protocol's vault-action gas is a median of observed exits that disagreed by more than 2x.
        proportionalBps:
          type: object
          properties:
            value:
              type: number
              nullable: true
            routerFeeBps:
              type: number
              nullable: true
            priceImpactBps:
              type: number
              nullable: true
            extrapolated:
              type: boolean
              description: 'True outside the probed $100–$5,000: the nearest probe is held flat, not fitted.'
        allInBps:
          type: object
          properties:
            current:
              type: number
              nullable: true
            p50_7d:
              type: number
              nullable: true
            p90_7d:
              type: number
              nullable: true
            floor:
              type: boolean
              description: Same as fixedUsd.floor. True means these figures are a LOWER BOUND; treat as not passed in any gate.
        missing:
          type: array
          items:
            type: string
            enum:
            - swap_gas
            - l1_data_fee
            - gas_current
            - gas_history
            - no_route_at_size
            - gas_history_partial
            - high_variance_gas
    VaultFactors:
      type: object
      properties:
        vaultId:
          type: string
          example: aave-v3:8453:0x4e65fe4dba92790696d040ac24aa414708f5c0ab
        chainId:
          type: integer
          example: 8453
        protocolId:
          type: string
          example: aave-v3
        composite:
          type: number
          example: 87.5
        label:
          type: string
          enum:
          - Conservative
          - Balanced
          - Aggressive
        pillarScores:
          type: object
          properties:
            yield:
              type: number
            safety:
              type: number
            liquidity:
              type: number
            sustainability:
              type: number
        factors:
          type: object
          description: 'All 16 factors keyed by name: YIELD_LEVEL, APY_STABILITY, APY_PERSISTENCE, YIELD_SOURCE, AUDIT_QUALITY, PROTOCOL_MATURITY, TVL_DEPTH_SAFETY, TVL_STABILITY, ADMIN_TOPOLOGY, CHAIN_SECURITY, EXPLOIT_HISTORY, WITHDRAWAL_TYPE, TVL_DEPTH_LIQUIDITY, EMISSION_DEPENDENCY, ASSET_RISK, UTILIZATION_HEALTH.'
          additionalProperties:
            $ref: '#/components/schemas/FactorResult'
        dataQuality:
          type: string
          enum:
          - sufficient
          - partial
          - fallback
        scoredAt:
          type: string
          format: date-time
        scorerVersion:
          type: string
          example: 2.2.0
    FactorResult:
      type: object
      properties:
        score:
          type: number
          description: Sub-score 0–100. For EXPLOIT_HISTORY this is multiplier × 100.
          example: 82
        weight:
          type: number
          description: Weight inside its pillar's arithmetic mean. 0 for EXPLOIT_HISTORY (multiplicative).
          example: 0.3
        rawValue:
          type: number
          description: The raw input that drove the score (TVL USD, audit count, slope, ...).
          example: 5.2
        label:
          type: string
          description: Plain-English description of the input.
          example: 5.2% APY, stablecoin
        pillar:
          type: string
          enum:
          - yield
          - safety
          - liquidity
          - sustainability
    VaultMetrics:
      type: object
      description: Tier 1 live metrics for one vault. Separate from the Atlas Score, never folded into the composite.
      properties:
        vaultId:
          type: string
          description: 'Stable identifier: protocol:chainId:address.'
          example: aave-v3:8453:0x4e65fe4dba92790696d040ac24aa414708f5c0ab
        chainId:
          type: integer
          example: 8453
        yieldQuality:
          type: number
          nullable: true
          description: 0-100. How much of the headline APY comes from the vault's own economics rather than transient incentives. Null when the APY split is unavailable.
          example: 82
        yieldQualityReason:
          type: string
          nullable: true
          description: Why that value was assigned, or why it is null.
        exitSafety:
          type: number
          nullable: true
          description: 0-100. How safely a position can be exited at size. Null when the underlying liquidity data is unavailable.
          example: 74
        exitSafetyReason:
          type: string
          nullable: true
          description: Why that value was assigned, or why it is null.
        scorerRunDate:
          type: string
          format: date
          description: The day (UTC) these metrics were computed.
          example: '2026-09-04'
    VaultRoute:
      type: object
      description: 'Round-trip route-survival verdict for one vault: send USDC in, take the position, sell it straight back, on the exact path the app itself executes. "Can I get out at size, measured today" — not a liquidity claim, a real quote. SAME-CHAIN ONLY: funding USDC sits on the vault''s own chain. Nothing here describes bridging in from another chain (see `probe`).'
      properties:
        vaultId:
          type: string
          nullable: true
          description: 'Stable identifier: protocol:chainId:address. Null when unscreened.'
          example: pendle:1:0x5949c3bfdf9babd8bf011d9d8dbb1a2c3e10d8b8
        chainId:
          type: integer
          example: 1
        address:
          type: string
          description: The address that was asked for. Present only on the unscreened shape.
        tracked:
          type: boolean
          description: 'False when the vault''s chain has no route probe. Route tracking covers EVM chains only, so a Solana vault is not tracked. Not tracked is neither a pass nor a failure: there is simply no verdict.'
          example: true
        note:
          type: string
          description: Present only when `tracked` is false; says why there is no verdict.
        screened:
          type: boolean
          description: False when this vault has never been screened — no verdict is fabricated.
          example: true
        verdict:
          type: string
          nullable: true
          enum:
          - OK
          - DEGRADED
          - DANGEROUS
          - UNPRICEABLE
          - NO_ROUTE
          - SKIPPED
          - null
          description: OK/DEGRADED are tradable. DANGEROUS, UNPRICEABLE and NO_ROUTE block deposits in the live engine. SKIPPED means our own probe was rate-limited, not a statement about the vault. Null when unscreened.
          example: OK
        reasonClass:
          type: string
          nullable: true
          enum:
          - protocol_refused
          - no_aggregator_quote
          - dust
          - no_amount
          - rate_limited
          - unmapped
          - null
          description: 'Why a non-OK verdict was reached. `protocol_refused`: the protocol''s own router (Pendle Convert) refuses the position — the vault is dead for entry or exit. `no_aggregator_quote`: no same-chain aggregator quotes USDC into the underlying (typical for LP-token vaults); the vault may still be exitable by redeeming and unwinding by hand. `dust`: value came back but below the 85% floor. Null for OK/DEGRADED.'
          example: protocol_refused
        usdIn:
          type: number
          nullable: true
          description: USDC sent on the worst probed notional.
          example: 5000
        usdOut:
          type: number
          nullable: true
          description: USDC that came back after entering and exiting the position.
          example: 4991
        retained:
          type: number
          nullable: true
          description: usdOut / usdIn on the worst probed notional.
          example: 0.9982
        path:
          type: string
          nullable: true
          enum:
          - pendle
          - composer
          - native
          - null
          description: Which execution path was probed — the same one the app itself calls.
          example: pendle
        probe:
          type: object
          description: What was measured, stated on every response. `scope` is always `same-chain`; `crossChain` is always `not probed`.
          properties:
            scope:
              type: string
              example: same-chain
            funding:
              type: string
            legs:
              type: string
            notionalsUsd:
              type: array
              items:
                type: number
              example:
              - 100
              - 5000
            router:
              type: object
              additionalProperties:
                type: string
            crossChain:
              type: string
              example: not probed
        checkedAt:
          type: string
          format: date-time
          nullable: true
          description: When this verdict was last measured. Null when unscreened.
        cost:
          $ref: '#/components/schemas/RouteCost'
  responses:
    ValidationError:
      description: A query parameter is missing or out of range. The body carries per-field detail under `details.fieldErrors`.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              error:
                type: string
                example: Validation error
              details:
                type: object
                description: Zod field errors, keyed by parameter name.
  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).