Positioning

OI dynamics

Returns cohort-level open interest dynamics with classic positioning signals (NEW_LONGS, NEW_SHORTS, LONG_LIQUIDATION, SHORT_COVERING), put/call ratio shifts, OI concentration (HHI), momentum classification, turnover analysis, and a multi-level warning system. One row per cohort per timestamp. Cohorts are the ORIA moneyness x expiry grid (7 x 4 = 28 cohorts per coin). This answers "what are market participants actually holding?" as opposed to liquidity which answers "what do they intend to do?"

GET/v1/positioning/oiproalpha

Query Parameters

coinstringrequired

Underlying asset. Required.

e.g.BTCETH

moneyness_bucketstringoptional

Filter: FAR_ABOVE, ABOVE, NEAR_ABOVE, ATM, NEAR_BELOW, BELOW, FAR_BELOW.

e.g.ATMNEAR_ABOVE

expiration_bucketstringoptional

Filter: DTE_7, DTE_30, DTE_60, DTE_LONG.

e.g.DTE_7

positioning_signalstringoptional

Filter: NEW_LONGS, NEW_SHORTS, LONG_LIQUIDATION, SHORT_COVERING, MIXED, NEUTRAL.

e.g.NEW_LONGS

fromstringoptional

Start UTC (ISO 8601). Default: latest snapshot.

e.g.2026-03-08T00:00:00Z

tostringoptional

End UTC (ISO 8601). Default: now.

e.g.2026-03-09T00:00:00Z

limitintegeroptional

Max rows returned. Default 500, max 5000.

e.g.200

Response Schema

Fields marked pro require a Pro subscription. Fields marked alpha require Alpha.

Field	Type	Tier	Description
`timestamp`	`datetime`	pro	Snapshot time in UTC. Aligned to 10-minute boundary.
`coin`	`string`	pro	Underlying asset.
`moneyness_bucket`	`string`	pro	Moneyness classification: FAR_ABOVE, ABOVE, NEAR_ABOVE, ATM, NEAR_BELOW, BELOW, FAR_BELOW.
`expiration_bucket`	`string`	pro	Expiry classification: DTE_7 (0-7d), DTE_30 (7-30d), DTE_60 (30-60d), DTE_LONG (60d+).
`cohort_name`	`string`	pro	Combined bucket name, e.g. ATM_DTE_7. 28 cohorts per coin.
`underlying_price`	`float`	pro	Spot price at snapshot time.
`underlying_change_24h_pct`	`float`	pro	24h spot price change as pct. Input to positioning signal logic.
`option_count`	`integer`	pro	Total options in this cohort.
`call_count`	`integer`	pro	Call options in cohort.
`put_count`	`integer`	pro	Put options in cohort.
`options_with_oi`	`integer`	pro	Options where OI > 0.
`pct_with_oi`	`float`	pro	Percentage of cohort with actual positions held.
`total_oi_contracts`	`float`	pro	Total OI in contracts across cohort.
`total_oi_usd`	`float`	pro	Total OI in USD (contracts * underlying * contract_size).
`call_oi_contracts`	`float`	pro	Call OI in contracts.
`put_oi_contracts`	`float`	pro	Put OI in contracts.
`call_oi_usd`	`float`	pro	Call OI in USD.
`put_oi_usd`	`float`	pro	Put OI in USD.
`avg_oi_per_option`	`float`	alpha	Average OI per option in cohort.
`max_oi_single_option`	`float`	alpha	Largest single-option OI in cohort. Concentration risk indicator.
`oi_change_1h_contracts`	`float`	alpha	OI change in contracts over 1 hour.
`oi_change_1h_usd`	`float`	alpha	OI change in USD over 1 hour.
`oi_change_1h_pct`	`float`	alpha	OI change as pct over 1 hour.
`oi_change_24h_contracts`	`float`	pro	OI change in contracts over 24 hours.
`oi_change_24h_usd`	`float`	pro	OI change in USD over 24 hours.
`oi_change_24h_pct`	`float`	pro	OI change as pct over 24 hours. Core input to positioning signal.
`call_oi_change_24h_pct`	`float`	pro	Call OI change 24h pct. Compare with put change for directional read.
`put_oi_change_24h_pct`	`float`	pro	Put OI change 24h pct.
`put_call_oi_ratio_change_24h`	`float`	alpha	Shift in put/call ratio over 24h. Rising = increasingly bearish positioning.
`top_3_options_oi_pct`	`float`	alpha	Percentage of cohort OI held in top 3 options. Above 70 = concentration_dangerous warning.
`volume_24h_usd`	`float`	pro	24h volume in USD for context. Compare with OI for turnover analysis.
`oi_to_volume_ratio`	`float`	alpha	OI / volume. High = sticky positions. Low = active churning.
`oi_expiring_24h_pct`	`float`	alpha	Percentage of OI expiring within 24 hours. Above 50 = expiration_heavy warning.
`oi_warning_level`	`integer`	alpha	Warning severity: 0 = OK, 1 = WATCH, 2 = WARNING, 3 = CRITICAL.
`is_oi_surging`	`boolean`	alpha	TRUE if OI increased >50 pct in 24h. Strong conviction building.
`is_oi_collapsing`	`boolean`	alpha	TRUE if OI decreased >30 pct in 24h. Mass liquidation / expiry event.
`is_put_call_extreme`	`boolean`	alpha	TRUE if put/call ratio is outside normal range. Sentiment extreme.
`is_concentration_dangerous`	`boolean`	alpha	TRUE if top 3 options hold >70 pct of OI. Fragility risk.
`is_expiration_heavy`	`boolean`	alpha	TRUE if >50 pct of OI expires within 24h. Pinning/rollover event.
`warning_flags`	`string[]`	alpha	Array of active warnings: OI_SURGING, OI_COLLAPSING, PUT_CALL_EXTREME, CONCENTRATION_DANGEROUS, EXPIRATION_HEAVY.
`put_call_oi_ratio`	`float`	pro	Sentiment indicator: are participants positioned bearish or bullish? See detail ↓
`positioning_signal`	`string`	pro	Classic OI + price interpretation: who is building positions? See detail ↓
`positioning_strength`	`float`	alpha	Confidence in the positioning signal (0-100) See detail ↓
`oi_hhi`	`float`	alpha	OI concentration: is positioning spread across many options or concentrated in a few? See detail ↓
`turnover_rate`	`float`	alpha	Position churn: are holders committed or scratching? See detail ↓
`oi_momentum`	`string`	alpha	OI trend classification See detail ↓

