MCP Server
A read-only MCP (Model Context Protocol) server that exposes Thetanuts SDK functionality to AI agents and LLM-powered tools.
This server is READ-ONLY. It does not execute transactions, handle private keys, or perform any state-changing operations. Encoding tools return calldata for wallet signing only.
For full details, see mcp-server/README.md and mcp-server/SPEC.md.
Tip for LLM users: if you don't need a persistent MCP connection, you can paste a one-line prompt into Claude or Cursor and have your LLM fetch the SDK context directly. See LLM Context for the copy-paste prompt.
Available Tools
LLM Context Tools (call these first)
If you're an LLM connecting for the first time, call get_sdk_context once and cache the result for the session — it returns the full embedded SDK context (every module, key types, common workflows, gotchas) in ~35 KiB of markdown. Same content as the llms-full.txt at the repo root.
get_sdk_context
Full long-form SDK context. Call this first — covers every module and the common gotchas
get_sdk_context_index
Curated index of canonical SDK docs (llmstxt.org spec) — links only
get_sdk_context_size
Byte size of the embedded context — use to budget before fetching
These three handlers run before the chain client is initialized, so they don't consume an RPC call.
Indexer API (OptionBook data)
get_stats
Protocol statistics
get_user_positions
User's option positions
get_user_history
User's trade history
get_referrer_stats
Aggregated stats for a referrer address
State / RFQ API
get_rfq
Get specific RFQ by ID
get_user_rfqs
User's RFQ history
Market & Orders
get_market_data
Current prices for BTC, ETH, SOL, etc.
get_market_prices
All supported asset prices
fetch_orders
All orders from the order book
filter_orders
Filter orders by asset, type, or expiry
Token & Option Data
get_token_balance
Token balance for address
get_token_allowance
Token allowance for spender
get_token_info
Token decimals and symbol
get_option_info
Option contract details
get_full_option_info
All strikes, positions, and settlement status
calculate_option_payout
Calculate payout at settlement price
preview_fill_order
Dry-run order fill preview
MM Pricing
get_mm_all_pricing
All MM-adjusted pricing for an asset
get_mm_ticker_pricing
MM pricing for a specific ticker
get_mm_position_pricing
Position-aware MM pricing with collateral cost
get_mm_spread_pricing
MM pricing for a two-leg spread
get_mm_condor_pricing
MM pricing for a four-leg condor
get_mm_butterfly_pricing
MM pricing for a three-leg butterfly
RFQ Quotation Tools
get_quotation
Quotation info by ID including parameters and state
get_quotation_count
Total quotations created
get_user_offers
All RFQ offers made by a user
get_user_options
All options held by a user
encode_settle_quotation
Encode settlement transaction (returns tx data)
encode_settle_quotation_early
Encode early settlement before offer period ends
encode_cancel_quotation
Encode cancellation transaction
encode_cancel_offer
Encode offer cancellation
RFQ Builder Tools
build_rfq_request
Build RFQ for vanilla PUT or CALL
build_spread_rfq
Build two-leg spread RFQ
build_butterfly_rfq
Build three-leg butterfly RFQ
build_condor_rfq
Build four-leg condor RFQ
build_iron_condor_rfq
Build four-leg iron condor RFQ
build_physical_option_rfq
Build physically settled vanilla RFQ
encode_request_for_quotation
Encode RFQ creation transaction
Calculation Tools
calculate_payout
Calculate payoff for structures
calculate_num_contracts
Number of contracts from trade amount
calculate_collateral_required
Collateral required for a position in USDC
calculate_premium_per_contract
Premium per contract in USD from MM price
calculate_reserve_price
Total reserve price (minimum acceptable premium)
calculate_delivery_amount
Delivery amount for physical options
calculate_protocol_fee
Protocol fee for an RFQ trade
convert_decimals
Convert to/from chain decimals
Validation Tools
validate_butterfly
Validate butterfly strike configuration
validate_condor
Validate condor strike configuration
validate_iron_condor
Validate iron condor strike configuration
validate_ranger
Validate ranger option strike configuration
Chain Configuration Tools
get_chain_config
Chain contracts and tokens
get_chain_config_by_id
Full chain configuration by chain ID
get_token_config_by_id
Token configuration by chain ID and symbol
get_option_implementation_info
All implementation addresses and deployment status
Encoding Tools (Transaction Builders)
encode_fill_order
Encode fill order transaction (returns calldata)
encode_approve
Encode token approval transaction (returns calldata)
Event Query Tools
get_order_fill_events
Historical fill events
get_option_created_events
Historical option creation events
get_quotation_requested_events
Historical RFQ request events
get_quotation_settled_events
Historical RFQ settlement events
get_position_closed_events
Position close events for a specific option
Utility Tools
parse_ticker
Parse option ticker (e.g., "ETH-16FEB26-1800-P") into components
build_ticker
Build option ticker from components
get_position_info
Position information for buyer or seller
generate_example_keypair
Generate example ECDH keypair (demo only)
Ranger Tools (RangerOption — zone-bound 4-strike payoff)
get_ranger_info
Full state of a Ranger position (buyer, seller, strikes, zone, expiry)
get_ranger_zone
Inner zone bounds where the buyer earns max payout
get_ranger_spread_width
Per-leg spread width (s2-s1 == s4-s3)
get_ranger_twap
Current TWAP from the option's price-feed consumer
calculate_ranger_payout
On-chain payout at a specific settlement price
simulate_ranger_payout
Simulate payout for hypothetical strikes/numContracts (pure)
calculate_ranger_required_collateral
Required collateral for given strikes + numContracts
Loan Tools (Non-liquidatable lending)
get_lending_opportunities
Fetch unfilled loan limit orders from the loan indexer
get_loan_request
On-chain state for a specific loan quotation
get_user_loans
All loans for an address from the loan indexer
get_loan_option_info
Details for a loan-issued option (strike, expiry, collateral, underlying)
is_loan_option_itm
Whether a loan-issued option is currently in-the-money
fetch_loan_pricing
Deribit-style option pricing (30s cache)
get_loan_strike_options
Filtered strike options grouped by expiry
WheelVault Tools (Ethereum mainnet — chainId 1)
WheelVault is gated to chainId 1; tools throw NETWORK_UNSUPPORTED unless THETANUTS_RPC_URL points at Ethereum mainnet.
get_wheel_vault_state
Full state of a WheelVault series (balances, shares, last price)
get_wheel_vault_series
Raw on-chain series struct
get_wheel_vault_series_count
Total number of series in a WheelVault
preview_wheel_deposit
Pre-flight: expected shares minted for a paired deposit
preview_wheel_withdraw
Pre-flight: expected base/quote returned for a share redemption
get_wheel_depth_chart
Depth-chart data across IV buckets
get_wheel_buyer_options
Options held by a buyer (paginated via fromId/maxCount)
get_wheel_seller_positions
Seller exposures within a series
get_wheel_claimable_summary
Aggregate claimable amounts across multiple series
StrategyVault Tools (Base — Fixed-strike + CLVEX vaults)
get_strategy_vault_state
Full vault state (assets, shares, next expiry, recovery state)
get_strategy_vault_total_assets
Base + quote assets currently held
get_strategy_vault_share_balance
A user's share balance in a vault
get_strategy_vault_next_expiry
Next option-creation expiry timestamp
can_strategy_vault_create_option
Whether createOption() is currently eligible
is_strategy_vault_recovery_mode
Whether the vault is paused for emergency withdrawals
get_all_strategy_vaults
Live state of every fixed-strike + CLVEX vault
get_fixed_strike_vaults
Live state of fixed-strike vaults only
get_clvex_vaults
Live state of CLVEX directional/condor vaults only
Setup
Build
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
Other MCP Clients
Add to .mcp.json at your project root:
Development (no build required)
Environment Variables
THETANUTS_RPC_URL
https://mainnet.base.org
RPC endpoint for on-chain reads
Example Calls
Get market prices
Filter ETH call orders
Get MM pricing for a specific ticker
Encode a fill (returns calldata, does not send)
See Also
mcp-server/README.md — full setup instructions and examples
mcp-server/SPEC.md — tool parameter schemas
Error Handling — error codes used by the underlying SDK
Last updated