> For the complete documentation index, see [llms.txt](https://docs.gage.cash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gage.cash/developers/api.md).

# API

The read API the app uses. Several services, JSON everywhere, amounts in raw units.

The app reads from the indexer, the valuation service (whose suggested-rates model runs as a separate deployment), the notifier behind partner vaults' profiles and the support service. Every shape below is the integration contract those services implement. gage runs these services for the app; gage-sdk and the agent API read them for you. What they serve can be rebuilt from the chain's events.

Building an agent? Use the [HTTP API for agents](https://docs.gage.cash/ai-agents/api.md), the [TypeScript SDK](https://docs.gage.cash/ai-agents/sdk.md) or the [MCP server](https://docs.gage.cash/ai-agents/mcp.md). They prepare unsigned transactions, each with a review link on gage.cash. The schemas below describe the underlying app services.

## Conventions

* JSON everywhere. Addresses are lowercase hex strings.
* Amounts are decimal strings in **raw on-chain units** (USDG raw units, token raw units, sGAGE wei). Format them with the asset's `decimals`.
* Timestamps are unix seconds. Enums are upper-case strings matching the Solidity enums.
* Every list endpoint takes `limit` (default 50, max 200) and `cursor`, and returns `{ items, nextCursor }`.
* Errors are `{ error: { code, message } }` with a 4xx or 5xx status.
* Every service exposes a health endpoint.

## Shared shapes

```
Deal        { id, borrower, kind: "ERC20"|"UNIV4_POSITION", token, amountOrTokenId, cap, term, listingExpiry, minPrice,
              lender|null, price|null, fee|null, fundedAt|null, expiry|null, graceEnd|null,
              state: "LISTED"|"FUNDED"|"RECLAIMED"|"CLAIMED"|"CANCELLED", lane: "STOCK"|"ETH"|"MEME"|"POSITION",
              txs: { listed, funded|null, settled|null }, listedAt, openBidCount, bestBid|null }
Bid         { id, dealId, lender, price, expiry, state: "OPEN"|"WITHDRAWN"|"ACCEPTED", placedAt, tx }
Balance     { account, asset, amount, kind: "USDG"|"ERC20"|"NFT" }
Drip        { id, account, source: "deal"|"lp", dealId|null, tokenId|null, total, claimed, start, length,
              unlockedNow, claimableNow, curve: [{ t, unlocked }] }
Asset       { token, symbol, name, decimals, lane, allowed, minAmount, maxDealRaw, maxOpenRaw, openRaw,
              uiMultiplier|null, pendingMultiplier|null, effectiveAt|null, paused|null }
            — the last four stay null; read a Stock Token's from GET /stocks
Stock       { token, symbol|null, decimals|null, uiMultiplier, pendingMultiplier|null, effectiveAt|null, paused|null,
              changes: [{ oldMultiplier, newMultiplier, effectiveAt, block, tx }]|null }
Epoch       { n, startsAt, endsAt, weekly, dealBudget7, dealBudget21, reserved7, reserved21, liquidityBudget,
              rate7|null, rate21|null, priceUSDGPerSGAGE|null, lenderShareBps|null, released, rolledOver }
LPPosition  { tokenId, owner, tickLower, tickUpper, liquidity, weight, inRange, valueGAGE, emissionsEarned,
              creatorFeeEarned, lastCheckpoint, isSeed }
PoolSummary { poolId, currency0, currency1, fee, tickSpacing, sqrtPriceX96, tick, liquidity, priceSGAGEinGAGE,
              totalWeight, depthGAGE }
Burn        { at, usdgSpent, gageBought, sgageBurned, caller, tx }
```

`minPrice` is the asking price. A `listingExpiry` of `0` means open-ended. These shapes describe the legacy vault, where `graceEnd = expiry + GRACE` (48 hours). The native engines publish through `/v2/…` with each engine's own grace: 172,800 s on the two earliest engines, 0 on V3 and the Intent cores, where the claim opens at expiry. `costBps = (cap − price) × 10000 ÷ price`.

## Indexer

gage runs it for the app; gage-sdk and the agent API read it for you. Built on Ponder.

| Endpoint                                                          | Returns                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /listings?lane=&term=&asset=&sort=newest\|expiry\|cap\|cost` | `{ items: Deal[], nextCursor }`: LISTED deals                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `GET /deals/:id`                                                  | `{ deal, bids, reward: { total, lender, borrower, epoch, budgetExhausted, drips } \| null }`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `GET /deals?wallet=&state=`                                       | `{ items: Deal[], nextCursor }`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `GET /portfolio/:wallet`                                          | `{ asBorrower, asLender, bids, balances, drips, summary: { receivedAlready, stillAtStake, paidOut, awaitingExpiry } }`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `GET /rewards/:wallet`                                            | `{ drips, claimableNow, stillDripping, epoch, pool, burnedThisWeek }`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `GET /pool`                                                       | `{ pool, epoch, burnedThisWeek, burns, emissionsRatePerSecond, budgets, floor }`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `GET /positions/:wallet`                                          | `{ positions: LPPosition[] }`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `GET /wallet/:address/positions`                                  | The wallet's Uniswap v4 positions, with `allowed` from the registry                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `GET /assets?lane=`                                               | `{ assets: Asset[] }`: the legacy vault's registry alone, its tokens and its limits. What new loans take is `gage.assets()` in gage-sdk, or [Accepted collateral](https://docs.gage.cash/borrow/accepted-collateral.md)                                                                                                                                                                                                                                                                                                                                                                                                    |
| `GET /assets/:token/deals`                                        | Recent funded deals on the asset, for the indicative cost                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `GET /stocks`                                                     | `{ chainId, block, at, historyFrom, stocks: Stock[] }`: what each Stock Token on the chain says about itself, read from the token and the same list on every scope. Multipliers are raw 18-decimal integers (`1000000000000000000` is one share per token); a scheduled change that has not taken effect is `pendingMultiplier` with its `effectiveAt`; `changes` are the multiplier changes that took effect since `historyFrom`, oldest first, or `null` until they are read. `block: null` means the service has not read the chain yet, not that there are no multipliers. For display only: amounts on chain stay raw |
| `GET /epochs`                                                     | `{ epochs: Epoch[] }`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `GET /stats`                                                      | The Protocol page's aggregates: lending TVL and what sits beside it, what depositors hold in the vaults by lend asset, fees (the fee streams it counts and their total), active deals, states, medians, emissions, sGAGE price history                                                                                                                                                                                                                                                                                                                                                                                     |
| `GET /price`                                                      | The GAGE price in USDG through the indexed pools: `{ usdgPerGage, change24hBps, history24h }`, hourly over the last day                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `GET /health/indexer`                                             | `{ ok, chainId, latestBlock, indexedBlock, lagBlocks }`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `GET /v2/positions?engine=&state=funding\|active\|settled&sort=`  | Native-engine positions, one row per loan, with quarters, dates and state, each lend asset's core included (its rows carry `asset`); `settled` is repaid and defaulted, never cancelled                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `GET /v2/positions/:engine/:id`                                   | One native-engine position                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `GET /v2/events?engine=&names=&after=&limit=`                     | One engine's indexed lifecycle events, oldest first, with a resumable cursor (limit 1–500)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `GET /activity?limit=`                                            | The newest loans listed and filled and the newest Earn deposits, newest first (limit 1–50), each with its USDG amount, collateral or strategy, and the wallets taking part                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `GET /deployment`                                                 | The deployment the indexer runs against                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

## Partner vaults

The indexer's `/intent/partners/…` routes serve the partner vaults and their fills. A route not about one vault serves the USDG generation unless `factory=` names a lend asset's factory (`intentV1Assets.<SYMBOL>.factory`); a vault's own routes find its generation themselves. Each snapshot carries `chainId`, `factory`, `mandateVersion`, `blockNumber`, `asOf` and `asset`, and every number in it is read from the chain at that one block.

| Endpoint                                                                       | Returns                                                                                                                                                                                                                                                                                                              |
| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /intent/partners/factory`                                                 | The factory: its core, reserve, fee bounds and protocol share, fill router, quote signer and whether funding is open                                                                                                                                                                                                 |
| `GET /intent/partners/vaults?limit=&cursor=`                                   | The partner vaults, 1 to 50 a page                                                                                                                                                                                                                                                                                   |
| `GET /intent/partners/vaults/:address`                                         | One vault: its name, the commitments fixed at creation (fee, longest term, universe), its tokens, current settings and the loosenings waiting out their three hours                                                                                                                                                  |
| `GET /intent/partners/vaults/:address/accounting`                              | What its shares are priced on, its loans and side pockets, what may leave now, and `settlement.settleable`, the loans anyone may settle                                                                                                                                                                              |
| `GET /intent/partners/vaults/:address/position/:account`                       | One holder's shares, their value, what it could withdraw now, its side-pocket claims and rewards                                                                                                                                                                                                                     |
| `GET /intent/partners/vaults/:address/preview?deposit=` or `?redeem=&account=` | The exact conversion the vault would make now, or why it would refuse                                                                                                                                                                                                                                                |
| `GET /intent/partners/vaults/:address/performance?period=1m\|3m\|ytd\|all`     | What 100 whole units of its asset deposited at the start of the period are worth across it, after every fee                                                                                                                                                                                                          |
| `GET /intent/partners/fills?limit=&cursor=`                                    | The fill router's fills, newest first, with each vault's part                                                                                                                                                                                                                                                        |
| `GET /intent/partners/filler`                                                  | The snapshot plus `filler`: whether funding is open, the last pass, and the latest decision for each open listing, newest first, at most 100 (why a listing waits, below)                                                                                                                                            |
| `GET /intent/partners/vaults/:address/filler`                                  | The same, kept to the decisions that mention this vault, each with `own: { maxUnits, refusal }`                                                                                                                                                                                                                      |
| `GET /intent/partners/links`                                                   | Every vault's short link, across all generations, LP vaults included: `{ schemaVersion, chainId, asOf, links: [{ link, vault, factory, name, kind }] }`, in creation order; `kind` is `lp` for an LP vault and `partner` for any other; the page is `https://gage.cash/v/<link>`                                     |
| `GET /intent/partners/pools?curator=`                                          | A DEX pool's vaults, one for each pool token gage lends, across all generations: `{ schemaVersion, chainId, asOf, pools: [{ name, curator, sides: [{ symbol, token, lent, vault, factory }] }] }`, one curator's alone with `curator=` ([Create your pool vaults](https://docs.gage.cash/developers/pool-vaults.md)) |

A `link` comes from the name a vault was created with: lower-case letters and digits, one dash between words. The first vault to claim it keeps it for good; a later vault with the same name takes the first characters of its own address (`silicon-4f2a`), and a rename changes `name`, never `link`. A token's Borrow page is `https://gage.cash/borrow/<link>`, its link by ticker among the tokens the release lists. Errors: `400 BAD_ADDRESS`, `BAD_QUERY`, `BAD_LIMIT`, `BAD_AMOUNT`, `BAD_CURSOR`; `404 UNKNOWN_PARTNER_VAULT`, `UNKNOWN_GENERATION`; `503 PARTNER_UNAVAILABLE`, for the links `503 LINKS_UNAVAILABLE` and for the pools `503 POOLS_UNAVAILABLE`, each with `Retry-After`.

A pool's two vaults share their curator and a name that ends in the pool's tag, its two tokens' symbols (`Fables NVDA/USDG`); a vault is a side of a pool where its tag names the asset it lends, and a side with no vault says whether gage lends that token (`lent`).

**Why a listing waits.** Each decision in `filler.decisions` is what the filler concluded about one open listing at its last pass. `listingId` names the listing and `state` the outcome:

| `state`                                    | What it means                                                                                                                                                      |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `funding_closed`                           | The factory names no fill router or no quote signer.                                                                                                               |
| `pending_fill`                             | An earlier funding is still unconfirmed, so nothing new is planned.                                                                                                |
| `capacity_unavailable`, `plan_unavailable` | The rates service gave no capacity reading or no signed plan. `code` is its own code, such as `PRICING_UNAVAILABLE` or `UNSUPPORTED_COLLATERAL`.                   |
| `wait`                                     | No vault funds it yet. `code` is `NO_ELIGIBLE_VAULT`, or `INSUFFICIENT_CAPACITY` with `unitsNeeded` and `unitsAvailable`: a listing is funded whole or not at all. |
| `simulation_failed`, `send_failed`         | Tried again at a later pass.                                                                                                                                       |
| `submitted`, `filled`                      | On its way, or done, with its `transaction` and `digest`.                                                                                                          |

`vaults` lists every vault of the factory at that reading, with `maxUnits`, the most it could take, and `refusal`, why it could take none. Nothing is signed or reserved by reading this: a borrower can cancel a waiting listing at any time.

## Valuation, suggested range, screening

The rates routes are served by a dedicated deployment of the same package. A browser may call them only from gage.cash. The scorecard routes answer gage's own servers only; any other request gets `401 UNAUTHORIZED`. Without a Rates API key, each address may make 30 requests a minute to the other rates routes; with one, the key's own ceiling of 600. Each address may make 600 a minute to the valuation routes. Over that, the service answers `429` with `Retry-After`.

The earlier engines' LP-backed loan origination is retired (loans against liquidity positions now go through their own lane: see [Borrow against LP positions](https://docs.gage.cash/borrow/lp-lane.md)). `/zap/pools` returns `enabled: false` with empty pools; `/quote/lp-zap` returns HTTP 410 (`LP_BORROWING_RETIRED`). Token borrowing and existing position valuation, repayment and claim APIs remain available.

| Endpoint                                                                                                               | Returns                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /rates/suggest?chainId=&engine=&token=\|poolId=&collateral=&term=&repayment=&shareBps=&maxRepaymentBps=&purpose=` | The suggested fixed cost for that exact collateral, quantity and term: `status: "preview"` with `costBps`, `repaymentRaw`, `collateralValueRaw`, `sizing` (`shareBps`, `maxRepaymentBps`, `curve`) and `expiresAt`; or `status: "unavailable"` with a `reason`. See [Suggested fixed costs](https://docs.gage.cash/start-here/ratings.md)                                                                                                    |
| `GET /intent/instant/:engine?token=&wallet=&term=&borrower=`                                                           | The largest loan the partner vaults fund whole on the keeper's next pass for a pledge of at most `wallet` raw tokens, at the model's suggested amount and cost. `:engine` is a generation's core; it signs and reserves nothing                                                                                                                                                                                                              |
| `GET /intent/preview/:engine?token=&collateral=&principal=&cap=&term=&borrower=`                                       | Before a loan is listed: what each partner vault could take of it, and whether the keeper funds it on its next pass                                                                                                                                                                                                                                                                                                                          |
| `GET /intent/capacity/:engine/:listing`                                                                                | For an open listing: the factory's vaults that hold what a new record carries, the largest first and at most 64 (`truncated` when one holding deposits was left out or part of the list is unread), with `maxUnits`, its `refusal` when it could take nothing, and `options`, one allocation per number of units it could be asked for, all from one block and one price. It signs nothing                                                   |
| `GET /intent/roll/quotes/:engine?loan=&borrower=&term=`                                                                | The signed funding plans of a roll of a running loan, for the holder of its reclaim right, at the lowest cost the vaults accept                                                                                                                                                                                                                                                                                                              |
| `GET /rates/snapshots`, `GET /rates/diagnostics`                                                                       | The model's scorecard, for gage's own servers only (`401 UNAUTHORIZED` otherwise): every native-engine listing, funding and close priced at its terms, and withheld quotes by market and reason                                                                                                                                                                                                                                              |
| `GET /positions/:tokenId/value`                                                                                        | An exact LP position's value                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `GET /quote/lp-zap`, `GET /zap/pools`                                                                                  | Retired: quote returns HTTP 410; discovery returns disabled with empty pools                                                                                                                                                                                                                                                                                                                                                                 |
| `GET /deals/:id/valuation`                                                                                             | `{ dealId, valueUSDG, priceUSDG, source: { kind: "pool"\|"two-hop", pools, asOfBlock }, scenarios: { now, atCap, atRangeTop, atRangeBottom, down20, down50, down80 }, position, suggestedCap, lane, at }`                                                                                                                                                                                                                                    |
| `GET /assets/:token/value`                                                                                             | `{ token, priceUSDG, priceRaw: { num, den }, source, at }`                                                                                                                                                                                                                                                                                                                                                                                   |
| `GET /range/suggest?pool=&term=`                                                                                       | `{ recommended: { tickLower, tickUpper, widthBps, note }, full, feeEstimateBps, basis }`                                                                                                                                                                                                                                                                                                                                                     |
| `GET /quote/reinvest?amount=&tickLower=&tickUpper=&route=match\|zap&payAsset=&slippageBps=`                            | match: `{ gageNeeded, payAmount, maxPay, minLiquidity }` · zap: `{ sgageToSell, maxSold, feeOnSold, minLiquidity }`                                                                                                                                                                                                                                                                                                                          |
| `GET /quote/entry?eth=`                                                                                                | `{ usdgOut, minUsdg, priceImpactBps, route }`                                                                                                                                                                                                                                                                                                                                                                                                |
| `GET /quote/payout?usdg=&to=ETH\|<token>&slippageBps=`                                                                 | `{ amountOut, minOut, rate, priceImpactBps, route }`                                                                                                                                                                                                                                                                                                                                                                                         |
| `GET /assets/:token/facts`                                                                                             | A listed token's facts: `allowed` and `lane` from the current core, market cap, 7-day median, pool, pair, age, the pool's virtual liquidity (`depthUSDG`, more than a sale can reach), locked, top ten, creator share, volume, drawdown, contract checks, `eligible` under the [published rules](https://docs.gage.cash/protocol/collateral-rules.md) for memes and utility coins, `listingNote`. A token not yet listed has no pool to read |
| `GET /health`                                                                                                          | `{ ok, chainId, block }`                                                                                                                                                                                                                                                                                                                                                                                                                     |

`priceUSDG` is a decimal string of USDG per one whole token. Prices are read from pools on the chain, never from a price feed, except for a display-only reference.

## Notifier

The notifier posts new loans on X and keeps each partner vault's profile, which is off chain: its description and the tokens its pages show first. It sends no reminders. No public URL is published. Local default `http://localhost:4200`.

| Endpoint               | Body / returns                                                                                                                                                              |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /vault-profiles`  | `{ chainId, profiles: [{ vault, description, order, signedAt }] }`: every saved partner-vault profile on the notifier's chain                                               |
| `POST /vault-profiles` | `{ chainId, vault, description, order, signedAt, signature }` → `{ profile }`, or `{ profile: null }` once an empty profile removed it: the vault's manager signs each save |
| `GET /health`          | `{ ok, chainId, loanPosts, vaultProfiles }`                                                                                                                                 |

## Addresses and ABIs

Contract addresses come from the public manifest `https://gage.cash/api/deployment`: the deployment file the services read, without its service URLs. Token-layer and Earn keys are absent until that layer is deployed on a chain, and every consumer works without them. A `nativeV2.assets` row's `minAmount`, `maxDealRaw` and `maxOpenRaw` are what the release recorded at its admission, on the engine of its day, and may not be the current core's limits: read those from the newest engine's registry (`getERC20Config` on `nativeV2.engines`' last `registry`) or from `gage.assets()`. ABIs are the Foundry build outputs for each contract and interface.

### Buybacks

`GET /stats` includes `buybacks: { gageThisWeek, gageAllTime }`, in raw 18-decimal GAGE units, or `null` when purchase receipts cannot be verified. This week uses the UTC calendar-week boundary. Totals combine actual creator-fee market purchases with `DealFeeRouter.FloorFunded.gageBought`. Initial seed purchases, donations and recycled floor fees are excluded. Existing emissions burn fields remain available for compatibility; the Protocol page leads with the GAGE bought back as a share of the GAGE supply.

### Fee streams

`fees.thisWeek`, `fees.allTime` and `fees.byWeek` are loan fees. `fees.streams` gives the fee streams the indexer counts, all time, in raw USDG: `creatorBuybacksUSDG` (creator fees spent on GAGE buybacks, the ETH valued at the snapshot's ETH/USDG spot), `loanUSDG` (deal and origination fees, a mirrored engine loan's fee counted once), `tradeUSDG` (sold reclaim rights and lender units), `cashoutUSDG` (the cash-out platform fee), `earnProtocolUSDG` (the protocol's share of the Gage-curated Earn strategies' fee), `partnerVaultsUSDG` (what partner vaults paid the protocol: the execution fees on their fills and purchases and the protocol's share of their performance fees, for every USDG generation, earlier withdraw-only ones included) and `lpLaneUSDG` (the LP lane's fees to the protocol: each loan's origination fee as the core charged it, a roll's included, and the protocol's share of each LP vault's performance fee on a loan repaid or rolled). The last two are `null` for a short while after the indexer starts, while it reads them. `fees.totalUSDG` is their sum, or `null` while a stream cannot be read. They leave out the fees of the generations that lend another asset than USDG.

### TVL

`tvlUSDG` is lending TVL (`tvlMethod: "custody-v4"`): what gage holds for its users, valued in USDG at indexed pool prices. A token no indexed pool prices takes the valuation service's price; one nothing prices is left out and counted in `tvlUnpricedItems`, and a borrower's repayment cap is never used as a price. Uncollected LP fees and virtual trading depth are not included. `tvlUSDG` is the sum of three `tvlBreakdown` lines:

* `collateralInDeals`: the collateral of every live loan, an LP position at its underlying principal.
* `usdgInOpenBids`: USDG waiting to fund a listing.
* `earnDeposits`: what the vaults hold for their depositors outside their loans. That is each Gage-curated Earn strategy's idle USDG and reserve position; each LP lane vault's free cash, set-aside bonus and unsold recovered tokens; and each partner vault's cash, repayments not yet booked, reserve position and unclaimed side pockets, in every generation, earlier withdraw-only ones and buy-only vaults included. `tvlBreakdown.lpLane` and `tvlBreakdown.partnerVaults` repeat the LP lane's and the partner vaults' parts.

Three figures sit beside TVL, never inside it: `borrowedUSDG` (the principal of every outstanding loan, also `tvlBreakdown.outstandingLoans`), `protocolLiquidityUSDG` (the principal of the protocol's own GAGE/sGAGE pool across every range, also `tvlBreakdown.gageSgagePool`) and `tvlBreakdown.withdrawableBalances` (credits users can withdraw). The loans a lend-asset generation funded are not in `/stats` yet. `tvlPoolBalances` returns the native pool's token quantities. The seven-day TVL comparison is unavailable until comparable balance snapshots exist.

### Vault deposits

`vaultDeposits` is what depositors hold in the vaults at their share prices: `{ assets: [...], unread }`, one row per lend asset with USDG's first, never added together across assets. Each row is `{ token, symbol, decimals, deposits, vaults, byKind }`:

* `deposits`: the vaults' total assets, raw. It includes the principal they have lent, so it is never part of TVL.
* `vaults`: every vault that takes deposits now, empty ones included, and every earlier vault while it has shares out.
* `byKind`: the same two figures for `partner` (partner vaults of every generation, buy-only ones included), `lp` (LP lane vaults), and `earn` and `hybrid` (the earlier Gage-curated Earn strategies).

A vault with no shares out counts nothing. `unread` counts the vaults that did not answer just now. `vaultDeposits` is `null` while the vaults cannot all be read.

## Earn strategies

Partner vaults have routes of their own (above). The indexer serves the Gage-curated third-design strategies (`EarnStrategy.version` 3, from the manifest's `earnV3`, closed to deposits and new loans since 15 October 2026) and the two delisted second-design strategies (version absent or 2) through the same routes and types; `shared/earn.d.ts` in the services is the canonical declaration. Read a strategy's address and its core, a zero-grace engine, from the manifest.

| Endpoint                                                        | Returns                                                                                                                                                            |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `GET /earn/strategies`                                          | Paginated strategy identities, mandate, categories, admitted ERC-20 tokens, balances, fees, share price and open side pockets.                                     |
| `GET /earn/:strategy`                                           | One strategy, same shape.                                                                                                                                          |
| `GET /earn/:strategy/accounts/:account`                         | Shares, value at the one price, what may be redeemed now, rewards and the account's side-pocket claims, including after all shares are redeemed.                   |
| `GET /earn/:strategy/loans`                                     | Paginated loans with collateral kind, category, quarter ownership, dates, state, carried value, outcome and all recovery pocket IDs.                               |
| `GET /earn/:strategy/pockets`                                   | Paginated recoveries in their actual currencies, independent of share value.                                                                                       |
| `GET /earn/:strategy/keeper`                                    | The keeper's health for the strategy and its limit-buy policy (`autofund`: on or off, the minimum Loan grade, the cap per listing).                                |
| `GET /earn/:strategy/events`                                    | Stable event IDs for once-only repayment, collateral, refund and overdue notices.                                                                                  |
| `GET /earn/:strategy/approvals`, `GET /earn/:strategy/requests` | Second design only: curator approvals and the withdrawal queue. Both pages are empty for a third-design strategy, which funds in one transaction and has no queue. |

Earn categories are `STOCK`, `MEME` and `LP`. Registry STOCK maps to Earn STOCK, registry MEME to Earn MEME, registry ETH tokens back no Earn loan, and eligible V3/V4 positions map to Earn LP. In the third design each category cap is independent, at most 10,000 basis points. The mandate carries `minDeposit` (one USDG), `maxTotalDeposits` (the one field the curator may move), `maxLoanTerm`, `minReturnBps` (0) and `maxGageExposureBps` (10,000), plus `assets`, the picks, empty for a category strategy; the cap per listing is keeper policy, not a mandate field. Every token row carries `allowed` and `ceiling` 0. `totals.instantLiquidity` equals `freeLiquidity`, the most one redemption pays at once: there is no queue, and the queue, unlock and high-water fields publish as zero. `totals.accruedInterest` is the net return the open loans have earned into the price so far; `grace` is 0 and every loan's `claimableAt` is its expiry.

Loan and approval `kind` is `"ERC20"`, `"UNIV3_POSITION"` or `"UNIV4_POSITION"`. On an ERC-20 loan, `token` and `collateralAmount` mean token address and raw quantity. On an LP loan, they mean position manager and NFT token ID. An NFT ID must never be formatted as a token balance or used to calculate a price ceiling.

A loan's `pocketIds` array lists every recovery. `pocketId` is the first entry or `null`, retained for compatibility. An LP default removes liquidity and collects fees into up to two pockets, one per nonzero recovered currency, owned by the same loss snapshot. Pocket `token` names the recovered currency; the zero address means native ETH. Optional `metadata` gives its `symbol`, `decimals` and `uiMultiplier`. Process every pocket independently and use the actual currency metadata, including ETH's 18 decimals.

Earn pages use `{ chainId, strategy, blockNumber, asOf, items, nextCursor }`. Pagination accepts `limit` up to 100 and an optional `blockNumber` to keep subsequent pages on the same snapshot; a changed snapshot returns `409 SNAPSHOT_CHANGED`. Absent deployment, unavailable reads and missing metadata must not be presented as zero balances.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.gage.cash/developers/api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
