Introduction

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`	The tracked vault universe, with live APY and TVL. Start here to discover `vaultId`s.
`/scores`	The latest composite and pillar scores for every tracked vault.
`/portfolio`	The Atlas Engine as a service — scores in, a sized, risk-adjusted allocation out.
`/basket`	Score a basket you define: per-vault scores plus a weighted basket score, with coverage disclosed.
`/vaults/{chainId}/{address}/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`	All 16 factor scores and labels behind one vault’s composite.
`/vaults/{chainId}/{address}/route`	Today’s round-trip route-survival verdict for one vault. Check it before a deposit.
`/gas`	The current gas regime per chain, with trailing 7-day percentiles.

The base URL, 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 (JSON: 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?”:

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:

{
  "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 and exact (`USDC`). A comma list of up to 10 is allowed (`USDC,USDT0`). `USDC` does not match `syrupUSDC`.
`address`	One vault by its on-chain address, case-insensitive.
`minScore`, `minTvl`, `minApy`	Keep vaults with composite at or above `minScore`, live TVL (USD) at or above `minTvl`, and live APY (percentage points) at or above `minApy`.
`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. It carries `flags`: cautions such as `thin_tvl` or `apy_outlier`. A flag is a prompt to look closer, never a verdict, and no flag is not a statement of safety.
`explain=true`	Adds an `explain` block: how many vaults each filter removed, the dropped vaults and why (best-ranked first, with up to 2 slots held for vaults dropped as unreachable or low-confidence), and near-miss asset symbols. Counts are per filter, so one vault can appear under two.

Every response carries applied, the filters this server honoured. If you sent a parameter and it is missing from applied, the rows are not filtered by it. The usual cause is a misspelt name: an unknown query key is not an error, it is ignored and listed in ignoredParams (present only when there is one), so minAPY=10 returns 200 with the rows unfiltered and "ignoredParams": ["minAPY"]. A ranking by composite is a ranking by the Atlas Score, not a recommendation. Before any deposit, check /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.

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.

Contact us for partner keys and more

Tell us what you are building and which vaults you list. We reply with a key, the partner endpoint reference, and pricing.

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.

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

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.

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.

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

Getting started

Endpoints

Find a vault in one call

Authentication

Partner keys

Contact us for partner keys and more

Calling from a browser

Rate limits

Versioning

Disclaimer

Coverage requests

​Find a vault in one call

​Authentication

​Partner keys

Contact us for partner keys and more

​Calling from a browser

​Rate limits

​Versioning

​Disclaimer

​Coverage requests

Find a vault in one call

Authentication

Partner keys

Calling from a browser

Rate limits

Versioning

Disclaimer

Coverage requests