# Theta AMM service reference

API base: `https://amm.thetanuts.finance/api`.
The gateway uses the existing indexer and data, not a separate copy per fork.
New browser origins and shared card/referral sites need registration.

| Method and path | Inputs and result |
| --- | --- |
| GET `/position` | Explicit `chainId`, wallet `address`, `vault`; preserve adapter-supplied `seriesId` and `benchmarkStrike`. Entry history and coverage for return calculations. |
| GET `/lending` | Explicit `chainId`, `vault`. Tracked Aave interest per series and its source time. |
| GET `/iv-history` | Exactly one explicit `chainId` and `vault`. Initial IV and recorded changes. |
| GET `/referral/resolve` | `code`, depositor `address`. Cookie-free referral resolution, including self-referral refusal. |
| GET `/referral/leaderboard` | Shared cross-chain first-deposit ranking. Not a per-fork trading competition or payout ledger. |
| POST `/share?chainId=…` | JSON `{address, vault, seriesId, dapp}`. The service derives the figures; no wallet signature. Writes a public card. |
| GET `/status` | Per-chain progress and lending status. `lastRun.confirmations` is the reorg margin: 30 blocks, or 600 on Robinhood Chain (4663). `operatorCounters` counts RPC results per operator for the last run only. |

Share and image links use `/s/:id?chainId=…` and `/og/:id.png?chainId=…` on
`https://amm.thetanuts.finance`, outside `/api`. Keep their chain query intact.
New referral links use `/r/:walletOrCode?site=…&chainId=…&asset=…&strike=…`.
The server owns the destination; a caller cannot choose an arbitrary redirect.

GET on a referral or share page can record a visit. Use HEAD on those pages for
write-free checks. Ordinary API read routes use GET, not HEAD. Legacy signed-link
endpoints are not exposed here. Operator job routes need a server-side token; they
are not public reads.

## Consumer rules

Robinhood browser reads can use the separate [read-only RPC](rpc.md) at `/rpc/4663`. This is not an indexer endpoint or a wallet transaction RPC.

- Use each site's existing tested adapters as the behavioral reference. Preserve
  chain, vault, series, wallet and API identity across every asynchronous request.
- Reject wrong-identity or refused data. Cancel or discard results after a context change.
- Values are integer atom strings. Use each token's own decimals.
- Position history is not a replacement for the current withdrawal simulation.
- A lending record's `sealedAsOf` is its own Unix source time, not fetch time.
  A 200 response with `completeAsOf:true` can still have `caughtUp:false`.
  Stale or unproven records return a typed, numberless 503. Do not substitute zero.
- Do not automatically retry an uncertain share POST. Storage may have succeeded.
- Use GETs or the [read-only example](examples/read-lending.mjs) to test access.
  Do not call admin or payout operations as health checks.

## What this service does not grant

No market issuance, seed funding, automatic fee split, reward entitlement or
profit guarantee. Referral records are attribution inputs, not a claim on a
treasury. The current leaderboard does not measure wrapper fees or pay rewards.
New wrappers and campaigns need their own verified records and settlement rules.