Derived Fields

FieldTypeTiercollapse all

▶put_call_oi_ratiofloatprocollapse

Sentiment indicator: are participants positioned bearish or bullish?

Put OI / call OI for this cohort. Above 1 = more put positions (bearish). Below 1 = more call positions (bullish). The absolute level matters less than the change (put_call_oi_ratio_change_24h). A ratio shifting from 0.8 to 1.2 in 24h is a stronger signal than a stable 1.5.

Put/call OI ratio

\text{put\_call\_ratio} = \frac{\text{put\_oi\_contracts}}{\text{call\_oi\_contracts}}

Range0 to unbounded. Typically 0.3 to 3.0. Above 1.5 = bearish skew. Below 0.7 = bullish skew.

▶positioning_signalstringprocollapse

Classic OI + price interpretation: who is building positions?

The textbook positioning read. Rising OI + rising price = NEW_LONGS (bulls entering). Rising OI + falling price = NEW_SHORTS (bears entering). Falling OI + falling price = LONG_LIQUIDATION (bulls forced out). Falling OI + rising price = SHORT_COVERING (bears closing). MIXED when signals conflict. NEUTRAL when OI change is small.

OI change x price direction matrix

\text{signal} = \begin{cases} \text{NEW\_LONGS} & \text{OI} \uparrow \text{ AND price} \uparrow \\ \text{NEW\_SHORTS} & \text{OI} \uparrow \text{ AND price} \downarrow \\ \text{LONG\_LIQUIDATION} & \text{OI} \downarrow \text{ AND price} \downarrow \\ \text{SHORT\_COVERING} & \text{OI} \downarrow \text{ AND price} \uparrow \end{cases}

RangeNEW_LONGS, NEW_SHORTS, LONG_LIQUIDATION, SHORT_COVERING, MIXED, NEUTRAL

▶positioning_strengthfloatalphacollapse

Confidence in the positioning signal (0-100)

How strongly the OI change and price direction align. 100 = massive OI change with clear price direction. 0 = negligible change. Below 50, the signal is noise.

Range0-100.

▶oi_hhifloatalphacollapse

OI concentration: is positioning spread across many options or concentrated in a few?

Herfindahl-Hirschman Index for OI distribution within the cohort. Sum of squared OI shares * 10000. Below 1500 = diverse (stable). Above 2500 = concentrated (fragile, single-option risk). High HHI combined with is_concentration_dangerous = positions are crowded in one or two strikes.

Herfindahl-Hirschman Index

\text{HHI} = \sum_{i} \left(\frac{OI_i}{OI_{\text{total}}}\right)^2 \times 10000

Range0-10000. Below 1500 = diverse. Above 2500 = concentrated.

▶turnover_ratefloatalphacollapse

Position churn: are holders committed or scratching?

Volume / OI. High turnover = active trading, positions churning (scratching, rolling). Low turnover = sticky positions, holders committed. The combination of turnover with OI change is the key: high volume + stable OI = scratching. High volume + rising OI = conviction building.

Volume / OI ratio

\text{turnover} = \frac{\text{volume\_24h\_usd}}{\text{total\_oi\_usd}}

Range0 to unbounded. Below 0.1 = very sticky. Above 1.0 = heavy churn.

▶oi_momentumstringalphacollapse

OI trend classification

