@thetanuts-finance/thetanuts-client

TypeScript client for trading options on Base mainnet via Thetanuts Finance V4 — listed orderbook fills, custom-built RFQs, and real-time price/order streams over WebSocket. Works in Node 18+ and modern browsers, ships as ESM and CJS with full type definitions.

Full documentation: docs.thetanuts.finance/sdk

Contents

• 30-second start
• Two paths: read market data, or trade
• Choosing between OptionBook and RFQ
• Modules
• Common workflows
• Error handling
• Production checklist
• Reference
• Development
• Documentation & links

30-second start

Install:

npm install @thetanuts-finance/thetanuts-client ethers

Instantiate a read-only client and prove it works:

import { ethers } from 'ethers';
import { ThetanutsClient } from '@thetanuts-finance/thetanuts-client';

const provider = new ethers.JsonRpcProvider('https://mainnet.base.org');
const client = new ThetanutsClient({
  chainId: 8453, // Base mainnet
  provider,
});

const orders = await client.api.fetchOrders();
console.log(`Found ${orders.length} live orders on the book`);

const market = await client.api.getMarketData();
console.log(`ETH: $${market.prices.ETH}  BTC: $${market.prices.BTC}`);

No signer, no approvals, no transactions — just network reads. If that prints, your setup is good.

Two paths: read market data, or trade

Path A — I just want to read market data

You don't need a signer. The client above can already:

• Browse the OptionBook (client.api.fetchOrders)
• Fetch MM pricing for RFQ-style options (client.mmPricing.getAllPricing)
• Pull positions, stats, and historical data from the indexer (client.api.*)
• Subscribe to live orders, prices, and trades (client.ws.*)

Quick examples:

// All active ETH option quotes the MM is showing
const pricing = await client.mmPricing.getAllPricing('ETH');
const active = client.mmPricing.filterExpired(Object.values(pricing));
console.log(`${active.length} active ETH options`);

// Real-time price stream
await client.ws.connect();
client.ws.subscribePrices((update) => {
  console.log(`${update.underlying}: $${update.price}`);
}, 'ETH');

Path B — I want to trade

You need three things in order:

1. A signer — anything ethers.Signer-shaped (private key wallet, Coinbase Smart Wallet, Safe, etc.).
2. Token approvals — USDC, WETH, or cbBTC must be approved to the OptionBook or OptionFactory contract before you fill or RFQ.
3. The right module — client.optionBook for filling existing orders, client.optionFactory for creating custom RFQs.

import { ethers } from 'ethers';
import { ThetanutsClient } from '@thetanuts-finance/thetanuts-client';

const provider = new ethers.JsonRpcProvider('https://mainnet.base.org');
const signer = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);

const client = new ThetanutsClient({
  chainId: 8453,
  provider,
  signer,
  // Optional: earn a share of fees on every fill you route
  referrer: '0x92b8ac05b63472d1D84b32bDFBBf3e1887331567',
});

// Approve USDC to OptionBook before filling
await client.erc20.ensureAllowance(
  client.chainConfig.tokens.USDC.address,
  client.chainConfig.contracts.optionBook,
  10_000000n, // 10 USDC (6 decimals)
);

// Fill an order — see Common workflows for the full flow
const orders = await client.api.fetchOrders();
const receipt = await client.optionBook.fillOrder(orders[0], 10_000000n);
console.log(`Filled: ${receipt.hash}`);

Jump to Common workflows for end-to-end fills, RFQs, multi-leg structures, and position management.

Choosing between OptionBook and RFQ

Both systems use the same cash-settled implementation contracts and produce identical option positions. The difference is how you get a quote and who provides liquidity.

