> 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 app reads from three services. Every shape below is the integration contract those services implement. Anyone can run them against the chain. ## 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 } 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. `graceEnd = expiry + GRACE`. `costBps = (cap − price) × 10000 ÷ price`. ## Indexer Default `http://localhost:42069`. 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[] }` | | `GET /assets/:token/deals` | Recent funded deals on the asset, for the indicative cost | | `GET /epochs` | `{ epochs: Epoch[] }` | | `GET /stats` | Dashboard aggregates: TVL, fees, active deals, states, medians, emissions, sGAGE price history | | `GET /health/indexer` | `{ ok, chainId, latestBlock, indexedBlock, lagBlocks }` | ## Valuation, suggested range, screening Default `http://localhost:4100`. | Endpoint | Returns | | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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\|&slippageBps=` | `{ amountOut, minOut, rate, priceImpactBps, route }` | | `GET /assets/:token/facts` | Meme facts: market cap, 7-day median, pool, pair, age, depth, locked, top ten, creator share, volume, drawdown, contract checks, `eligible`, `listingNote` | | `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 Default `http://localhost:4200`. | Endpoint | Body / returns | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `POST /notify` | `{ wallet, channel: "email"\|"telegram"\|"push", address, prefs: { t48, t24, t6, t1, expiry, budget, epoch }, signature, message }` → `{ ok }` | | `GET /notify/:wallet` | `{ subscriptions: [{ channel, address, prefs, createdAt }] }` | | `DELETE /notify/:wallet/:channel` | Same signature scheme → `{ ok }` | | `GET /health` | `{ ok, pending, sentLastHour }` | `message` is the EIP-191 text `gage notify
` signed by the wallet. ## Addresses and ABIs Contract addresses come from `contracts/deployments/.json` in the repository. Token-layer keys are absent until that layer is deployed on a chain, and every consumer works without them. ABIs are the Foundry build outputs for each contract and interface. --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.gage.cash/developers/api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.