Reference

Symbol Format

Diffusal uses a consistent symbol format for option identification:

Format: UNDERLYING-STRIKE-TYPE-EXPIRY[-SHORT]

Component	Description	Example
UNDERLYING	Asset ticker (uppercase)	BTC, ETH, SHIB
STRIKE	Price with underscore decimal	82000, 3550_5, 0_00001234
TYPE	C (call) or P (put)	C, P
EXPIRY	Unix timestamp (seconds)	1736409600
SHORT	Optional suffix for short positions	-SHORT

Expiry Time

All options expire at 08:00 UTC (4:00 PM Singapore/HKT). The expiry is encoded as a Unix timestamp in the symbol.

Time Zone Reference:

Time Zone	Expiry Time
UTC	08:00
Singapore/HKT	16:00 (4:00 PM)
London (GMT)	08:00
New York (EST)	03:00
New York (EDT)	04:00
Tokyo (JST)	17:00

Strike Format Rules

Rule	Input	Output
Underscore as decimal separator	3550.5	`3550_5`
Strip trailing zeros	3550.50	`3550_5`
Keep leading zero for values less than 1	0.5	`0_5`
Whole numbers: no underscore	82000.0	`82000`

Examples by Price Range

Large Cap Assets (BTC, ETH)

Asset	Strike ($)	Symbol
BTC	82,000	`BTC-82000-C-1736409600`
BTC	100,000.50	`BTC-100000_5-C-1736409600`
ETH	3,550	`ETH-3550-P-1736409600`
ETH	3,550.50	`ETH-3550_5-C-1736409600`
ETH	3,550.05	`ETH-3550_05-C-1736409600`

Mid Cap Assets (SOL, AVAX)

Asset	Strike ($)	Symbol
SOL	123	`SOL-123-C-1736409600`
SOL	123.45	`SOL-123_45-C-1736409600`
SOL	123.456	`SOL-123_456-P-1736409600`
AVAX	45.50	`AVAX-45_5-C-1736409600`

Small Cap Assets (DOGE, MATIC)

Asset	Strike ($)	Symbol
DOGE	0.35	`DOGE-0_35-C-1736409600`
DOGE	0.355	`DOGE-0_355-P-1736409600`
MATIC	1.25	`MATIC-1_25-C-1736409600`

Micro Cap / Memecoins (SHIB, PEPE)

Asset	Strike ($)	Symbol
SHIB	0.00001234	`SHIB-0_00001234-C-1736409600`
SHIB	0.0000123	`SHIB-0_0000123-P-1736409600`
PEPE	0.00000089	`PEPE-0_00000089-C-1736409600`

Edge Cases

Trailing Zero Handling

Input Value	Incorrect	Correct
3550.50	`3550_50`	`3550_5`
3550.00	`3550_00`	`3550`
100.10	`100_10`	`100_1`
0.500	`0_500`	`0_5`

Precision Examples

Decimal Places	Example Strike	Symbol Strike
0 (whole)	82000	`82000`
1	3550.5	`3550_5`
2	123.45	`123_45`
3	45.125	`45_125`
5	0.00035	`0_00035`
8	0.00001234	`0_00001234`

Short Position Examples

Position	Symbol
Long BTC call	`BTC-82000-C-1736409600`
Short BTC call	`BTC-82000-C-1736409600-SHORT`
Long ETH put	`ETH-3550_5-P-1736409600`
Short ETH put	`ETH-3550_5-P-1736409600-SHORT`

User-Facing Symbol Format

For human-readable display and external integrations, use the user-facing format:

Format: UNDERLYING-DDMMMYY-STRIKE-TYPE

Component	Description	Example
UNDERLYING	Asset ticker (uppercase)	BTC, ETH, SHIB
DDMMMYY	Expiry date	09JAN26, 28MAR25
STRIKE	Price with underscore decimal	82000, 3550_5, 0_00001234
TYPE	C (call) or P (put)	C, P

Examples:

