# Modules Overview All 14 SDK modules are accessed as properties on the `ThetanutsClient` instance — no separate instantiation needed. ## Module Table | Module | Client Property | Purpose | Requires Signer | | ------------- | ---------------------- | ------------------------------------------------------- | --------------- | | ERC20 | `client.erc20` | Token approvals, balances, transfers | Write ops only | | OptionBook | `client.optionBook` | Fill/cancel orders, fee claiming | Write ops only | | API | `client.api` | Fetch orders, positions, stats | No | | OptionFactory | `client.optionFactory` | RFQ lifecycle management | Write ops only | | Option | `client.option` | Position management and payouts | Write ops only | | Ranger | `client.ranger` | RangerOption (zone-bound, 4-strike) position management | Write ops only | | Events | `client.events` | Query blockchain events | No | | WebSocket | `client.ws` | Real-time subscriptions | No | | MM Pricing | `client.mmPricing` | Market maker pricing and Greeks | No | | RFQ Keys | `client.rfqKeys` | ECDH key management and offer encryption | No | | Utils | `client.utils` | Decimal conversions, payoff calculations | No | | Loan | `client.loan` | Non-liquidatable lending | Write ops only | | WheelVault | `client.wheelVault` | WheelVault (Ethereum mainnet) interactions | Write ops only | | StrategyVault | `client.strategyVault` | StrategyVault (Base) interactions | Write ops only | ## Module Descriptions ### `client.erc20` — ERC20Module Handles all ERC-20 token operations: reading balances and allowances, approving spenders, and transferring tokens. Provides `ensureAllowance()` to conditionally approve only when the existing allowance is insufficient. Relevant section: [OptionBook overview](/sdk/optionbook/overview.md) ### `client.optionBook` — OptionBookModule Fills and cancels orders on the OptionBook contract. Use `previewFillOrder()` for a dry-run before executing. Also handles referrer fee tracking and claiming across all collateral tokens. Relevant section: [OptionBook overview](/sdk/optionbook/overview.md) ### `client.api` — APIModule Fetches data from Thetanuts APIs. Methods are read-only and organized by source: `*FromIndexer` for the book indexer, `*FromRfq` for the RFQ/factory indexer. Covers orders, user positions, trade history, protocol stats, and daily time series. ### `client.optionFactory` — OptionFactoryModule Manages the full RFQ (Request for Quotation) lifecycle: building parameters, submitting requests, polling quotation state, revealing offers, and settling. Supports vanilla, spread, butterfly, condor, iron condor, and physically settled structures. Also exposes the RFQ-side referral surface (`registerReferral`, `getReferralOwner`, `getReferralFees`, `withdrawFees`) — see the [RFQ Referrals](/sdk/rfq-factory/referrals.md) guide. Relevant section: [RFQ overview](/sdk/rfq-factory/overview.md) ### `client.option` — OptionModule Queries and manages individual option positions. Reads option info, checks expiry/settlement state, calculates payouts at a given price, and executes close/transfer/split/payout operations. ### `client.ranger` — RangerModule Manages RangerOption positions — the r12 zone-bound, 4-strike payoff. The buyer earns the maximum payout when the settlement price lands inside the zone (between strikes 2 and 3) and a linearly decaying payout outside. Reads include `getInfo()`, `getZone()`, `getSpreadWidth()`, `getStrikes()`, `getTWAP()`, `calculatePayout(price)`, `simulatePayout(...)`, and `calculateRequiredCollateral(...)`. Writes include `payout()`, `close()`, `split(amount)`, `transfer(isBuyer, target)`, `reclaimCollateral(ownedOption)`, and `returnExcessCollateral()`. The module throws `NETWORK_UNSUPPORTED` on chains where RangerOption is not deployed (e.g., Ethereum mainnet today) — no silent eth\_call failures. ### `client.events` — EventsModule Queries on-chain events from the Thetanuts contracts: order fills, cancellations, RFQ requests, MM offers, offer reveals, settlements, and position closes. Block ranges are auto-chunked into 10K-block segments. ### `client.ws` — WebSocketModule Provides real-time subscriptions over WebSocket for order updates, price feeds, and connection state changes. Includes automatic reconnection. ### `client.mmPricing` — MMPricingModule Fetches market maker pricing from the pricing API. Returns fee-adjusted bid/ask prices per collateral token with collateral cost included. Includes filter and sort helpers and multi-leg pricing for spreads, butterflies, and condors. Relevant section: [MM Pricing guide](/sdk/pricing/mm-pricing.md) ### `client.rfqKeys` — RFQKeyManagerModule Manages ECDH key pairs used in the sealed-bid auction RFQ flow. Generates, stores, loads, and backs up keys. Provides `encryptOffer()` for market makers and `decryptOffer()` for requesters. Relevant section: [RFQ overview](/sdk/rfq-factory/overview.md) ### `client.utils` — UtilsModule Pure utility functions with no network calls: decimal conversions (`toBigInt`, `fromBigInt`, `strikeToChain`, `strikeFromChain`, `toUsdcDecimals`, `fromUsdcDecimals`), payout calculations, collateral calculations, and payoff diagram data generation. Relevant section: [Utilities](/sdk/sdk-reference/utilities.md) ### `client.loan` — LoanModule Non-liquidatable lending. Borrowers deposit ETH/BTC collateral and receive USDC. At expiry, repay to reclaim collateral or walk away. Includes pricing, cost calculation, lending opportunities, and option exercise. Relevant section: [Loan overview](/sdk/loan/overview.md) ### `client.wheelVault` — WheelVaultModule Reads and interacts with the WheelVault contracts on Ethereum mainnet. The module is chain-gated — methods throw `NETWORK_UNSUPPORTED` when the client is configured for any chain other than `chainId 1`. Relevant section: [Wheel Vault overview](/sdk/wheel-vault-ethereum/overview.md) ### `client.strategyVault` — StrategyVaultModule Reads and interacts with the StrategyVault contracts (fixed-strike and CLVEX strategies) on Base. The module is chain-gated — methods throw `NETWORK_UNSUPPORTED` when the client is configured for any chain other than `chainId 8453`. Relevant section: [Strategy Vault overview](/sdk/strategy-vault-base/overview.md) ## Quick Reference ```typescript import { ThetanutsClient } from '@thetanuts-finance/thetanuts-client'; const client = new ThetanutsClient({ chainId: 8453, provider, signer }); // ERC20 const balance = await client.erc20.getBalance(tokenAddress, userAddress); await client.erc20.ensureAllowance(token, spender, amount); // OptionBook const preview = client.optionBook.previewFillOrder(order, 10_000000n); const receipt = await client.optionBook.fillOrder(order, 10_000000n); // API const orders = await client.api.fetchOrders(); const positions = await client.api.getUserPositionsFromIndexer(address); // OptionFactory const request = client.optionFactory.buildRFQRequest({ /* params */ }); await client.optionFactory.requestForQuotation(request); // Option const info = await client.option.getFullOptionInfo(optionAddress); // Ranger (RangerOption — zone-bound, 4-strike) const rangerInfo = await client.ranger.getInfo(rangerAddress); const { zoneLower, zoneUpper } = await client.ranger.getZone(rangerAddress); // Events const fills = await client.events.getOrderFillEvents(); // WebSocket await client.ws.connect(); client.ws.subscribeOrders((update) => console.log(update)); // MM Pricing const all = await client.mmPricing.getAllPricing('ETH'); const active = client.mmPricing.filterExpired(Object.values(all)); // RFQ Keys const keyPair = await client.rfqKeys.getOrCreateKeyPair(); // Utils const onChain = client.utils.strikeToChain(1850); // 185000000000n const human = client.utils.fromBigInt(100500000n, 6); // '100.5' // Loan const strikes = await client.loan.getStrikeOptions('ETH'); const calc = client.loan.calculateLoan({ depositAmount: '1.0', underlying: 'ETH', strike: 1600, expiryTimestamp: 1780041600, askPrice: 0.007, underlyingPrice: 2328 }); ``` *** ## See Also * [Client](/sdk/sdk-reference/client.md) — ThetanutsClient constructor and properties * [Utilities](/sdk/sdk-reference/utilities.md) — UtilsModule method reference * [../getting-started/configuration.md](/sdk/getting-started/configuration.md) — Getting started with configuration --- # Agent Instructions: 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: ``` GET https://docs.thetanuts.finance/sdk/sdk-reference/modules-overview.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.