Build on Thetanuts V4

Options on EVM chains. Market makers quote on RFQ and OptionBook. Uniswap pools run the AMM. Grids on CoW Protocol replicate options on any pair.

Find your task below. Each one gives the contract, the endpoint and the rules that apply.

How the V4 products fit together Three groups. Market makers quote on RFQ and OptionBook. Uniswap pools run Theta AMM: swaps hedge the Wheel vaults, and Markets sells the long side. Grids on CoW Protocol replicate options: ThetaCow sells gamma on any pair, and Cattle runs long or short grids on Aave collateral. Assets start on pools and grids and move to market makers as demand grows. Market makers quote RFQ Sealed auction for custom and block size OptionBook Signed orders, filled on-chain at once Assets move up as demand grows Uniswap pools quote (Theta AMM) Uniswap V3 Swaps from aggregators Wheel vaults Sellers, as LP Markets Buyers take the long side Grids replicate options (CoW Protocol) ThetaCow Sell gamma on any token pair. No oracle. Cattle Long or short grids on Aave collateral. Delta-hedge on-chain.

Tasks

Start with the SDK for OptionBook and RFQ. Start with the Gyro reference app for Theta AMM.

Show live options and prices

Live

OptionBook on Base. Read only; no wallet needed.

npm install @thetanuts-finance/thetanuts-client ethers

// read only
const client = new ThetanutsClient({ chainId: 8453, provider });
const orders = await client.api.fetchOrders();

Without the SDK, GET https://round-snowflake-9c31.devops-118.workers.dev/ returns the same signed orders. Each order has order, signature, optionBookAddress and greeks.

Units. price and strikes are USD with 8 decimals: 212263159 is $2.12. maxCollateralUsable uses the collateral token's decimals (USDC has 6).
Whitelist. The contract accepts any signed order. Before you show one, check its implementation, collateral and priceFeed against the known set. Hide unknown orders.

SDK docs · Order feed reference

Fill an order from your app

Live

OptionBook r12 on Base: 0x1bDff855d6811728acaDC00989e79143a2bdfDed

  1. Approve the collateral token (USDC) to the OptionBook.
  2. Preview the fill, then send it. You choose the number of contracts, so partial fills work.
  3. Pass your referrer address to record fills you route.
await client.erc20.ensureAllowance(USDC, client.chainConfig.contracts.optionBook, amount);
const receipt = await client.optionBook.fillOrder(order, amount);

// the contract call underneath
fillOrder(Order order, bytes signature, address referrer) returns (address option)
One book per order. Makers sign each order for one OptionBook address. A fill sent to another release reverts. Use the optionBookAddress in the order.

Referral fee splits are set per referrer by Thetanuts. Ask us to set yours.

SDK source · Full fill workflow

React to a fill

Contract events and callbacks

OrderFilled is the OptionBook log for presigned maker-order fills. Decode it with the ABI for the order's OptionBook deployment.

For on-chain integrations, the option calls buyer and seller contracts through handleOptionEvent(address optionAddress, bool isBuyer, uint8 eventType, bytes data). Creation uses event type 0; trade settled uses 6. OptionBook triggers creation after the fill and trade settlement for direct fills. For factory-mediated fills, the factory triggers trade settlement after role transfers.

Notifications, not vetoes. Callbacks are gas-bounded and non-blocking. Authenticate the calling option, keep work bounded, and make repeated notifications safe. Match the implementation and release; these callbacks target participating contracts, not arbitrary subscribers.

For HTTP delivery, use an external webhook service such as Alchemy, or your own event listener. That integration defines the payload, signing, retries, deduplication, confirmations and reorg handling. Contract callbacks are not HTTP webhooks.

Request a custom option

Live

RFQ OptionFactory r12 on Base: 0x8118daD971dEbffB49B9280047659174128A8B94

Use RFQ when the strike, expiry or size you need is not on the book. Market makers send sealed offers. The best revealed offer wins. The option is created when the auction settles.

const pricing = await client.mmPricing.getAllPricing('ETH');  // indicative quotes
const rfq = client.optionFactory.buildRFQRequest({ ... });
await client.optionFactory.requestForQuotation(rfq);
Size cap. An RFQ has a maximum value, $1M by default.

RFQ workflow in the SDK docs

Show a user's positions

Live

Current V4 SDK history on Base.

The current indexer covers RFQs, executed trades and option positions. OptionBook means presigned maker orders; the order feed and indexed execution history serve different purposes.

GET https://indexer.thetanuts.finance/api/v1/book/stats
GET https://indexer.thetanuts.finance/api/v1/factory/stats

