AtlasYield Basket API

openapi: 3.2.0
info:
  title: AtlasYield Basket 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: Basket
paths:
  /basket:
    post:
      operationId: scoreBasket
      summary: Score a basket
      description: 'Score a basket you define. Send up to 50 positions (chainId + vault address, optional weight) and get back each position''s current Atlas Score plus a weighted basket score: composite, pillars, and APY, weighted by position size. Weights are normalised, so percentages, USD amounts, and fractions all work; omit them for equal weight.


        **Coverage is disclosed, never assumed.** A position Atlas does not score is returned with `scored: false` and excluded from the aggregate, and `basket.scoredWeight` reports the share of the basket the score actually covers. It is never averaged in as zero.


        A pure computation over the request body: nothing is stored.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - positions
              properties:
                positions:
                  type: array
                  minItems: 1
                  maxItems: 50
                  items:
                    type: object
                    required:
                    - chainId
                    - address
                    properties:
                      chainId:
                        type: integer
                        example: 1
                      address:
                        type: string
                        description: Vault contract address, case-insensitive.
                        example: '0xd8a9f8b3c1b52e8a4f1e2f6c4e0b1a9c8d7e6f5a'
                      weight:
                        type: number
                        exclusiveMinimum: 0
                        description: Position size in any unit; normalised across the basket. Omit on every position for equal weight.
                        example: 60
      responses:
        '200':
          description: The basket score and each position.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  disclaimer:
                    type: string
                    example: Research and information, not investment advice.
                  scorerVersion:
                    type: string
                    example: 2.2.0
                  generatedAt:
                    type: string
                    format: date-time
                  basket:
                    type: object
                    properties:
                      composite:
                        type: number
                        nullable: true
                        description: Weight-weighted mean of the scored positions' composites. Null when nothing in the basket is scored.
                        example: 74.2
                      label:
                        type: string
                        nullable: true
                        example: Good
                      pillarScores:
                        type: object
                        properties:
                          yield:
                            type: number
                            nullable: true
                          safety:
                            type: number
                            nullable: true
                          liquidity:
                            type: number
                            nullable: true
                          sustainability:
                            type: number
                            nullable: true
                      apy:
                        type: number
                        nullable: true
                        description: Weight-weighted live APY of the scored positions, percentage points.
                      positions:
                        type: integer
                        description: Positions sent.
                      scoredPositions:
                        type: integer
                        description: Positions Atlas scores.
                      scoredWeight:
                        type: number
                        description: Share of basket weight covered by the aggregate, 0 to 1. Below 1 means the basket holds something Atlas does not score.
                        example: 1
                      maxWeight:
                        type: number
                        description: Largest single position weight
                        0 to 1.: null
                      chainShare:
                        type: object
                        additionalProperties:
                          type: number
                        description: Basket weight by chainId.
                      protocolShare:
                        type: object
                        additionalProperties:
                          type: number
                        description: Basket weight by protocolId; unscored positions appear under `unscored`.
                  positions:
                    type: array
                    description: One entry per position sent, in order. Scored entries carry the same fields as a /scores row plus `weight`.
                    items:
                      type: object
                      properties:
                        chainId:
                          type: integer
                        address:
                          type: string
                        weight:
                          type: number
                          description: Normalised weight
                          0 to 1.: null
                        scored:
                          type: boolean
                        vaultId:
                          type: string
                        name:
                          type: string
                          nullable: true
                        protocolId:
                          type: string
                        composite:
                          type: number
                        label:
                          type: string
                        apy:
                          type: number
                          nullable: true
                        tvl:
                          type: number
                          nullable: true
                        dataQuality:
                          type: string
                          enum:
                          - sufficient
                          - partial
                          - fallback
                        scoredAt:
                          type: string
                          format: date-time
        '400':
          $ref: '#/components/responses/ValidationError'
      tags:
      - Basket
components:
  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).