@thetanuts-test/api

REST API wrappers for Thetanuts V4 - positions, pricing, order history, and more.

Installation

# pnpm
pnpm add @thetanuts-test/api

# npm
npm install @thetanuts-test/api

# yarn
yarn add @thetanuts-test/api

Quick Start

import { createThetanutsApi } from '@thetanuts-test/api'

// Create API client
const api = createThetanutsApi()

// Get user positions
const positions = await api.getPositions('0xYourAddress...', {
  chainId: 8453,
})

// Get options pricing
const pricing = await api.getPricing('ETH')

Configuration

// Default configuration
const api = createThetanutsApi()

// Custom configuration
const api = createThetanutsApi({
  baseUrl: 'https://api.thetanuts.finance/v4', // Custom API URL
  apiKey: 'your-api-key',                       // API key (if required)
  timeout: 30000,                               // Request timeout (ms)
})

API Reference

Positions

getPositions(address, options?)

Get all positions for an address.

const positions = await api.getPositions('0x...', {
  chainId: 8453,      // Optional: Filter by chain
  status: 'open',     // Optional: 'open', 'closed', 'expired', 'settled'
  page: 1,            // Optional: Page number
  limit: 20,          // Optional: Items per page
})

// Response
{
  data: Position[],
  total: 100,
  page: 1,
  limit: 20,
  hasMore: true
}

getPosition(positionId)

Get a specific position by ID.

const position = await api.getPosition('position-id-123')

getOpenPositions(address, options?)

Convenience method for open positions.

const openPositions = await api.getOpenPositions('0x...', {
  chainId: 8453,
})

Orders

getOrderHistory(address, options?)

Get order history for an address.

const orders = await api.getOrderHistory('0x...', {
  chainId: 8453,
  status: 'filled',   // 'pending', 'filled', 'cancelled', 'expired'
  page: 1,
  limit: 50,
})

getOrder(orderId)

Get a specific order.

const order = await api.getOrder('order-id-123')

getPendingOrders(address, options?)

Get pending orders.

const pending = await api.getPendingOrders('0x...', {
  chainId: 8453,
})

Pricing

getPricing(asset, options?)

Get options pricing for an asset.

const pricing = await api.getPricing('ETH', { chainId: 8453 })

// Response
{
  asset: 'ETH',
  spotPrice: '3500.00',
  strikes: [
    {
      strike: '3000',
      expiryTimestamp: 1699999999,
      call: { bid: '100', ask: '105', iv: '0.65', delta: '0.7', ... },
      put: { bid: '50', ask: '55', iv: '0.60', delta: '-0.3', ... }
    },
    // ...
  ],
  updatedAt: 1699900000
}

getAllPricing(options?)

Get pricing for all available assets.

const allPricing = await api.getAllPricing({ chainId: 8453 })
// Returns: OptionsPricing[]

Quotes

getQuote(params)

Get a quote for a specific trade.

const quote = await api.getQuote({
  asset: 'ETH',
  type: 'call',            // 'call' or 'put'
  strike: '3500',
  expiryTimestamp: 1699999999,
  numContracts: '10',
  isBuy: true,
  chainId: 8453,
})

// Response
{
  price: '150.00',
  totalCost: '1500.00',
  slippage: '0.5',
  expiresAt: 1699900060,
  fees: {
    protocolFee: '15.00',
    referralFee: '0.00'
  }
}

getAvailableQuotes(options?)

Get available quotes from the order book.

const quotes = await api.getAvailableQuotes({
  asset: 'ETH',
  chainId: 8453,
})

Factory State

getFactoryState(chainId)

Get factory contract state.

const state = await api.getFactoryState(8453)

// Response
{
  chainId: 8453,
  factoryAddress: '0x...',
  totalQuotations: 1500,
  activeQuotations: 120,
  collaterals: [...],
  updatedAt: 1699900000
}

getCollaterals(chainId)

Get supported collateral tokens.

const collaterals = await api.getCollaterals(8453)

// Response
[
  { address: '0x...', symbol: 'USDC', decimals: 6, isNative: false },
  { address: '0x...', symbol: 'ETH', decimals: 18, isNative: true },
]

Error Handling

import { ThetanutsApiError } from '@thetanuts-test/api'

try {
  const positions = await api.getPositions('0x...')
} catch (error) {
  if (error instanceof ThetanutsApiError) {
    console.error('Error:', error.message)
    console.error('Code:', error.code)       // e.g., 'NOT_FOUND'
    console.error('Status:', error.status)   // e.g., 404
    console.error('Details:', error.details) // Additional info
  }
}

Error Codes

| Code | Description | |------|-------------| | NOT_FOUND | Resource not found | | UNAUTHORIZED | Authentication required | | RATE_LIMITED | Too many requests | | TIMEOUT | Request timed out | | NETWORK_ERROR | Network connectivity issue | | UNKNOWN_ERROR | Unexpected error |

TypeScript

Import types as needed:

import type {
  ApiClientConfig,
  Position,
  Order,
  OptionsPricing,
  StrikePricing,
  Quote,
  QuoteParams,
  FactoryState,
  CollateralInfo,
  PaginatedResponse,
} from '@thetanuts-test/api'

Pagination

All list endpoints support pagination:

// First page
const page1 = await api.getPositions(address, { page: 1, limit: 20 })

// Check for more
if (page1.hasMore) {
  const page2 = await api.getPositions(address, { page: 2, limit: 20 })
}

License

MIT