Use /api/v1/book for book execution history and /api/v1/factory for RFQ history. Follow the current SDK guide for list paths and response shapes. Check contract scope, block coverage and update time before treating a record as current.

Older OptionBook service

Existing apps also use the separate service below. Its paths and schema are not interchangeable with the current SDK indexer.

GET https://optionbook-indexer.thetanuts.finance/api/v1/user/{address}/{type}
GET https://optionbook-indexer.thetanuts.finance/api/v1/open-positions
GET https://optionbook-indexer.thetanuts.finance/api/v1/option-events/{optionAddress}
GET https://optionbook-indexer.thetanuts.finance/api/v1/stats

Current SDK guide · Older OptionBook API reference · Fill notifications

Handle expiry and exercise

Live

Every option is its own contract, created at fill.

  • Cash-settled (the default): settles from a 30-minute Chainlink TWAP at expiry. No user action.
  • Physically settled (RFQ only): the buyer can exercise from expiry until the seller calls withdraw(). The seller cannot withdraw an in-the-money option for the first hour.
Exercise rule. The expiry TWAP decides whether an option can be exercised, not the current price.

Show vault positions and history

Live

Theta AMM on Ethereum (1), Base (8453) and HyperEVM (999). Registered vaults only.

GET https://amm.thetanuts.finance/api/position?chainId=8453&address=0x…&vault=0x…
GET https://amm.thetanuts.finance/api/lending?chainId=8453&vault=0x…
GET https://amm.thetanuts.finance/api/iv-history?chainId=8453&vault=0x…
GET https://amm.thetanuts.finance/api/status
Missing is not zero. Values are integer strings in each token's own decimals. A stale or unproven record returns a 503 with no number. Show it as unavailable.
Origins. A new browser origin must be registered before it can call this API. Server-side GETs work without registration.

Service reference · Read-only example

Deposit, withdraw or buy on a vault

Live

Theta AMM. Sellers deposit into Wheel vaults. Buyers take the long side in Markets.

  1. Copy the adapters from the Gyro reference app. They hold the tested call shapes for every chain.
  2. Static-call each write before you send it, and show the simulated amount.
  3. Check the Market's paused() state before you offer a buy.
Do not hand-build calldata. Vault generations change argument lists and record sizes. Pin the generation and the Markets release you tested against.
Buyer price. Sellers set an IV. The buyer pays the full executable price, so the buy IV can be higher than the listed IV. Show the buyer the price you simulated.

Launch your own site

LiveRegistration needed

A subDAO: your brand and design on existing Theta AMM markets.

  1. Get the approved frontend release from Thetanuts. Start from Gyro.
  2. Give the fork its own name, design, configuration and RPC credentials.
  3. Select the approved chains, vaults, Markets and lens. Pin the generation.
  4. Ask us to register your site ID and browser origins for the shared API.
  5. Set INDEX_API = 'https://amm.thetanuts.finance/api' after registration.
  6. Run the release checks in the fork guide, then ask for a launch review.
New markets. You can bundle existing markets. New markets, assets and chains need Thetanuts approval. Thetanuts deploys and seeds them, because managed seeding protects against sizing attacks.

Fork guide · Fees and incentives (proposal) · llms.txt for coding agents

Sell gamma on any token pair

Deposits not open

ThetaCow. Contracts deployed on Ethereum, Base, Arbitrum, BNB Chain, Polygon and Avalanche.

A pair owner picks two tokens, a strike and an IV. The pair turns a Black-Scholes delta curve into CoW Protocol limit orders. It sells the base asset as price rises and buys it back as price falls. That is a short-gamma position, paid by the grid spread.

  • No oracle. Price comes from the pair's own inventory, so it works for tokens with no price feed.
  • The owner keeps the funds in their own pair, not a pooled vault.
  • At expiry the pair holds the inventory its grid reached.
Token review. The contracts accept any token. The official app lists reviewed tokens only; do the same in yours.

ThetaCow docs

Draw charts and oracle prices

Live

One cached feed. Sources: OKX, Alpaca, Coinbase, Kraken, then Binance.

GET https://odette.fi/api/feed/klines?symbol=BTCUSDT&interval=5m&limit=100
GET https://odette.fi/api/feed/oracle?asset=BTC      // Chainlink, 1e8 = $1.00
WS  wss://odette.fi/api/feed/stream?symbol=BTCUSDT

Macro events for the next 7 days: GET https://calendar.thetanuts.finance/v1/events.json

Things that need a conversation

