AtlasYield Portfolio API

openapi: 3.2.0
info:
  title: AtlasYield Portfolio 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: Portfolio
paths:
  /portfolio:
    get:
      operationId: getPortfolio
      summary: Build a portfolio
      description: 'The Atlas Engine as a service. Give it a risk tier, a timeline, and a principal; it runs the mean-variance allocator over the current scored universe and returns the resulting allocation, sized in dollars.


        Unlike /scores and /catalog, this endpoint **fails closed on stale scoring**: an allocation is an active recommendation, so if the most recent scoring run is too old the endpoint returns 503 rather than allocating on stale data.


        The allocator is deterministic — the same inputs against the same scoring snapshot return the same portfolio.'
      parameters:
      - name: riskTier
        in: query
        required: true
        schema:
          type: string
          enum:
          - conservative
          - balanced
          - aggressive
        description: Which tier policy to allocate under. See the tier policy page.
        example: balanced
      - name: principal
        in: query
        required: true
        schema:
          type: number
          minimum: 100
          maximum: 1000000
        description: Amount to allocate, USD. Must be between 100 and 1,000,000.
        example: 10000
      - name: timeline
        in: query
        required: false
        schema:
          type: string
          enum:
          - short
          - medium
          - long
          default: medium
        description: Investment horizon. Nudges risk appetite within the tier's band — short is more variance-averse, long more return-seeking — and a short horizon also tightens the cap on vaults with little history.
        example: medium
      responses:
        '200':
          description: The proposed allocation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  riskTier:
                    type: string
                    example: balanced
                  timeline:
                    type: string
                    example: medium
                  principal:
                    type: number
                    example: 10000
                  strategy:
                    type: string
                    enum:
                    - MVO
                    - naive
                    - none
                    description: Which allocator produced the result. MVO is the mean-variance optimiser; naive is the equal-weight fallback; none means no allocation could be produced (see `note`).
                    example: MVO
                  fallback:
                    type: boolean
                    description: True when the result came from the fallback path rather than MVO.
                    example: false
                  allocations:
                    type: array
                    items:
                      $ref: '#/components/schemas/PortfolioSlice'
                  expectedApy:
                    type: number
                    nullable: true
                    description: Principal-weighted expected APY of the allocation, percentage points.
                    example: 4.69
                  expectedSharpe:
                    type: number
                    description: Expected Sharpe-like ratio of the allocation.
                    example: 14.58
                  unallocatedUsd:
                    type: number
                    description: Principal left in cash because policy caps could not be satisfied. Surfaced honestly rather than force-fitted into a vault.
                    example: 0
                  scorerVersion:
                    type: string
                    example: 2.2.0
                  generatedAt:
                    type: string
                    format: date-time
                    description: ISO-8601 UTC timestamp the allocation was produced.
                  disclaimer:
                    type: string
                    example: Research and information, not investment advice.
                  note:
                    type: string
                    description: Present only when the allocator could not fully allocate; explains why.
        '400':
          $ref: '#/components/responses/ValidationError'
        '503':
          description: Scoring data is stale, so no allocation was produced. Carries a `Retry-After` header (seconds).
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Scoring data is stale — portfolio unavailable
      tags:
      - Portfolio
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.
  schemas:
    PortfolioSlice:
      type: object
      description: One position in the proposed allocation.
      properties:
        vaultId:
          type: string
          description: Vault identifier (same as vaultId in /scores).
          example: morpho:1:0xbeefc1cdafc5b4a649b54d07afc6bf0f75c6f4e2
        protocol:
          type: string
          example: morpho
        chainId:
          type: integer
          example: 1
        asset:
          type: string
          description: Underlying asset symbol.
          example: USDC
        name:
          type: string
          description: Vault display name.
          example: STEAKUSDTBETHENA
        apy:
          type: number
          description: Current APY in percentage points.
          example: 12.18706
        tvl:
          type: number
          description: Total value locked, USD.
          example: 11780173
        composite:
          type: number
          description: The vault's 0–100 Atlas Score at allocation time.
          example: 78.762
        fraction:
          type: number
          description: Share of principal as a fraction, rounded to 1e-4.
          example: 0.15
        allocationPct:
          type: number
          description: Share of principal as a percentage, 2 dp.
          example: 15
        allocationUsd:
          type: number
          description: Dollar amount allocated to this vault.
          example: 1500
        vaultAddress:
          type: string
          description: On-chain vault contract address.
          example: '0xbeefc1cdafc5b4a649b54d07afc6bf0f75c6f4e2'
        underlyingToken:
          type: string
          description: Address of the token the vault accepts.
          example: '0xc139190f447e929f090edeb554d95abb8b18ac1c'
  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).