@thetanuts-test/api

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

Installation

``bash


pnpm

pnpm add @thetanuts-test/api

npm

npm install @thetanuts-test/api

yarn

yarn add @thetanuts-test/api
`

Quick Start

`typescript
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

`typescript
// 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

$3

#### getPositions(address, options?)

Get all positions for an address.

`typescript
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.

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

#### getOpenPositions(address, options?)

Convenience method for open positions.

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

---

$3

#### getOrderHistory(address, options?)

Get order history for an address.

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

#### getOrder(orderId)

Get a specific order.

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

#### getPendingOrders(address, options?)

Get pending orders.

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

---

$3

#### getPricing(asset, options?)

Get options pricing for an asset.

`typescript
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.

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

---

$3

#### getQuote(params)

Get a quote for a specific trade.

`typescript
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.

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

---

$3

#### getFactoryState(chainId)

Get factory contract state.

`typescript
const state = await api.getFactoryState(8453)

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

#### getCollaterals(chainId)

Get supported collateral tokens.

`typescript
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

`typescript
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
}
}
`

$3

| 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:

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

Pagination

All list endpoints support pagination:

`typescript
// 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