Integrate Vigil
Keep your users' money out of weak lending pools on Stellar. Choose how your product connects, set the minimum score a pool needs, check the rule on a live pool, then hand the brief to your AI coding assistant. The grades come from the pool ratings.
Reading the live ratings. The first load of the hour takes about a minute and a half.
01Choose how you connect
Every Blend pool and DeFindex strategy on mainnet with its grade, score, reasons and whether Vigil allows deposits. Use it to label pools in your app or to drop weak ones before your backend picks one.
- Does not
- Nothing on-chain stops a deposit. If your backend has a bug or its key is stolen, money can still reach a weak pool.
- Effort
- Hours. One HTTP call, no keys, open to browsers (CORS).
- Works on
- Mainnet pools, today.
- You trust
- yieldpilot.org's server. Every run's inputs are archived, so anyone can recompute a rating and check it.
02Set your rule
A pool needs at least this score to receive a deposit. YieldPilot's own wallets use . It starts at 1: the registry signs 0 for pools Vigil holds back, so a minimum of 0 would let them in.
Maximum rating ageA new rating is signed every 30 minutes. The registry stops counting one after 2 hours, so a longer limit would change nothing. If publishing stops, deposits stop too: the rule fails closed.
03See the rule on a live pool
Waiting for the live ratings…
04Hand it to your AI
Paste the brief into Claude Code, Cursor or any assistant that can read your repository. It carries your choices, the addresses, starting code and a done-when list, and points the assistant to the full guide, which it can fetch itself.
# Integrate Vigil pool risk ratings: Show ratings
You are working in our codebase. We are adding Vigil, a risk rating for Stellar lending pools (Blend V2 and v2.1, and DeFindex strategies), so that our app shows each pool's Vigil grade, and our backend never sends a deposit to a pool Vigil does not allow.
First read the full integration guide: https://yieldpilot.org/integrate.md
Then find where we list pools to users and where our backend picks the pool a deposit goes to, and tell me your plan before you change anything.
## Decisions already made
- Path: Show ratings (Read the JSON API).
- Minimum score: 60. A pool must score at least this to receive a deposit. Grades: A is 80 and up, B 65 to 79, C 50 to 64, D 35 to 49, E under 35.
- Maximum rating age: 7200 seconds.
- Network: mainnet ratings over HTTPS.
- Fail closed: when the rating is missing, unreadable, too old or under the minimum, do not deposit. Never block withdrawals on a rating.
- No Vigil SDK (it is not published). Start from the code below.
## Facts
- `GET https://yieldpilot.org/api/ratings`: no key, CORS open. Top level: `engineVersion`, `computedAt` (unix seconds), `stale` (true when the last refresh failed), `ratings[]`.
- Each rating: `poolId`, `name`, `protocol` (blend | defindex), `grade` (A to E, or NR for not rated), `score` (0 to 100, higher is safer, null when NR), `eligibleForDeposit`, `reasons[]`, `hardRules[]`, `tvlUsd`, `yields[]`.
- A deposit is allowed when the pool is rated, `eligibleForDeposit` is true and `score` is at least the minimum. This is the same rule RiskGate enforces on-chain.
- Every run's inputs are archived for 90 days at `https://yieldpilot.org/api/ratings/runs`, so a rating can be recomputed and checked.
## Code to start from
File: vigil.ts (server or browser)
```ts
// Vigil pool ratings from the public API. Cache the response for 5 minutes or more:
// ratings are recomputed every 30 minutes.
export type VigilRating = {
poolId: string; // Blend pool or DeFindex strategy contract id (mainnet)
name: string;
grade: "A" | "B" | "C" | "D" | "E" | "NR";
score: number | null; // 0..100, higher is safer; null when not rated
eligibleForDeposit: boolean; // false when a hard rule holds the pool back
reasons: string[];
hardRules: string[];
};
export const MIN_SCORE = 60;
export const MAX_AGE_SECS = 7200;
export async function fetchVigilRatings(): Promise<{ computedAt: number; ratings: Map<string, VigilRating> }> {
const res = await fetch("https://yieldpilot.org/api/ratings");
if (!res.ok) throw new Error(`Vigil API HTTP ${res.status}`);
const body = (await res.json()) as { computedAt: number; ratings: VigilRating[] };
return { computedAt: body.computedAt, ratings: new Map(body.ratings.map((r) => [r.poolId, r])) };
}
// The same rule RiskGate enforces on-chain. Anything unknown, unrated, held back,
// under the minimum or too old is refused: fail closed.
export function depositAllowed(r: VigilRating | undefined, computedAt: number, nowSecs = Date.now() / 1000): boolean {
if (!r || r.score === null || !r.eligibleForDeposit) return false;
if (nowSecs - computedAt > MAX_AGE_SECS) return false;
return r.score >= MIN_SCORE;
}
```
## Done when
- [ ] Pools show their Vigil grade and score; unrated pools say "not rated".
- [ ] The code that picks a deposit target calls `depositAllowed` and skips every pool it refuses.
- [ ] If the API call fails or `computedAt` is older than `MAX_AGE_SECS`, no deposit is made (fail closed) and the reason is logged.
- [ ] Unit tests use a saved API response, with no live network calls, and cover: allowed, under the minimum, held back (`eligibleForDeposit: false`), not rated, stale, API down.
## Do not
- Do not copy scores into config or code: read them each time, caching for at most 5 minutes.
- Do not use a minimum of 0: the registry signs 0 for pools Vigil holds back, so 0 lets them through.
- Do not treat a missing or unreadable rating as safe.
05Reference
Addresses
- Ratings API
https://yieldpilot.org/api/ratings- Run archive
https://yieldpilot.org/api/ratings/runs- RiskRegistry · testnet
CB4LXLCCD7YDND5FBVXPKPHUQMF7JFSDRVXHG7ZZTWWNPJ6WDCXDNDF6- RiskGate · testnet
CD6BDS7R5K3IUCQSJUZUWAGLTR47EZOYEVCO5MPT7YGNBNQRHSNY5VMS- Rated testnet demo pool
CBI7WAUQ4NPQFZW4C3MDSVFAZJWV3RCLZSTTMA5OZ6BTPEQMOZZNSZ3Z- RPC
https://soroban-testnet.stellar.org
RiskGate errors
A refused call fails with Error(Contract, #code).
4100NotInstalledno RiskGate params for this smart account and rule4101AlreadyInstalledRiskGate is already on this rule4102InvalidParamsmin_score over 100, a minimum without a registry, or a registry with max_age_secs 04103OnlyCallContractRiskGate attaches only to CallContract rules4104NoSignersnot every signer of the rule authenticated4105ContextNotAllowedcontract creation is refused4106WrongContractthe called contract is not the rule's target4107FunctionNotAllowedonly submit, submit_with_allowance, claim and transfer pass4108BadArgsthe arguments do not decode as Blend's or the token's4109AccountMismatchfrom, spender and to must all be the smart account4110EmptyRequestssubmit with no requests4111RequestTypeNotAllowedonly supply and withdraw (request types 0 to 3)4112NegativeAmounta negative amount4113RecipientNotAlloweda transfer to an address not in allowed_recipients4114RatingUnavailablethe registry has no rating for the pool4115ScoreTooLowthe pool's rating is under the account's minimum4116RatingStalethe pool's rating is older than max_age_secsLimits today
- The registry and RiskGate are on testnet. A mainnet contract cannot call them yet; on mainnet, read the API or the testnet registry from your backend.
- One publisher signs the ratings (threshold 1). The registry takes up to 16 and returns their median.
- RiskGate guards Blend pool calls and token transfers; it refuses DeFindex vault calls.
- There is no published SDK: the code uses @stellar/stellar-sdk or soroban-sdk directly.
Everything on this page as Markdown: /integrate.md. How a score is made: the methodology. Every contract function, event and encoding: the contracts reference.