> ## 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. |
| [`/vaults/{chainId}/{address}/factors`](/api-reference/get-vault-factors) | All 16 factor scores and labels behind one vault's composite. |
| [`/vaults/{chainId}/{address}/route`](/api-reference/get-vault-route) | Today's round-trip route-survival verdict for one vault. Check it before a deposit. |
| [`/gas`](/api-reference/get-gas) | The current gas regime per chain, with trailing 7-day percentiles. |

The base URL, [`https://api.atlasyield.club/v1`](https://api.atlasyield.club/v1), returns an
index of every endpoint with the rate limits and links. The machine-readable OpenAPI 3.1
document is at
[`docs.atlasyield.club/api-reference/openapi.yaml`](https://docs.atlasyield.club/api-reference/openapi.yaml)
(JSON: [`api.atlasyield.club/openapi.json`](https://api.atlasyield.club/openapi.json)).

## Find a vault in one call

You do not need to know a vault address to get started. `/scores` takes filters, so one
small request can answer "which USDC vaults on Base can I actually deposit into?":

```bash theme={null}
curl "https://api.atlasyield.club/v1/scores?asset=USDC&chainId=8453&routable=true&excludeFallback=true&sort=composite&limit=5&fields=compact"
```

That response is about 2.5 KB. Without `fields=compact` and `limit`, `/scores` returns the
whole catalog, which is large. A trimmed real response:

```json theme={null}
{
  "success": true,
  "scorerVersion": "2.3.0",
  "count": 2,
  "total": 39,
  "data": [
    {
      "vaultId": "morpho:8453:0xee8f4ec5672f09119b96ab6fb59c27e1b7e44b61",
      "chainId": 8453,
      "protocolId": "morpho",
      "name": "Morpho Gauntlet USDC Prime",
      "asset": "USDC",
      "composite": 89.87,
      "label": "Conservative",
      "apy": 4.46546,
      "tvl": 414280265,
      "dataQuality": "sufficient",
      "routable": true,
      "scoredAt": "2026-10-08T19:52:38.011+00:00",
      "pageUrl": "https://atlasyield.club/vaults/morpho/8453/0xee8f4ec5672f09119b96ab6fb59c27e1b7e44b61"
    }
  ]
}
```

`count` is the rows returned and `total` is the rows that matched before `limit`.

| Parameter | What it does |
| - | - |
| `chainId`, `protocolId` | Filter to one chain or protocol. |
| `asset` | Underlying asset symbol, case-insensitive (`USDC`). |
| `address` | One vault by its on-chain address, case-insensitive. |
| `minScore`, `minTvl` | Keep vaults with composite at or above `minScore` and live TVL (USD) at or above `minTvl`. |
| `routable=true` | Only vaults a deposit can reach. A vault that is not in the live catalog is left out, never assumed reachable. |
| `excludeFallback=true` | Drop rows scored on fallback data. |
| `sort` | `composite`, `apy` or `tvl`, highest first. `apy` and `tvl` are the live values. |
| `limit` | At most this many rows, 1 to 200, applied after filtering and sorting. |
| `fields=compact` | The small row shown above instead of the full score row. |

A ranking by composite is a ranking by the Atlas Score, not a recommendation. Before any
deposit, check [`/route`](/api-reference/get-vault-route) for that vault: a blocking verdict
means refuse.

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

## Calling from a browser

Every `/v1` route answers cross-origin requests from any website: `Access-Control-Allow-Origin: *`,
with no credentials involved, so `fetch` works from a page on any domain or from `localhost`.
The `x-api-key` and `content-type` request headers are allowed, preflights are cached for 24
hours, and error responses carry the same headers, so a browser can read a `429` or `404`
body. The `RateLimit`, `RateLimit-Policy`, `Retry-After` and `X-Atlas-Disclaimer` response
headers are readable from JavaScript. `openapi.json` and `llms.txt` on the API host are open
the same way.

```js theme={null}
const res = await fetch(
  "https://api.atlasyield.club/v1/scores?asset=USDC&limit=3&fields=compact"
);
const { data, total } = await res.json();
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.