Diffusal (Internal)	User-Facing
`BTC-82000-C-1736409600`	`BTC-09JAN26-82000-C`
`ETH-3550_5-P-1743148800`	`ETH-28MAR25-3550_5-P`
`SHIB-0_00001234-C-1736409600`	`SHIB-09JAN26-0_00001234-C`

Use the Symbol Translate API to convert between formats.

Error Codes

Error Response Format

All API errors return a consistent JSON structure:

{
  "error": "error_code",
  "message": "Human-readable description",
  "details": {}
}

Error Codes Reference

Error Code	HTTP Status	Description
`not_found`	404	Resource not found (series, pair, portfolio, etc.)
`unauthorized`	401	Authentication required or invalid
`auth_error`	401	Authentication flow error
`validation_error`	400	Invalid input parameters
`rate_limited`	429	Too many requests
`indexer_error`	500	Failed to fetch data from indexer
`chain_error`	500	Failed to read from blockchain
`cache_update_error`	500	Internal cache synchronization failed

Error Examples

Not Found (404)

{
  "error": "not_found",
  "message": "Series not found: 0x123abc..."
}

Validation Error (400)

{
  "error": "validation_error",
  "message": "Must be a valid bytes32 hex",
  "details": {
    "field": "pairId"
  }
}

Rate Limited (429)

{
  "error": "rate_limited",
  "message": "Too many requests",
  "details": {
    "limit": 50,
    "resetAt": 1700000000000
  }
}

Rate Limits

Endpoint Category	Unauthenticated	Authenticated
Market Data (`/markets/*`)	60/min	300/min
Helpers (`/helpers/*`)	100/min	300/min
Account (`/account/*`)	—	120/min
Auth (`/api/auth/*`)	10/min	20/min

Data Types

Numeric Precision

WAD Format (18 Decimals)

Most numeric values use WAD format — 18 decimal fixed-point representation returned as strings.

Value	WAD Representation
1.0	`"1000000000000000000"`
100.5	`"100500000000000000000"`
0.001	`"1000000000000000"`

Used for: Prices, Greeks, volatility, margin amounts, position sizes

USDC Format (6 Decimals)

Collateral and fee amounts use USDC's native 6-decimal precision.

Value	USDC Representation
$1.00	`"1000000"`
$100.50	`"100500000"`
$0.01	`"10000"`

Used for: Deposits, withdrawals, fees, equity

Field Precision Reference

This section clarifies which numeric format each API field uses.

Ticker Response (GET /markets/ticker/:symbol)

Field	Format	Decimals	Example Raw	Human Value
`markPrice`	WAD	18	`"1050000000000000000"`	1.05
`indexPrice`	WAD	18	`"95000000000000000000000"`	95,000
`bestBid`	WAD	18	`"1000000000000000000"`	1.0
`bestAsk`	WAD	18	`"1100000000000000000"`	1.1
`delta`	WAD	18	`"550000000000000000"`	0.55
`gamma`	WAD	18	`"1000000000000000"`	0.001
`vega`	WAD	18	`"50000000000000000000"`	50.0
`theta`	WAD	18	`"-10000000000000000"`	-0.01
`rho`	WAD	18	`"5000000000000000"`	0.005
`iv`	WAD	18	`"800000000000000000"`	0.80 (80%)
`volume24h`	WAD	18	`"1000000000000000000000"`	1,000

Portfolio Response (GET /account/portfolios/:id)

Field	Format	Decimals	Notes
`deposit`	USDC	6	Raw USDC deposited
`equity`	USDC	6	Deposit + unrealized PnL
`unrealizedPnl`	USDC	6	Mark-to-market PnL
`initialMargin`	WAD	18	IM requirement
`maintenanceMargin`	WAD	18	80% of IM
`maxWithdraw`	USDC	6	Maximum withdrawable
`healthRatio`	WAD	18	Equity / MM ratio

Position Response (GET /account/portfolios/:id/positions)

Field	Format	Decimals	Notes
`optionBalance`	WAD	18	Signed: negative = short
`premiumBalance`	USDC	6	Deferred premium
`entryPrice`	WAD	18	Average entry price
`markPrice`	WAD	18	Current mark price
`notional`	WAD	18	abs(balance) × spot
`unrealizedPnl`	WAD	18	Position PnL
`delta`	WAD	18	Position delta
`gamma`	WAD	18	Position gamma
`vega`	WAD	18	Position vega
`theta`	WAD	18	Position theta