| | OptionBook | RFQ (Factory) | | -------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | What | Fill existing market-maker orders from a public book | Request a custom option, market makers submit sealed-bid offers | | Best for | Quick trades on listed strikes/expiries | Custom strikes, custom expiries, off-the-run structures | | Structures | Vanilla, spread, butterfly, condor, iron condor (cash) | Same, plus optional physically-settled vanilla | | Settlement | Cash-settled (payout in collateral token at expiry) | Cash-settled by default; physical opt-in via buildPhysicalOptionRFQ() (vanilla only) | | Key methods | fetchOrders(), previewFillOrder(), fillOrder() | buildRFQRequest(), requestForQuotation(), settleQuotationEarly() | | Pricing source | Per-order from fetchOrders() | MM continuous quotes from client.mmPricing.getAllPricing() | | Collateral | Taker pays premium upfront | collateralAmount = 0 at creation; pulled at settlement (SELL needs prior approval) | | Data | Book indexer (/api/v1/book/) | Factory indexer (/api/v1/factory/) | | User reads | getUserPositionsFromIndexer() | getUserRfqs(), getUserOptionsFromRfq() | | Stats | getBookProtocolStats(), getBookDailyStats() | getFactoryProtocolStats(), getFactoryDailyStats() |

Rule of thumb: if the order you want already exists on the book, fill it. If not, RFQ it.

Modules

The client exposes 15 modules. Pull what you need; the rest stay idle.

| Module | Purpose | Needs signer | | ----------------------- | ---------------------------------------------------- | --------------- | | client.api | Indexer reads: orders, positions, stats, market data | No | | client.optionBook | Fill / preview / cancel orders, fees | Write ops only | | client.optionFactory | RFQ lifecycle (create, offer, settle) | Write ops only | | client.option | Position management and payouts | Write ops only | | client.ranger | RangerOption (zone-bound, 4-strike) positions | Write ops only | | client.mmPricing | Continuous MM pricing, Greeks, fee adjustments | No | | client.rfqKeys | ECDH keypairs for encrypted RFQ offers | No | | client.erc20 | Token approvals, balances, transfers | Write ops only | | client.events | On-chain event queries | No | | client.ws | Real-time order, price, and trade subscriptions | No | | client.utils | Decimal conversions, payoff math | No | | client.loan | Non-liquidatable lending (borrow vs ETH/BTC) | Write ops only | | client.collar | Zero-interest collar loans (capped upside, preview) | Write ops only | | client.wheelVault | WheelVault interactions | Write ops only | | client.strategyVault | StrategyVault interactions | Write ops only |

Note: the pricing module is client.mmPricing, not client.pricing.

See src/modules/README.md for per-module reference.

Common workflows

OptionBook flows

Browse and fill an order

import { ethers } from 'ethers';
import { ThetanutsClient } from '@thetanuts-finance/thetanuts-client';

const provider = new ethers.JsonRpcProvider('https://mainnet.base.org');
const signer = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);

const client = new ThetanutsClient({
  chainId: 8453,
  provider,
  signer,
  referrer: '0x92b8ac05b63472d1D84b32bDFBBf3e1887331567',
});

// 1. Browse the book
const orders = await client.api.fetchOrders();
const order = orders.find(
  (o) => o.order.expiry > BigInt(Math.floor(Date.now() / 1000)),
);
if (!order) throw new Error('No active orders');

// 2. Preview the fill — no transaction, no signer call
//    For PUTs and multi-leg structures, contract count != premium.
//    previewFillOrder runs the same collateral math the contract uses.
const preview = client.optionBook.previewFillOrder(order, 10_000000n); // 10 USDC
console.log(`Buying ${preview.numContracts} contracts at ${preview.pricePerContract}`);
console.log(`Collateral token: ${preview.collateralToken}`);

// 3. Approve collateral
const usdc = client.chainConfig.tokens.USDC.address;
await client.erc20.ensureAllowance(
  usdc,
  client.chainConfig.contracts.optionBook,
  10_000000n,
);

// 4. Fill
const receipt = await client.optionBook.fillOrder(order, 10_000000n);
console.log(`Filled: ${receipt.hash}`);

Understand collateral vs contracts (PUT footgun)

availableAmount on an order is the maker's collateral budget, not contract count. The actual fillable contracts depend on option type:

