> ## Documentation Index
> Fetch the complete documentation index at: https://docs.atlasyield.club/llms.txt
> Use this file to discover all available pages before exploring further.

# Score a basket

> 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.



## OpenAPI

````yaml api-reference/openapi.yaml POST /basket
openapi: 3.1.0
info:
  title: AtlasYield 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.
servers:
  - url: https://api.atlasyield.club/v1
security: []
paths:
  /basket:
    post:
      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.
      operationId: scoreBasket
      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.1.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'
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.

````