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

# Introduction

> The judgment layer for on-chain yield, as an API. Public, read-only, no key.

Read-only access to the Atlas Score Index: neutral **16-factor** vault scores across four
pillars — Yield, Safety, Liquidity, Sustainability. Public, no key, JSON out.
A stranger should be able to integrate in under 30 minutes.

| Endpoint                                                                  | What it gives you                                                                                                    |
| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| [`/catalog`](/api-reference/get-catalog)                                  | The tracked vault universe, with live APY and TVL. Start here to discover `vaultId`s.                                |
| [`/scores`](/api-reference/get-scores)                                    | The latest composite and pillar scores for every tracked vault.                                                      |
| [`/portfolio`](/api-reference/get-portfolio)                              | The Atlas Engine as a service — scores in, a sized, risk-adjusted allocation out.                                    |
| [`/basket`](/api-reference/post-basket)                                   | Score a basket you define: per-vault scores plus a weighted basket score, with coverage disclosed.                   |
| [`/vaults/{chainId}/{address}/metrics`](/api-reference/get-vault-metrics) | Live risk metrics for one vault: yield quality and exit safety, each with its reason. Separate from the Atlas Score. |

The machine-readable OpenAPI 3.1 document is at
[`docs.atlasyield.club/api-reference/openapi.yaml`](https://docs.atlasyield.club/api-reference/openapi.yaml).

## Authentication

None for everything above. The API is public and read only. No key, no signup.

```bash theme={null}
curl https://api.atlasyield.club/v1/scores
```

### Partner keys

Partners embedding Atlas in their own interface get a key, sent as `x-api-key`. It is an
unlock, not a gate: every public endpoint behaves the same with or without it. What it
adds (bulk factor breakdowns, the timestamped score history, a larger request budget) is
documented for partners only.

<Card title="Contact us for partner keys and more" icon="key" href="/partner-access">
  Tell us what you are building and which vaults you list. We reply with a key, the partner
  endpoint reference, and pricing.
</Card>

| Status | Meaning                                                                                                           |
| ------ | ----------------------------------------------------------------------------------------------------------------- |
| `400`  | A query parameter is missing or out of range. Per-field detail is in `details.fieldErrors`.                       |
| `429`  | Rate limit exceeded (see below).                                                                                  |
| `503`  | `/portfolio` only — scoring data is stale, so no allocation was produced. Retry after the `Retry-After` interval. |

<Note>
  `/scores` and `/catalog` serve whatever is currently cached. `/portfolio` **fails closed**:
  an allocation is an active recommendation, so it returns `503` rather than allocating on
  stale scoring data. Treat a `503` as "ask again shortly", not as an outage.
</Note>

## Rate limits

**60 requests / minute** per IP. Exceeding it returns `429` with standard
`RateLimit-*` headers. The dataset refreshes on a scoring cadence of hours, not seconds —
cache responses and poll sparingly.

## Versioning

Everything lives under the `/v1` prefix. Breaking changes ship under a new prefix; `/v1`
stays stable. Every score row also carries `scorerVersion` so you can pin to a scoring
engine revision.

## Disclaimer

Atlas Scores are **research and information, not investment advice**. The same line ships
on every response — as a `disclaimer` field and an `X-Atlas-Disclaimer` header. Scores are
neutral, model-driven signals; you are responsible for your own listing and allocation
decisions. See [Limitations](/limitations).

## Coverage requests

Nothing to request access to. If there is a protocol or chain you need scored that we do not
cover yet, email [admin@atlasyield.club](mailto:admin@atlasyield.club). Tell us the surface
you are building and the sources you route to.

You can tell us what to cover. You cannot tell us what it scores.