| Type | Strikes | Formula | Worked example | | --------------- | ------- | ---------------------------------------- | ----------------------------------------- | | Vanilla PUT | 1 | (collateral × 1e8) / strike | 10,000 USDC @ $95k strike = 0.105 contracts | | Inverse CALL | 1 | collateral / 1e12 | 1 WETH = 1 contract | | Spread | 2 | (collateral × 1e8) / spreadWidth | 10,000 USDC / $10k spread = 1 contract | | Butterfly | 3 | (collateral × 1e8) / maxSpread | Based on widest strike range | | Condor | 4 | (collateral × 1e8) / maxSpread | Based on widest strike range |

Always call previewFillOrder() before fillOrder() — it returns the exact contract count, collateral token, and price-per-contract the contract will use.

Referrer fees

Set a referrer to earn a share of fees on every fill you route. Fees accrue per collateral token and can be claimed in bulk.

// Set globally on the client
const client = new ThetanutsClient({
  chainId: 8453, provider, signer,
  referrer: '0x92b8ac05b63472d1D84b32bDFBBf3e1887331567',
});

// Or override per-call
await client.optionBook.fillOrder(order, undefined, '0xYourReferrerAddress');

// Or build the calldata for viem/wagmi/AA wallets
const { to, data } = client.optionBook.encodeFillOrder(
  order, 10_000000n, '0x92b8ac05b63472d1D84b32bDFBBf3e1887331567',
);

// Check what's claimable across every collateral token
const claimable = await client.optionBook.getAllClaimableFees('0xYourAddress');
for (const fee of claimable) {
  console.log(`${fee.symbol}: ${ethers.formatUnits(fee.amount, fee.decimals)}`);
}

// Claim every non-zero balance in one call
const results = await client.optionBook.claimAllFees();
for (const r of results) {
  if (r.receipt) console.log(`Claimed ${r.symbol}: ${r.receipt.hash}`);
}

If no referrer is set, the zero address is used (no fee sharing).

RFQ flows

RFQs are sealed-bid: you broadcast a request, market makers submit encrypted offers, and you reveal/settle the best one. The SDK handles ECDH encryption automatically.

Vanilla RFQ (cash-settled)

const client = new ThetanutsClient({ chainId: 8453, provider, signer });
const userAddress = await signer.getAddress();

// 1. Get (or create) your ECDH keypair — used to receive encrypted MM offers
const keyPair = await client.rfqKeys.getOrCreateKeyPair();

// 2. Build the request. buildRFQRequest enforces collateralAmount = 0.
const rfqRequest = client.optionFactory.buildRFQRequest({
  requester: userAddress,
  underlying: 'ETH',           // 'ETH' | 'BTC'
  optionType: 'PUT',           // 'CALL' | 'PUT'
  strike: 2000,                // Human-readable USD strike
  expiry: Math.floor(Date.now() / 1000) + 86400 * 7, // 7 days out
  numContracts: 1.5,           // Human-readable
  isLong: true,                // true = BUY, false = SELL
  offerDeadlineMinutes: 60,
  collateralToken: 'USDC',
  reservePrice: 0.015,         // BUY: max price per contract you'd accept
  requesterPublicKey: keyPair.compressedPublicKey,
});

// 3. Submit
const receipt = await client.optionFactory.requestForQuotation(rfqRequest);
console.log(`RFQ created: ${receipt.hash}`);

// SELL side only: approve collateral to the OptionFactory BEFORE submitting.
// For a PUT, the collateral is strike * contracts (in USDC):
//   const approval = BigInt(Math.round(2000 * 1.5 * 1e6));
//   await client.erc20.approve(USDC, client.optionFactory.contractAddress, approval);

See the RFQ workflow guide for the full lifecycle: MM offers, the reveal phase, and final settlement.

Multi-leg RFQs (spread, butterfly, condor)

Pass an array of strikes instead of a single strike. The generic SDK builder selects the implementation from option type plus strike count; MCP callers must pass the explicit product that matches the strike count (*_SPREAD = 2, *_FLY = 3, *_CONDOR / IRON_CONDOR = 4).

