Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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, the TypeScript SDK or the MCP server. 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

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)

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

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

Last updated

Was this helpful?