Order Book Response (GET /markets/orderbook/:symbol)

Field	Format	Decimals
`price`	WAD	18
`size`	WAD	18

Trade Response (GET /markets/trades/:symbol)

Field	Format	Decimals
`price`	WAD	18
`size`	WAD	18

Collateral Response (GET /account/portfolios/:id/collateral)

Field	Format	Decimals
`deposit`	USDC	6
`maxWithdraw`	USDC	6
`locked`	USDC	6

Fee Response (GET /account/fees)

Field	Format	Decimals
`totalFeesPaid`	USDC	6
`fees24h`	USDC	6
`makerFees`	USDC	6
`takerFees`	USDC	6
`rebatesReceived`	USDC	6

Common Data Structures

Market/Series Object

{
  seriesId: string,      // bytes32 hex
  symbol: string,        // "BTC-82000-C-1736409600"
  pairId: string,        // bytes32 hex
  pairSymbol: string,    // "BTC-USD"
  strike: string,        // WAD
  expiry: number,        // Unix seconds
  isCall: boolean,
  isSettled: boolean
}

Ticker Object

{
  symbol: string,
  seriesId: string,
  markPrice: string,     // WAD - Black-Scholes price
  indexPrice: string,    // WAD - Spot price
  bestBid: string | null,
  bestAsk: string | null,
  // Greeks (all WAD)
  delta: string,
  gamma: string,
  vega: string,
  theta: string,
  rho: string,
  iv: string,            // Implied volatility
  // 24h Stats
  volume24h: string,
  trades24h: number,
  priceChange24h: string,
  high24h: string | null,
  low24h: string | null,
  openInterest: string,
  lastTradeAt: number | null
}

Position Object

{
  seriesId: string,
  symbol: string,
  optionBalance: string,   // Signed WAD (negative = short)
  premiumBalance: string,  // USDC
  entryPrice: string | null,
  realizedPnl: string,
  markPrice: string,
  notional: string,        // balance x markPrice
  unrealizedPnl: string,
  // Greeks (all WAD)
  delta: string,
  gamma: string,
  vega: string,
  theta: string
}

Portfolio Object

{
  id: number,
  deposit: string,           // USDC
  equity: string,            // USDC
  unrealizedPnl: string,     // USDC
  initialMargin: string,     // WAD
  maintenanceMargin: string, // WAD
  maxWithdraw: string,       // USDC
  isHealthy: boolean,
  isLiquidatable: boolean,
  healthRatio: string,       // WAD (equity/MM)
  positionCount: number
}

Order Book Level

{
  price: string,      // WAD
  size: string,       // WAD
  orderCount: number
}

Trade Object

{
  id: string,
  price: string,      // WAD (premium)
  size: string,       // WAD
  side: "buy" | "sell",
  timestamp: number   // Unix seconds
}

Identifier Formats

Type	Format	Example
Series ID	bytes32 hex	`0x1234...abcd` (66 chars)
Pair ID	bytes32 hex	`0xabcd...1234` (66 chars)
Address	Ethereum address	`0x1234...5678` (42 chars)

Conversion Examples

WAD to Human-Readable

const wadValue = "3550500000000000000000"; // 3550.5 in WAD
const humanValue = Number(wadValue) / 1e18; // 3550.5

USDC to Human-Readable

const usdcValue = "100500000"; // $100.50 in USDC
const humanValue = Number(usdcValue) / 1e6; // 100.5

Tick to Price

// tick x 10^(18 - tickDecimals) = WAD price
const tick = 82000;
const tickDecimals = 2;
const wadPrice = tick * 10 ** (18 - tickDecimals);
// 82000 x 10^16 = 820000000000000000000 (82000 WAD)

Signed Values

Position balances use signed values:

Balance	Meaning
Positive	Long position
Negative	Short position
Zero	No position

Reference

On this page