MCP prepare_request_rfq validates the product/strike shape before calldata is built: PUT/CALL require 1 strike, *_SPREAD require 2, *_FLY require 3, and *_CONDOR/IRON_CONDOR require 4. BUY RFQs also require a positive per-contract reservePrice; use prepare_suggest_reserve_price instead of guessing.

const keyPair = await client.rfqKeys.getOrCreateKeyPair();
const expiry = Math.floor(Date.now() / 1000) + 86400 * 7;

// Butterfly: 3 strikes — +1 PUT @lower, -2 PUT @middle, +1 PUT @upper
const butterfly = client.optionFactory.buildRFQRequest({
  requester: userAddress,
  underlying: 'ETH',
  optionType: 'PUT',
  strikes: [1700, 1800, 1900],     // 3 strikes = BUTTERFLY
  expiry,
  numContracts: 0.001,
  isLong: false,                   // SELL (short) butterfly
  offerDeadlineMinutes: 6,
  collateralToken: 'USDC',
  reservePrice: 0.0001,
  requesterPublicKey: keyPair.compressedPublicKey,
});

// Collateral for a short PUT butterfly = (middle - lower) * numContracts
// $100 wing width * 0.001 = 0.1 USDC
await client.erc20.ensureAllowance(
  client.chainConfig.tokens.USDC.address,
  client.optionFactory.contractAddress,
  100000n,
);
await client.optionFactory.requestForQuotation(butterfly);

// Condor: 4 strikes — +1 @s1, -1 @s2, -1 @s3, +1 @s4
const condor = client.optionFactory.buildRFQRequest({
  requester: userAddress,
  underlying: 'ETH',
  optionType: 'PUT',
  strikes: [1600, 1700, 1800, 1900],  // 4 strikes = CONDOR
  expiry,
  numContracts: 0.001,
  isLong: false,
  offerDeadlineMinutes: 6,
  collateralToken: 'USDC',
  reservePrice: 0.0001,
  requesterPublicKey: keyPair.compressedPublicKey,
});
await client.optionFactory.requestForQuotation(condor);

Physically-settled RFQ (vanilla only)

By default, RFQs are cash-settled. For physical settlement, use the dedicated builder — only vanilla CALL/PUT are supported on-chain.

const physical = client.optionFactory.buildPhysicalOptionRFQ({
  requester: userAddress,
  underlying: 'ETH',
  optionType: 'CALL',
  strike: 2500,
  expiry,
  numContracts: 1,
  isLong: true,
  offerDeadlineMinutes: 30,
  collateralToken: 'WETH',
  requesterPublicKey: keyPair.compressedPublicKey,
});
await client.optionFactory.requestForQuotation(physical);

Settle early (accept an MM offer before the deadline)

const quotationId = 784n;
const currentBlock = await provider.getBlockNumber();

// 1. Pull the MM offers from chain events
const offerEvents = await client.events.getOfferMadeEvents({
  quotationId,
  fromBlock: currentBlock - 1000,
});
const offer = offerEvents[0];

// 2. Decrypt with your keypair
const keyPair = await client.rfqKeys.loadKeyPair();
const decrypted = await client.rfqKeys.decryptOffer(
  offer.signedOfferForRequester,
  offer.signingKey,
);
console.log(`Offer: ${ethers.formatUnits(decrypted.offerAmount, 6)} USDC`);

// 3. Accept on-chain
const { to, data } = client.optionFactory.encodeSettleQuotationEarly(
  quotationId,
  decrypted.offerAmount,
  decrypted.nonce,
  offer.offeror,
);
const tx = await signer.sendTransaction({ to, data });
console.log(`Settled early: ${tx.hash}`);

All structures at a glance

| Structure | Strikes | Implementation | Strike order | | ---------- | ------- | --------------------------- | ------------------------- | | Vanilla | 1 | PUT / INVERSE_CALL | N/A | | Spread | 2 | PUT_SPREAD / CALL_SPREAD| PUT: desc, CALL: asc | | Butterfly | 3 | PUT_FLY / CALL_FLY | PUT: desc, CALL: asc | | Condor | 4 | PUT_CONDOR / CALL_CONDOR| Always ascending | | Iron condor| 4 | IRON_CONDOR | strike1..strike4 asc |

