YieldPilot

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 age

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

Live pools

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 rule
4101AlreadyInstalledRiskGate is already on this rule
4102InvalidParamsmin_score over 100, a minimum without a registry, or a registry with max_age_secs 0
4103OnlyCallContractRiskGate attaches only to CallContract rules
4104NoSignersnot every signer of the rule authenticated
4105ContextNotAllowedcontract creation is refused
4106WrongContractthe called contract is not the rule's target
4107FunctionNotAllowedonly submit, submit_with_allowance, claim and transfer pass
4108BadArgsthe arguments do not decode as Blend's or the token's
4109AccountMismatchfrom, spender and to must all be the smart account
4110EmptyRequestssubmit with no requests
4111RequestTypeNotAllowedonly supply and withdraw (request types 0 to 3)
4112NegativeAmounta negative amount
4113RecipientNotAlloweda transfer to an address not in allowed_recipients
4114RatingUnavailablethe registry has no rating for the pool
4115ScoreTooLowthe pool's rating is under the account's minimum
4116RatingStalethe pool's rating is older than max_age_secs
Limits 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.