Contact Thetanuts
You want toStatus
Register a site ID or browser origin for the shared AMM APIOn request
Set a referral fee split for fills you routeOn request
Quote as a market maker on OptionBook or RFQOn request
Route aggregator swaps through the AMM Uniswap V3 poolsLooking for partners
Launch a new market, asset or chain on Theta AMMBy approval
Charge partner fees or share revenue on AMM MarketsUnder review
Deposit and withdraw from any chain in an embedded walletIn testing
Swap directly against the AMM marketsPlanned
Sell gamma on any token pair with ThetaCowDeposits not open

Products compared

RFQ and OptionBook create the same option contracts. Theta AMM and ThetaCow get their liquidity from pools instead of market makers.

RFQOptionBookTheta AMMThetaCow
How a trade happensRequester asks; market makers send sealed offers; best reveal winsMarket maker signs an order; taker fills it on-chainSellers deposit into Uniswap V3 LP vaults; buyers fill in MarketsA pair owner's grid posts CoW limit orders; solvers fill
Who sets the priceMarket makersMarket makersPool fees, plus the IV each seller lists in MarketsBlack-Scholes inventory curve; no oracle
Best forCustom strikes, expiries and block sizeListed strikes, instant fillsTokens with no market-maker network yetShort gamma on any token pair
SettlementCash (TWAP) or physicalCash (TWAP)Weekly epochs, Friday 20:00 UTCInventory at expiry
ChainsBaseBaseEthereum, Base, HyperEVM6 chains; deposits not open
StatusLiveLiveLiveDeposits not open
Start withSDKSDK, OdetteBuilder hub, GyroThetaCow docs

Design rules you will meet

Each rule is a design choice we made on purpose. The second line says why.

Contracts never upgrade

A new release gets new addresses. Pin addresses per release and move when we announce a new one.

No admin key can change a deployed contract. That removes upgrade and key-theft risk for user funds.

Every option is fully collateralised

The seller locks the maximum payout at creation. There is no margin, no liquidation and no margin call.

Less capital efficient, but no liquidation cascades and no dependence on a live oracle for solvency.

USD has 8 decimals

Prices and strikes use 1e8 = $1.00. Token amounts use each token's own decimals: USDC 6, WETH 18.

It matches Chainlink price feeds directly, on every chain.

Contracts are permissionless; frontends filter

The contracts accept any valid signed order. Your app must whitelist implementations, collateral and price feeds.

Checks live in market-maker bots and frontends, so the contracts stay simple and cheap.

Two market-maker venues

RFQ for custom and block trades. OptionBook for listed strikes and instant fills.

A sealed auction hides large trades. A signed book is faster for retail size.

Splitting a position costs more each time

Each split generation doubles the fee. The counterparty receives the fee.

It prevents dust attacks without a minimum size that would trap small positions.

The AMM runs on Uniswap V3

Wheel vaults are Uniswap V3 LP positions that behave like short options. Markets sells the long side to buyers.

Aggregators already route swaps to Uniswap, and the LP hedges delta as swaps arrive. That gives a token a continuous option market before any market maker quotes it.

Assets start on pools and move to market makers

A new asset needs only a pool, a strike and a keeper. As demand grows, it moves to RFQ and OptionBook.

The AMM is the bootstrap. The market-maker venues are for scale.

Addresses and endpoints

Check the release before you copy. Theta AMM vault and Market addresses change per market; read them from the Gyro reference config.

WhatChainAddress or URL
OptionBook r12Base0x1bDff855d6811728acaDC00989e79143a2bdfDed
OptionFactory (RFQ) r12Base0x8118daD971dEbffB49B9280047659174128A8B94
USDCBase0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
Theta AMM RouterEthereum, Base, HyperEVM0x9949D7079d13FfEEf6e2310bC1Ba6Ee4411BE175
Theta AMM LensEthereum, Base, HyperEVM0xD8ab30720dacEE5bcd66bDf66510B33dBc03f490
Theta AMM factoryEthereum, Base, HyperEVM0x42c059Bf54553957ca4b8BeA67fcf43424C03A92
Markets factoryEthereum0x61C8FA9ef4711680369351bBa4bf90b2Ea4C89aD
Markets factoryBase, HyperEVM0x8D4f862A64b1E2B4E66B7Ff384394857f4D8bA88
SDKBasenpm @thetanuts-finance/thetanuts-client
Order feedBasehttps://round-snowflake-9c31.devops-118.workers.dev/
Current V4 indexerBasehttps://indexer.thetanuts.finance/api/v1/book · /api/v1/factory
Older OptionBook indexerBasehttps://optionbook-indexer.thetanuts.finance/api/v1
Theta AMM APIEthereum, Base, HyperEVMhttps://amm.thetanuts.finance/api
Market data feed–https://odette.fi/api/feed/