Iron condor strike params are named strike1, strike2, strike3, strike4 — not putLowerStrike / callLowerStrike. Butterfly and call/put fly are PUT_FLY / CALL_FLY (singular, no trailing S).

Position & portfolio flows

// All on-chain positions for an address — pulled from the book indexer
const positions = await client.api.getUserPositionsFromIndexer(userAddress);

// All RFQs you've created (active + historical)
const rfqs = await client.api.getUserRfqs(userAddress);

// Options that materialized from your RFQs after MM acceptance
const rfqOptions = await client.api.getUserOptionsFromRfq(userAddress);

// Lightweight legacy totals
const stats = await client.api.getStatsFromIndexer();
console.log(`Unique users: ${stats.uniqueUsers}, open: ${stats.openPositions}`);

// Richer time-windowed protocol stats (book / factory / combined)
const bookStats = await client.api.getBookProtocolStats();
const factoryStats = await client.api.getFactoryProtocolStats();
const combined = await client.api.getProtocolStats();

// Compute payoff at a hypothetical settlement price
const payoff = client.utils.calculatePayout({
  structure: 'call_spread',
  strikes: [100000n, 105000n],
  size: 1000000n,
  price: 102000n,
  isLong: true,
});

Realtime / WebSocket

const client = new ThetanutsClient({ chainId: 8453, provider });
await client.ws.connect();

const unsubOrders = client.ws.subscribeOrders((update) => {
  console.log(`Order ${update.event}:`, update);
});

const unsubPrices = client.ws.subscribePrices((update) => {
  console.log(`ETH: $${update.price}`);
}, 'ETH');

const unsubState = client.ws.onStateChange((state) => {
  console.log(`WS state: ${state}`);
});

// Tear down when done
// unsubOrders(); unsubPrices(); unsubState();
// client.ws.disconnect();

The WebSocket module auto-reconnects (default 10 attempts). Tune via maxReconnectAttempts / reconnectInterval.

Error handling

All SDK methods throw ThetanutsError with a typed code. The package also exports concrete subclasses for instanceof narrowing.

import {
  ThetanutsError,
  RateLimitError,
  ContractRevertError,
  InsufficientAllowanceError,
  OrderExpiredError,
} from '@thetanuts-finance/thetanuts-client';

try {
  await client.optionBook.fillOrder(order, 10_000000n);
} catch (error) {
  if (error instanceof OrderExpiredError) {
    const fresh = await client.api.fetchOrders();
    // retry with a fresh order
  } else if (error instanceof InsufficientAllowanceError) {
    await client.erc20.ensureAllowance(usdc, optionBook, amount);
    // retry
  } else if (error instanceof ContractRevertError) {
    console.error('Reverted:', error.message, error.cause);
  } else if (error instanceof ThetanutsError) {
    console.error(`SDK error [${error.code}]: ${error.message}`);
  }
}

Error codes

| Code | Meaning | | ------------------------ | -------------------------------------- | | ORDER_EXPIRED | Order expired or expiring imminently | | SLIPPAGE_EXCEEDED | Price moved beyond tolerance | | INSUFFICIENT_ALLOWANCE | Approve the collateral token first | | INSUFFICIENT_BALANCE | Wallet doesn't hold enough tokens | | NETWORK_UNSUPPORTED | Configured chainId isn't supported | | HTTP_ERROR | API/indexer request failed | | CONTRACT_REVERT | On-chain call reverted | | INVALID_PARAMS | Bad arguments to an SDK method | | ORDER_NOT_FOUND | No order with that id | | SIZE_EXCEEDED | Fill size exceeds available collateral | | SIGNER_REQUIRED | This call needs a signer | | WEBSOCKET_ERROR | WS transport failure |

Retrying transient errors

import { RateLimitError } from '@thetanuts-finance/thetanuts-client';