Human-readable trend. RAPID_BUILDUP (>30 pct increase in 24h): strong conviction entering. GRADUAL_BUILDUP (>10 pct): steady accumulation. STABLE (-10 to +10 pct): no significant change. GRADUAL_UNWIND (-10 to -25 pct): positions being reduced. RAPID_UNWIND (>25 pct decrease): mass liquidation, early warning signal.

RangeRAPID_BUILDUP, GRADUAL_BUILDUP, STABLE, GRADUAL_UNWIND, RAPID_UNWIND

Suggested Calculations

Not included in the API response. Compute these client-side from the fields above. Formulas and context provided.

FieldTypeInputsexpand all

▶oi_heatmapstringclient-sideWhere are positions concentrated on the surface?expand

Where are positions concentrated on the surface?

Pivot total_oi_usd into a 7x4 grid (moneyness rows x expiry columns). Color by OI size. This IS the positioning map: where are people actually holding positions? In crypto, ATM DTE_7 and ATM DTE_30 typically hold the most OI. But when FAR_BELOW DTE_7 lights up, someone is buying crash protection for this week. That is a signal.

Inputstotal_oi_usdmoneyness_bucketexpiration_bucket

▶oi_change_directionstringclient-sideIs the market building or unwinding positions?expand

Is the market building or unwinding positions?

Map oi_change_24h_pct across the grid. Positive = new positions entering. Negative = positions closing. Where on the surface is change happening? If ATM is flat but FAR_BELOW is building rapidly (+40 pct), someone is quietly buying crash insurance. If everything is unwinding simultaneously, it is a risk-off event or mass expiry.

Inputsoi_change_24h_pctmoneyness_bucketexpiration_bucket

▶oi_vs_volume_divergencestringclient-sideCompare what is held vs what is tradedexpand

Compare what is held vs what is traded

Use total_oi_usd from this endpoint and total_volume_usd from /v1/positioning/volume at the same strikes. High OI + low volume = sticky positions, holders committed. High volume + low OI = day trading, no conviction. Rising OI + rising volume = conviction building. The divergence between the two tells you whether activity is noise or signal.

Inputstotal_oi_usdtotal_volume_usd

Or use the pre-computed endpointalpha

Strike-level volume at /v1/positioning/volume (Pro).

▶simple_positioning_readstringclient-sideAre new positions being opened or old ones closed?expand

Are new positions being opened or old ones closed?

The simplest positioning framework: is OI rising or falling? Rising OI means new money entering the market (someone is opening new contracts). Falling OI means existing positions are being closed (someone is exiting). Combine with price direction (check underlying_price vs yesterday): rising OI + rising price = bullish conviction. Rising OI + falling price = bearish conviction. This is a simplified version of the positioning_signal derived field.

Inputsoi_change_24h_pctoi_change_24h_contractsunderlying_price

▶call_put_oi_divergencestringclient-sideAre calls and puts moving in the same direction?expand

Are calls and puts moving in the same direction?

Compare call vs put OI change. Both rising = market uncertainty (hedging both directions). Calls rising + puts falling = rotation into bullish positions. Puts rising + calls falling = rotation into protection. The divergence between call and put OI changes reveals whether positioning is directional or hedging.

Inputscall_oi_change_24h_pctput_oi_change_24h_pct

▶cross_cohort_positioningstringclient-sideWhere on the surface are positions building?expand

Where on the surface are positions building?

Map positioning signals across the moneyness x expiry grid. NEW_LONGS concentrated in ATM DTE_7 = short-term directional bet. NEW_LONGS in ABOVE DTE_60 = longer-term bullish. SHORT_COVERING in FAR_BELOW = tail risk unwinding. The spatial pattern across cohorts reveals strategy, not just direction.

Inputspositioning_signalmoneyness_bucketexpiration_bucket

▶oi_gex_cross_readstringclient-sideHow do OI changes interact with GEX structure?expand

How do OI changes interact with GEX structure?

Rising OI at the GEX magnetic strike strengthens pinning (more gamma = stronger magnet). Rising OI at strikes outside the pinning zone weakens it (distributed gamma). Cross-reference cohort OI changes with /v1/gex/strikes concentration data to assess whether positioning reinforces or undermines the current gamma structure.

Or use the pre-computed endpointalpha

Strike-level OI breakdown and GEX at /v1/gex/strikes. Pinning intelligence at /v1/gex/pinning.

▶warning_severity_screenstringclient-sideScreen for dangerous OI conditions across all cohortsexpand

Screen for dangerous OI conditions across all cohorts

Filter for oi_warning_level >= 2 to find WARNING and CRITICAL conditions. Cross-reference warning_flags to identify the specific risk: OI_SURGING (conviction extreme), OI_COLLAPSING (mass liquidation), CONCENTRATION_DANGEROUS (crowded), EXPIRATION_HEAVY (pinning event). Multiple warnings on the same cohort = compounding risk.

Inputsoi_warning_levelwarning_flags