# Vault catalog
Source: https://docs.atlasyield.club/api-reference/get-catalog
api-reference/openapi.yaml GET /catalog
The tracked vault universe — every vault Atlas scores, with its live APY and TVL. Use it to discover vaultIds before querying /scores.
# Gas regime
Source: https://docs.atlasyield.club/api-reference/get-gas
api-reference/openapi.yaml GET /gas
# Build a portfolio
Source: https://docs.atlasyield.club/api-reference/get-portfolio
api-reference/openapi.yaml GET /portfolio
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.
# Latest scores
Source: https://docs.atlasyield.club/api-reference/get-scores
api-reference/openapi.yaml GET /scores
The most recent composite + pillar scores for every tracked vault — one row per vault, newest first.
# Factor breakdown
Source: https://docs.atlasyield.club/api-reference/get-vault-factors
api-reference/openapi.yaml GET /vaults/{chainId}/{address}/factors
The "why" behind a composite: every one of the 16 factors (15 additive across four pillars plus the multiplicative exploit-history modifier) with its sub-score, weight, raw input and a plain-English label. Served from the stored score row, so it is exactly what the engine computed at `scoredAt`, not a recomputation.
# Live risk metrics
Source: https://docs.atlasyield.club/api-reference/get-vault-metrics
api-reference/openapi.yaml GET /vaults/{chainId}/{address}/metrics
Tier 1 live metrics for a single vault: yield quality and exit safety, each with the reason it was assigned. These are **separate from the Atlas Score** and are never folded into it — the composite answers "how good is this vault", these two answer "is the yield real" and "can I get out".
Both values are nullable and are never fabricated: when the underlying inputs are missing, the value is `null` and the reason says why. Metrics are recomputed on a ~24h cadence, so `scorerRunDate` is the day the values were produced.
# Route survival
Source: https://docs.atlasyield.club/api-reference/get-vault-route
api-reference/openapi.yaml GET /vaults/{chainId}/{address}/route
The wedge, not the score. An agent about to move real money needs "can I get out at size, measured today" more than "is this good". This is the same verdict `refreshAllRouteScreens` writes daily and the live engine uses to gate deposits — exposed read-only. Round trip, on the protocol's own execution path, so no pricing oracle is involved: USDC compared against USDC.
A vault that has never been screened returns `screened: false` with every measurement field `null` — never a fabricated verdict.
# Introduction
Source: https://docs.atlasyield.club/api-reference/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.
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.
```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.
# MCP server
Source: https://docs.atlasyield.club/api-reference/mcp
Seven read-only tools an agent can call for judgment before it moves money. Hosted or local, no key, no custody.
The Atlas MCP server wraps the public `/v1` API and the published score history as a
[Model Context Protocol](https://modelcontextprotocol.io) server. Use it hosted at a URL, or
run it locally. It is listed in the
[official MCP registry](https://registry.modelcontextprotocol.io/v0.1/servers/club.atlasyield%2Fmcp/versions/latest)
as `club.atlasyield/mcp`.
## Connect
### Hosted: nothing to install
```
https://atlasyield.club/mcp
```
MCP Streamable HTTP, read-only, no key. In Claude Code:
```bash theme={null}
claude mcp add --transport http atlasyield https://atlasyield.club/mcp
```
Any client that accepts a remote MCP server URL can use the same address; the field it goes
in depends on the client. To check it from a terminal:
```bash theme={null}
curl -s https://atlasyield.club/mcp \
-H "content-type: application/json" \
-H "accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```
Both headers are required; without the `accept` header the server answers `406`. Opening the
URL in a browser shows a `405` message, which is expected: the endpoint only accepts `POST`.
### Local: run it yourself
`@atlasyield/mcp` on npm runs the same tools over stdio.
```bash theme={null}
claude mcp add atlasyield -- npx -y @atlasyield/mcp
```
```json theme={null}
{ "mcpServers": { "atlasyield": { "command": "npx", "args": ["-y", "@atlasyield/mcp"] } } }
```
## Tools
| Tool | Input | Gives you |
| - | - | - |
| `find_vaults` | `asset?`, `chain?` (name or id), `protocolId?`, `minScore?`, `minTvlUsd?`, `sortBy?`, `limit?` (default 5, max 10) | Start here when you have no vault address. A short ranked list of scored vaults a deposit can reach, with composite, label, live APY/TVL, `routable` and a citable page URL. Rows with no deposit route or fallback data are excluded. A ranking, not a recommendation. About 2 KB per call. |
| `get_vault_score` | `chainId`, `address` | Latest composite, label, the four pillar scores, live APY/TVL, `found:false` if unscored. |
| `get_coverage` | `chainId?`, `protocolId?` | Vault count, TVL, composite min/median/max, counts by protocol and chain. |
| `check_route_survival` | `chainId`, `address` | Today's same-chain round-trip route screen. `blocking:true` (NO\_ROUTE, DANGEROUS, UNPRICEABLE) means refuse the deposit; `reasonClass` says why (`protocol_refused` = the vault is dead, `no_aggregator_quote` = no priced same-chain route into the underlying). `screened:false` means unjudged, never cleared. Cross-chain is not probed. |
| `list_open_alerts` | `chainId?`, `minSeverity?` | Open monitor alerts from the daily snapshot with score before/after. |
| `explain_vault_score` | `chainId`, `address` | Why the score is what it is: all 16 factors grouped by pillar with sub-score, weight, raw input and label, plus the three weakest factors. |
| `compare_vaults` | `vaults[]` (2-8 of `chainId`, `address`) | Side-by-side scores, pillars, live APY/TVL, yieldQuality and exitSafety, ranked by composite. Unscored entries come back `found:false`. |
Every result carries the disclaimer: research and information, not investment advice.
A good first call is `find_vaults` (for example `asset: "USDC"`, `chain: "base"`). It returns a short
list you can act on, and each row carries what the other tools need. Then call
`check_route_survival` for the vault you pick, before any deposit.
## About the hosted endpoint
* **Stateless.** Each request stands alone and replies with plain JSON, not a stream. During
`initialize` the server returns an `Mcp-Session-Id` header and compliant clients send it
back on later requests. It only carries the client name for our usage counts and is not
used for anything else.
* **Same data as the API.** The hosted tools read the same `/v1` data and share its
disclaimer. Browser-based MCP clients can call it: CORS is open and the session header is
exposed.
* **Shared infrastructure.** All hosted callers share one upstream request budget. Under heavy
load a call can come back as a tool error mentioning the rate limit; retry after the
interval it states. For sustained or latency-sensitive use, run the server locally so
requests come from your own address, or call [`/v1`](/api-reference/introduction) directly.
* **What we log.** For each hosted call: the time, your IP address, the client name and
version your MCP client announces, the method, the tool name, the outcome and how long it
took. We do not log tool arguments.
## What it refuses to do
There is no deposit, sign, or send tool, and none will be added. The point of the server is the
refusal: an agent asks whether a route survives a round trip and is told **no** before it moves a
user's money. Execution, where it exists, is a separate API with its own guards, not an MCP tool.
Source: [https://github.com/gveshk/atlasyield-mcp](https://github.com/gveshk/atlasyield-mcp). Data licence: [https://atlasyield.club/data-license](https://atlasyield.club/data-license)
# Score a basket
Source: https://docs.atlasyield.club/api-reference/post-basket
api-reference/openapi.yaml POST /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.
# Accounts and funding
Source: https://docs.atlasyield.club/asset-flow/accounts
Two ways in, one ownership model — the user owns the keys at every step.
This section describes exactly how money moves when a user acts on an Atlas portfolio.
The invariant throughout: **funds go from the user's account into the underlying
protocol's vault, with the user as the on-chain owner at every step.** AtlasYield never
sits in the middle of the flow.
## Accounts
Two ways in, one ownership model:
* **Connect a wallet.** Web3 users connect an existing self-custodial wallet and
transact from it directly.
* **Sign in with email or Google.** Web2 users get an embedded self-custodial wallet
(via Privy) paired with an ERC-4337 smart account. The key is the user's; AtlasYield
cannot move funds from it. For these users the app calls it an "Account" and hides the
crypto plumbing, but the ownership model is identical.
For smart-account users, gas on supported chains is sponsored by a paymaster (all
supported chains except BNB Chain), so deposits and withdrawals don't require the user
to hold native gas tokens first.
## Funding
Users fund their account with a card/bank onramp or by bridging existing crypto in. The
funding leg is a plain transfer into the user's own address — no Atlas contract is
involved.
# Deposits
Source: https://docs.atlasyield.club/asset-flow/deposits
Direct and routed paths, and the two hard safety rules on every leg.
When the user accepts an allocation, each position becomes one deposit leg. A leg is
executed one of two ways:
* **Direct path** — the user is already on the vault's chain holding its underlying
token. The app builds the protocol's own deposit call and the user's account executes
it directly.
* **Routed path** — the user's funds are on another chain or in another token. Execution
goes through an intent-based relayer: a solver delivers the required token on the
destination chain and executes the deposit calldata there, typically settling in
seconds for cents.
## Two hard safety rules
Both checks run before any funds move, and both fail closed.
1. **The user must be the encoded recipient.** Deposit calldata always names the user as
`receiver` / `onBehalfOf`. For the minority of protocols whose vaults credit shares
to whatever address calls `deposit()` (rather than to a named recipient), the routed
path is refused outright — those vaults can only be entered on the direct path, where
the user's own account is the caller.
2. **Route targets are validated.** Where a deposit routes through a protocol's own
router (e.g. Pendle), the transaction target returned by the protocol's API is
checked against the known canonical router address before anything is signed. An
unexpected target aborts the deposit.
Where the user's wallet supports batched execution (EIP-5792), multiple legs are bundled
into a single approval flow; otherwise legs execute sequentially, each individually
signed.
The result of a deposit is vault shares (or the protocol's equivalent position token)
held **in the user's account**. Positions remain visible and withdrawable even if
AtlasYield disappears — they live in the underlying protocols, not in Atlas.
# Withdrawals
Source: https://docs.atlasyield.club/asset-flow/withdrawals
Exit in-app through the same account that deposited — and what never happens.
Withdrawals are built and executed in-app through the same account that deposited:
the app constructs the protocol's redeem/withdraw call (including protocol-specific
routes where a position token must be swapped back to a base asset) and the user signs
it. This matters especially for email/Google users, whose smart account is driven by the
app — they are never stranded needing a protocol's own interface to exit.
Withdrawal *speed* is a property of the vault, not of Atlas: instant vaults exit
immediately; queue/cooldown vaults exit on the protocol's schedule. This is exactly what
the [Liquidity pillar](/score/pillars-and-factors#pillar-3--liquidity) scores and what
the [tier policy](/engine/tier-policy) caps.
## What never happens
* **No pooling:** user funds are never commingled with other users' or with Atlas's.
* **No discretionary movement:** Atlas has no key, no allowance, and no permission that
would let it move user funds.
* **No hidden legs:** every transaction the user signs is shown before signing, and every
leg's outcome is verifiable on-chain.
# Coverage
Source: https://docs.atlasyield.club/coverage
What the Atlas index tracks today, and how coverage grows.
As of the **8 October 2026** snapshot, Atlas publishes scores for **535 vaults**
representing about **\$43.6B** in TVL, across **9 protocols** and **6 chains**. Execution
is supported on Ethereum, Base, Arbitrum, Optimism, BNB Chain and Polygon. Solana is
scored only (see below).
| Protocol | Scored vaults |
| - | - |
| Morpho | 197 |
| Aave v3 | 90 |
| Beefy | 85 |
| Yearn v3 | 54 |
| Pendle | 41 |
| Kamino | 36 |
| Euler | 29 |
| EtherFi | 2 |
| Ethena | 1 |
| Chain | Scored vaults |
| - | - |
| Ethereum | 324 |
| Base | 111 |
| Arbitrum | 37 |
| Solana | 36 |
| Optimism | 17 |
| BNB Chain | 10 |
Coverage is uneven by design. Most of the scored set sits in Morpho, Aave and Beefy, while
newer adapters contribute a thin tail. A vault only enters the scored set when its data
pipeline meets the quality bar described in [Reading a score](/score/reading-a-score) —
scores carry a `dataQuality` flag, and on this snapshot 524 were `sufficient`, 6 `partial`
and 5 `fallback`.
## Verify this yourself
These counts move daily as vaults cross the TVL floor or adapters change. Rather than trust
the numbers on this page, read the machine-readable snapshot:
```
https://raw.githubusercontent.com/gveshk/atlasyield-score-history/main/latest.json
```
Every scored vault, with its composite, pillar scores, APY, TVL and `dataQuality`, for the
current day. The [full history](/score/public-record) is committed daily to a public
repository.
The route-survival screen is published in the same commit:
```
https://raw.githubusercontent.com/gveshk/atlasyield-score-history/main/routes-latest.json
```
One row per screened vault with `verdict`, `reasonClass`, `path`, `usdIn`, `usdOut`,
`retained` and `checkedAt`, plus a `probe` block stating what was measured. Read that block
before quoting a count: the probe is **same-chain only** (USDC on the vault's own chain,
into the position, straight back), so a `NO_ROUTE` says nothing about bridging in from
another chain. `reasonClass` separates `protocol_refused` (the protocol's own router will
not quote the position; the vault is dead for entry or exit) from `no_aggregator_quote`
(no same-chain swap into the underlying, typical of LP-token vaults, which may still be
exitable by redeeming and unwinding by hand).
The admin-topology screen (who can change a vault, and how fast) is published in the same
commit too:
```
https://raw.githubusercontent.com/gveshk/atlasyield-score-history/main/admin-latest.json
```
One row per screened vault with `class`, `curatorId`, `curatorRating`, `timelockSeconds`, a
role summary (no addresses) and `checkedAt`. Aave, Pendle, EtherFi, Ethena and BNB vaults
are not screened. A vault controlled by a single key scores 40 on this factor if its curator
is rated established and 10 otherwise. On-chain DAO governance (a token-vote governor or Sky)
scores like a strong multisig, and an Aragon DAO like a weak one, since its voting plugin is not
inspected. A role's `delaySeconds` is the delay a timelock or supervisor adds in front of it.
## What is not covered
Named gaps, stated plainly because an undisclosed one is worse than a known one:
* **Spark** and **Sky** (including sUSDS) are not scored today.
* **Compound** is not scored today.
* On Solana, only **Kamino Earn vaults** are scored (added 24 September 2026, chain id
`792703809`). Kamino Lend reserves, Jupiter Lend and PT markets on Solana venues are not.
Solana vaults are scored only: Atlas has no Solana execution, so they never appear in a
suggested portfolio. Solana addresses are case-sensitive; use the `onchainId` field, not
the lowercased `vaultId`, to look one up on-chain.
## Programmatic access
The same scores that power the app are available via a
[read-only API](/api-reference/introduction) for teams that want to quote the Atlas Score
on their own earn surfaces. Scores refresh on a roughly four-hour pipeline; the public
snapshot is committed once a day.
Agents can reach the same data through the [MCP server](/api-reference/mcp), hosted at
`https://atlasyield.club/mcp` or run locally with `npx`. To ask what is covered right now
instead of reading this page, call `GET /v1/scores?fields=compact&limit=1` and read `total`,
or the `get_coverage` MCP tool.
# Design principles
Source: https://docs.atlasyield.club/design-principles
The five commitments every part of AtlasYield is built on.
* **Neutrality.** AtlasYield is not paid by protocols to be scored, and the score cannot
be bought. The scoring model treats every vault the same way.
* **Ex-ante accountability.** Every score is published *before the fact* and snapshotted
daily to a public git repository. The history cannot be quietly rewritten after a vault
blows up — anyone can check what we said, when we said it, against what happened next.
* **Determinism, not "AI".** There is no language model and no black-box classifier in
the scoring or allocation path. Same inputs in, same score and same portfolio out,
every time.
* **Non-custody.** AtlasYield never holds user funds, never pools deposits, and never
moves money on its own. Every position sits in the user's own account, in the
underlying protocol's own vault, and nothing moves without the user's signature.
* **Honesty about uncertainty.** Every score carries a [data-quality flag](/score/reading-a-score),
and the methodology states plainly what a score is not.
# What the Engine does not do
Source: https://docs.atlasyield.club/engine/boundaries
The boundaries that keep the Engine a proposal, never a custodian.
* **It never takes custody.** It proposes a portfolio; the user holds their own funds and
signs every transaction.
* **It does not rebalance on its own.** Nothing moves without an explicit signature.
* **It makes no yield promise.** Expected return is an estimate from current rates and
past variance, not a guarantee.
* **It never overrides the score.** It can only choose among vaults the scoring model
already judged eligible.
* **It is not "AI".** There is no guessing model and no language model in the loop — it
is deterministic optimization with the parameters published on the
[tier policy page](/engine/tier-policy).
# How the Engine works
Source: https://docs.atlasyield.club/engine/how-it-works
A mean-variance optimizer in the tradition of Markowitz — five deterministic steps.
A score rates one vault at a time. Turning scored vaults into a portfolio is a second,
separate job, done by the Atlas Engine — a mean-variance optimizer in the tradition of
Harry Markowitz. Markowitz, not magic: deterministic quantitative math, with its policy
parameters [published in full](/engine/tier-policy).
## The pipeline — five deterministic steps
Start from every scored vault, keep only those that clear the chosen tier's hard
gates — minimum Atlas Score, minimum TVL, minimum audit count and track record, an
allowed asset class, and a permitted withdrawal speed. A vault that misses any single
gate is never considered.
For each survivor the Engine reads two numbers from public data: current APY as
expected return, and the historical variance of that APY — extended to a covariance
across vaults, with statistical shrinkage to steady thin histories — as risk. No
private inputs, no forecasts.
Solve for the mix of vaults with the best expected return for the risk taken. A
single risk-aversion dial, λ, set by the user's risk score, decides how hard the mix
leans toward yield versus away from volatility.
The raw optimum is held inside the tier's guardrails — caps per vault, per protocol,
and per chain, a floor under each position, and a tighter cap on vaults with little
history. Concentration is trimmed proportionally until every cap holds.
A set of positions with explicit percentages that sum to the full amount. Same inputs
in, same portfolio out — every time.
When a candidate set has too little history for the covariance step to be trustworthy,
the Engine falls back to a simpler, equally deterministic diversification rule rather
than optimize on noise — and the result is labelled when that happens.
# Per-tier policy
Source: https://docs.atlasyield.club/engine/tier-policy
Three tiers, one rulebook — every number read straight from the allocation code.
The user's risk score (1–10) selects one of three tiers. All three share the same
optimizer; they differ only in which vaults are eligible and how concentrated the result
may get. Every number below is read straight from the allocation code.
| Parameter | Conservative | Balanced | Aggressive |
| - | - | - | - |
| Risk-score band | 1–3 | 4–7 | 8–10 |
| Min Atlas Score | 70 | 55 | 40 |
| Min TVL | \$50M | \$10M | \$1M |
| Min audits | 2 | 1 | 1 |
| Min track record | 90 days | 30 days | none |
| Assets | Stablecoins, ETH, BTC | + curated yield-bearing dollars | + long-tail USD tokens |
| Max withdrawal wait | Instant only | ≤ 10 days | ≤ 30 days |
| Max per vault | 35% | 35% | 35% |
| Max per protocol | 50% | 60% | 50% |
| Max per chain | 60% | 60% | 60% |
| Positions | 3–5 | 3–6 | 3–8 |
| Risk-aversion λ | 0.1–0.5 | ≈0.9–2.0 | ≈4.7–10 |
λ is the risk-aversion dial handed to the optimizer, set on a continuous 0.1–10 scale by
the exact risk score; the ranges shown are what each tier's band maps to. A higher λ
leans harder away from volatility. Caps and thresholds are allocation policy, not the
scoring math.
# What AtlasYield is
Source: https://docs.atlasyield.club/index
The independent judgment layer for on-chain yield.
Everything in these docs — scores, bands, allocations, and methodology — is research and
general information, **not investment advice**. See [Limitations and disclaimer](/limitations).
DeFi produces thousands of yield-bearing vaults, and almost no neutral way to judge them.
Yields are advertised by the protocols that earn fees from them; aggregators rank by APY;
the risk that actually destroys principal — exploits, admin keys, emission cliffs, frozen
withdrawals — is left for the depositor to price alone.
AtlasYield is built as the judgment layer that sits between depositors and that universe.
It does three things:
A 0–100 rating of every vault it covers, built from four pillars and sixteen factors,
published on a timestamped, git-verifiable public record.
A deterministic portfolio builder that turns scored vaults into a risk-adjusted
allocation under explicit, published policy constraints.
Continuous re-scoring of every covered vault, with dated, evidence-backed risk calls
when the model's judgment of a vault changes materially.
The consumer app at [atlasyield.club](https://atlasyield.club) is the live demonstration of
all three: you can read the scores, have the Engine propose a portfolio, and deploy into it
from an account you control — non-custodially, signing every transaction yourself.
Scoring has been live since **May 5, 2026**; verifiable public snapshots since
**July 8, 2026**.
## System overview
The score rates one vault at a time. The Engine composes scored vaults into a portfolio.
Execution moves the user's funds into that portfolio under hard safety rules. Monitoring
watches everything after the fact and feeds back into the score.
```
On-chain + protocol data
│
▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Atlas Score │ ──▶ │ Atlas Engine │ ──▶ │ Execution │
│ 4 pillars, │ │ eligibility → │ │ user-signed, │
│ 16 factors, │ │ mean-variance → │ │ non-custodial │
│ 0–100 composite │ │ policy caps │ │ deposits │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │
▼ ▼
Daily public snapshots Continuous monitoring,
(git-stamped, ex-ante) risk calls, rebalancing
calls (future)
```
The full v1.0 litepaper — the Score, the Engine, asset-flow mechanics, and limitations —
as a single document, with a downloadable PDF.
# Limitations and disclaimer
Source: https://docs.atlasyield.club/limitations
What a score is not — read this before acting on anything Atlas publishes.
* A score is an **opinion**, formed from public on-chain and protocol data. It is not a
guarantee and not a promise about any vault.
* Scores can be wrong. Data can be stale, incomplete, or misreported at the source, and
the model can misjudge a vault.
* Smart-contract risk can never be fully scored away. A high Safety score lowers the
odds of failure; it does not remove them. Any contract can be exploited.
* Past performance is not future results. A strong track record is evidence, not a
forecast.
Everything AtlasYield publishes — scores, bands, pillar breakdowns, allocations, calls,
and these docs — is research and general information. It is **not investment advice**
and not a recommendation to buy, sell, or hold anything. Nothing here is an offer or
solicitation to enter any transaction, and using AtlasYield creates no fiduciary or
advisory relationship. DeFi carries real risk, up to and including the **total loss** of
the capital you deploy. You are solely responsible for your own decisions — do your own
research and, where appropriate, consult a licensed professional before you act.
# Litepaper v1.0
Source: https://docs.atlasyield.club/litepaper
The AtlasYield litepaper — July 2026.
The AtlasYield Litepaper v1.0 (July 2026) is the canonical statement of the system: the
Atlas Score, the Atlas Engine, the mechanics of asset flow, monitoring and calls, and the
limitations we publish alongside all of it.
Everything in the litepaper is also in these docs, section by section — the litepaper is
the same content as a single citable document.
AtlasYield Litepaper v1.0 — July 2026. Research-paper format, \~15 pages.
## Contents
| Section | In these docs |
| - | - |
| 1. What AtlasYield is | [Overview](/index) |
| 2. Design principles | [Design principles](/design-principles) |
| 3. System overview | [Overview → System overview](/index#system-overview) |
| 4. The Atlas Score | [Pillars and factors](/score/pillars-and-factors) · [Reading a score](/score/reading-a-score) · [The public record](/score/public-record) |
| 5. The Atlas Engine | [How it works](/engine/how-it-works) · [Tier policy](/engine/tier-policy) · [Boundaries](/engine/boundaries) |
| 6. Mechanics of asset flow | [Accounts](/asset-flow/accounts) · [Deposits](/asset-flow/deposits) · [Withdrawals](/asset-flow/withdrawals) |
| 7. Monitoring and calls | [Monitoring](/monitoring) |
| 8. Coverage | [Coverage](/coverage) |
| 9. Limitations and disclaimer | [Limitations](/limitations) |
The litepaper is research and general information, **not investment advice**.
*AtlasYield — scoring live since 2026-05-05 · verifiable public snapshots since 2026-07-08.*
# Monitoring and calls
Source: https://docs.atlasyield.club/monitoring
Scoring does not stop at publication.
Scoring does not stop at publication. Every covered vault is re-scored continuously as
new data arrives, and the daily snapshot commits the full set to the
[public record](/score/public-record).
## Risk calls
When the model's judgment of a vault changes materially — a score cut on deteriorating
safety or sustainability — AtlasYield publishes a dated, narrated call with its evidence:
what was cut, when, why, and (over time) what happened next. A ratings brand is built on
calls, not dashboards, and the git-stamped history keeps the calls honest.
Every call, dated and narrated, on the live site.
## Rebalancing calls (future)
The same machinery points forward: when the Engine's optimal portfolio for a tier drifts
materially from a user's held portfolio — because scores moved, yields decayed, or a
position was cut — Atlas will surface a *rebalancing call*: a concrete proposed set of
exits and entries, with the reasoning attached. Like everything else, a rebalancing call
is a proposal the user signs or ignores. Atlas will never rebalance autonomously; the
non-custody invariant is permanent.
# Partner access
Source: https://docs.atlasyield.club/partner-access
Keys for teams embedding Atlas scores in their own product.
Everything in the [API reference](/api-reference/introduction) is public and keyless.
Partners embedding Atlas in their own interface get a key on top, sent as `x-api-key`.
It is an unlock, not a gate: every public endpoint behaves the same with or without it.
What a partner key adds:
* **Bulk factor breakdowns**: every vault's full 16-factor breakdown in one call, instead of one vault per request.
* **Score history**: the timestamped series of every scoring run for a vault, as stored, never recomputed.
* **A larger request budget** than the per-IP public limit.
The partner endpoint reference and pricing are shared directly.
## Get a key
Email **[admin@atlasyield.club](mailto:admin@atlasyield.club)** with what you are building and which vaults you list.
Opens your mail client. If nothing happens, copy the address above.
We reply with a key, the partner endpoint reference, and pricing. Scoring only: deposit
routes and execution stay on your side.
# Pillars and factors
Source: https://docs.atlasyield.club/score/pillars-and-factors
Four pillars, sixteen factors, one 0–100 number.
Every covered vault is scored 0–100 across four pillars built from sixteen underlying
factors. Fifteen factors contribute additively within their pillar; the sixteenth,
exploit history, acts as a **multiplier on the entire Safety pillar** — a protocol with a
serious prior incident cannot average the damage away. An incident counts only if it hit
the contracts we score and left depositors with an uncovered loss; incidents in legacy or
adjacent products, integrators, or fully reimbursed events are recorded but not scored.
The pillars combine into the composite in a way that punishes imbalance: a vault cannot
paper over a weak pillar with a strong one. A fragile vault paying a huge yield stays a
fragile vault.
On purpose, AtlasYield does **not** publish exact weights, formulas, or thresholds:
a score you can game is a score no one should trust. The factors below are described at
concept level.
## Pillar 1 — Yield
Not just how much a vault pays, but how trustworthy that yield is.
| Factor | What it measures |
| - | - |
| Yield level | Current payout, read in the context of its asset class — a high headline number is weighed against the risk taken to earn it. |
| APY stability | How steady the yield has been; wild week-to-week swings read as lower quality. |
| APY persistence | Whether the yield has endured rather than spiking briefly and collapsing. |
| Yield source | Where the return actually comes from — real lending demand, trading fees, or temporary incentives — and how legible that source is. |
## Pillar 2 — Safety
How likely the vault is to lose principal to a failure, an exploit, or bad governance.
| Factor | What it measures |
| - | - |
| Audit quality | Depth and credibility of the protocol's security reviews — who did them and how thorough they were. Firms are tiered by reputation (tier 1: Trail of Bits, OpenZeppelin, Spearbit/Cantina, ChainSecurity, Certora, Sigma Prime, Consensys Diligence, OtterSec, Zellic, or formal verification by any firm). Only audits of the contracts we score count, and an audit older than 24 months counts for less. |
| Protocol maturity | Time live holding real money — evidence that survives no other test. |
| TVL depth (safety) | How much capital sits in the vault; deeper pools are harder to manipulate. |
| TVL stability | Whether deposits are steady or prone to sudden flight. |
| Admin topology | Who can change the vault and how fast, read per vault every day: timelocks, multisig strength (strong = 3+ signers and a majority), and for a single admin key, the curator's track record (40 established, 10 unknown or new). Never below 10. |
| Chain security | The settlement assurance of the chain underneath the vault — whether it settles its own state, who operates the sequencer, and whether you keep a permissionless exit if that operator censors or halts. |
| Exploit history | Whether the protocol has been broken before. Works as a multiplier on the whole pillar. |
## Pillar 3 — Liquidity
How reliably you can get your money back out — quickly, in full, and at size.
| Factor | What it measures |
| - | - |
| Withdrawal type | Instant on demand, or through a queue, cooldown, or lock-up. |
| TVL depth (liquidity) | Whether the pool is deep enough to exit a real position without moving the price against yourself. |
## Pillar 4 — Sustainability
Whether the yield is built to last — or quietly living on borrowed time.
| Factor | What it measures |
| - | - |
| Emission dependency | How much of the return leans on token incentives that can be cut at any time. |
| Asset risk | The risk of the underlying asset itself — even a flawless vault inherits the fate of what it holds. |
| Utilization health | For lending markets, whether utilization sits in a healthy band rather than pinned dangerously high. |
# The public record
Source: https://docs.atlasyield.club/score/public-record
Ex-ante, git-stamped, tamper-evident score history.
Scores refresh on a roughly four-hour pipeline as new data arrives. Once a day the full
set is snapshotted to a public GitHub repository. Every snapshot is written **before the
fact** and stamped by git, so the history is tamper-evident — anyone can check what we
said, when we said it, against what happened next.
This ex-ante track record is the core of the project: a rating with no verifiable history
is just an opinion with a logo.
## Reading history across engine versions
Every score carries a `scorerVersion`. The engine changes occasionally — a factor is added,
a weight is retuned — and when it does, the version is bumped and old snapshots are left
exactly as they were written. We do not rescore history.
That means **scores are comparable within a version, not across one**. Any analysis of the
record — hit rates, calibration, score-versus-outcome — must group by `scorerVersion` or it
will be comparing two different instruments. The trade-off is deliberate: rewriting history
to match the current engine would make the numbers prettier and the record worthless.
Daily score snapshots, git-stamped since July 8, 2026. Scoring live since May 5, 2026.
# Reading a score
Source: https://docs.atlasyield.club/score/reading-a-score
Data-quality flags and score bands — how much to lean on the number.
## Data quality
A score is only as good as its inputs, so every score carries one of three flags —
never hidden:
Complete, current data across the factors that matter for this vault. The score rests
on the inputs we wanted.
Some inputs were thin or missing and were handled conservatively. The score is still
meaningful, but stands on less ground than a "sufficient" one.
Data was genuinely sparse — a new or obscure vault we could not fully observe. The
score is published anyway and labelled as our weakest read, not our best.
## Score bands
Alongside the number, each vault carries a plain-English band:
* **Conservative** — top band; suitable where preserving capital is the priority.
* **Balanced** — the middle band.
* **Aggressive** — meaningfully more risk; eyes-open territory.
Bands describe risk posture, **not a recommendation** to buy or avoid anything.