async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (error instanceof RateLimitError) {
        await new Promise((r) => setTimeout(r, 2 ** attempt * 1000));
        continue;
      }
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}

const orders = await withRetry(() => client.api.fetchOrders());

Production checklist

• Bring your own RPC. https://mainnet.base.org is rate-limited and unreliable under load. Use Alchemy, Infura, QuickNode, or your own node.
• Set a referrer if you're routing user flow — fees accrue automatically.
• Wire a logger. Pass a custom logger to forward to Sentry / Datadog / your stack.
• Approve before you fill. The SDK never auto-approves. Always call client.erc20.ensureAllowance() first.
• Check order.expiry upfront. Cheaper than catching OrderExpiredError after a failed gas estimate.
• Configure WS reconnects (maxReconnectAttempts, reconnectInterval) for your uptime targets.
• Back up your RFQ keypair. Node stores keys in .thetanuts-keys/ (perms 0600). If you lose the private key, encrypted MM offers to your old public key are unrecoverable.
• Use a real key store in production. MemoryStorageProvider loses keys on process exit.

Reference

Client configuration

interface ThetanutsClientConfig {
  chainId: 8453;                         // Required: Base mainnet
  provider: Provider;                    // Required: ethers.js provider
  signer?: Signer;                       // Optional: needed for write ops
  referrer?: string;                     // Optional: fee-share address
  apiBaseUrl?: string;                   // Optional: override REST API base
  indexerApiUrl?: string;                // Optional: override indexer
  pricingApiUrl?: string;                // Optional: override MM pricing
  wsUrl?: string;                        // Optional: override WebSocket
  env?: 'dev' | 'prod';                  // Optional: default 'prod'
  logger?: ThetanutsLogger;              // Optional: custom logger
  keyStorageProvider?: KeyStorageProvider; // Optional: override RFQ key store
  rfqKeyPrefix?: string;                 // Optional: namespace stored keys
}

Chain config (no hardcoded addresses)

const config = client.chainConfig;

// Tokens
config.tokens.USDC.address;   // 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
config.tokens.USDC.decimals;  // 6
config.tokens.WETH.address;   // 0x4200000000000000000000000000000000000006
config.tokens.cbBTC.address;  // 0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf

// Cash-settled implementations (OptionBook + RFQ)
config.implementations.PUT;            // Vanilla PUT
config.implementations.INVERSE_CALL;   // Vanilla CALL
config.implementations.PUT_SPREAD;     // Put spread (2 strikes)
config.implementations.CALL_SPREAD;    // Call spread (2 strikes)
config.implementations.PUT_FLY;        // Put butterfly (3 strikes)
config.implementations.CALL_FLY;       // Call butterfly (3 strikes)
config.implementations.PUT_CONDOR;     // Put condor (4 strikes)
config.implementations.CALL_CONDOR;    // Call condor (4 strikes)
config.implementations.IRON_CONDOR;    // Iron condor (4 strikes)

// Physically settled (vanilla only — multi-leg physicals are zero-addressed)
config.implementations.PHYSICAL_PUT;
config.implementations.PHYSICAL_CALL;

// Chainlink price feeds
config.priceFeeds.ETH;
config.priceFeeds.BTC;

Decimal helpers

| Quantity | Decimals | Example | | ------------ | -------- | ----------------------------------------- | | USDC | 6 | 1000000n = 1 USDC | | WETH | 18 | 1000000000000000000n = 1 WETH | | cbBTC | 8 | 100000000n = 1 cbBTC | | Strike/Price | 8 | 185000000000n = $1,850 |

client.utils.toBigInt('100.5', 6);        // 100500000n
client.utils.strikeToChain(1850);         // 185000000000n
client.utils.fromBigInt(100500000n, 6);   // '100.5'
client.utils.strikeFromChain(185000000000n); // 1850

RFQ collateralAmount is always 0

collateralAmount on a quotation params struct must be 0. buildRFQRequest / buildRFQParams enforce this; never override it. Collateral isn't locked at RFQ creation — it's pulled from both parties at settlement. SELL-side RFQs require a prior approve() on the OptionFactory.

RFQ key management

ECDH keypairs are persisted automatically. The default storage backend depends on environment:

| Environment | Default backend | Persistence | | ----------- | ----------------------- | -------------------------------- | | Node.js | internal file storage | .thetanuts-keys/ (perms 0600) | | Browser | explicit provider required | choose app-specific encrypted storage |

const keyPair = await client.rfqKeys.getOrCreateKeyPair();
console.log(keyPair.compressedPublicKey);

// Node persists RFQ keys to ./.thetanuts-keys/ by default.
// For custom persistence, pass any object implementing KeyStorageProvider.
// Browser apps must pass keyStorageProvider explicitly; plaintext localStorage is not used by default.

// Memory-only (tests only — logs a warning, keys lost on exit)
import { MemoryStorageProvider } from '@thetanuts-finance/thetanuts-client';
const testClient = new ThetanutsClient({
  chainId: 8453, provider,
  keyStorageProvider: new MemoryStorageProvider(),
});

Back up your private key. There is no recovery path — lose it and you cannot decrypt offers sent to that public key.

Custom logger

import { ThetanutsClient, consoleLogger } from '@thetanuts-finance/thetanuts-client';

const client = new ThetanutsClient({
  chainId: 8453,
  provider,
  logger: consoleLogger, // built-in
  // logger: { debug, info, warn, error }, // or your own
});

Compatibility

| Requirement | Minimum | | ----------- | --------------- | | Node.js | 18 | | ethers.js | v6 | | TypeScript | 5.0 | | Chain | Base (8453) |

Builds ship as both ESM and CJS with .d.ts declarations, produced by tsup. Both npm and Yarn (incl. Yarn Berry) are supported; CI auto-detects the lockfile.

Directory layout

src/
├── abis/       # Contract ABIs (ERC20, OptionBook, OptionFactory, BaseOption, ...)
├── chains/     # Chain config (addresses, tokens, implementations)
├── client/     # ThetanutsClient
├── modules/    # 14 feature modules
├── types/      # Type definitions
├── utils/      # Helpers
└── index.ts    # Public entry

scripts/
├── run-mainnet-tests.ts       # Live mainnet integration tests
├── benchmark-indexer.ts       # Indexer performance benchmark
└── test-indexer-endpoints.ts  # Indexer endpoint validation

Development

npm install
npm run build           # tsup: ESM + CJS + types
npm run typecheck
npm run lint
npm test                # live mainnet integration tests (needs network)
npm run test:benchmark

See CONTRIBUTING.md for the four required gates and PR conventions.

Documentation & links

| Section | Description | | -------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | Getting Started | Installation, quick start, configuration | | OptionBook | Browse, preview, fill | | RFQ (Factory) | Custom options, multi-leg, RFQ lifecycle | | Pricing | MM pricing, spreads, collateral cost | | Guides | Errors, WebSocket, production checklist | | Loan | Non-liquidatable lending | | SDK Reference | Client, modules, types, utilities | | MCP Server | MCP server for SDK reads and prepare-tool calldata builders |

Copy-paste examples

| File | What it shows | | ------------------------------------------------------------------- | ---------------------------------------------------------- | | docs/examples/fill-order.ts | Full OptionBook fill: preview, approve, execute, errors | | docs/examples/claim-fees.ts | Check + claim referrer fees across all tokens | | docs/examples/create-rfq.ts | RFQ creation (BUY and SELL sides) | | docs/examples/physical-option-rfq.ts | Physically-settled RFQ (vanilla only) | | docs/examples/fetch-pricing.ts | MM pricing with filters | | docs/examples/option-management.ts | Position queries and operations | | docs/examples/query-stats.ts | Protocol and referrer stats |

API reference

• Source overview
• Client
• Modules
• Types
• Utils
• ABIs
• Chains
• Scripts

License & policies

• MIT License
• Contributing guide
• Security policy

Links

• Thetanuts Finance
• Documentation
• GitHub