# OIWAP (/strategies/oiwap) OIWAP, or Open-Interest-Weighted Average Price, executes a user-supplied side and amount according to expected and observed changes in derivatives open interest. You choose what to buy or sell and the total duration. The strategy decides when to work the order and how large each child should be. OIWAP is an execution strategy, not a directional signal. Rising or falling open interest does not cause it to choose `buy` or `sell`; both represent market activity, while the user supplies the side. Market Lab executes OIWAP orders on BULK, Hyperliquid core or HIP-3 perpetuals, and HyperLink. MMT supplies the normalized historical and live open-interest data used for the trajectory. The execution venue's trade volume, orderbook, and fills independently constrain what can be executed. > OIWAP can place real post-only limit and market orders. Preview the complete plan with `--dry-run` before deploying it. ## Preview an OIWAP [#preview-an-oiwap] ```bash mlab strategy run oiwap BTC \ --venue bulkf \ --side buy \ --margin 100 \ --leverage 10 \ --duration 3600 \ --oi-sources binancef@mmt,hyperliquidf@mmt \ --dry-run ``` The dry run fetches completed one-minute MMT open-interest history and execution-venue volume history, constructs the requested UTC execution window, estimates the required venue participation rate, and submits nothing. OIWAP intentionally has no `--interval`. The worker reacts to live OI activity, execution-venue trades, order-book changes, fills, trajectory drift, stale maker orders, and the remaining time. ## Open-Interest Sources [#open-interest-sources] `--oi-sources` is required and accepts a comma-separated list of MMT futures or perpetual exchanges: ```txt binancef@mmt,bybitf@mmt,hyperliquidf@mmt ``` Every selector must use `exchange@mmt`. A direct selector such as `binancef` is rejected until Market Lab has a standalone normalized historical-OI adapter for that exchange. Each selected exchange must: * be classified as futures or perpetuals rather than spot * contain the requested symbol in the installed MMT market snapshot * appear only once in the source list Refresh a snapshot before retrying a newly listed market: ```bash mlab markets --provider mmt --exchange binancef --refresh ``` The OI sources determine the trajectory only. They do not change the execution venue and they do not grant permission to consume its orderbook. ## Trajectory Construction [#trajectory-construction] Market Lab uses completed one-minute MMT open-interest candles from the previous 28 days. For every exchange and minute, it calculates: ```txt OI activity = abs(close OI - open OI) ``` The absolute change is calculated before exchanges are combined. This matters because a decrease on one exchange must not cancel an increase on another exchange. Both are evidence of open-interest activity. Market Lab then: 1. Sums the normalized per-exchange OI activity for each minute. 2. Groups matching UTC minutes of day across the historical period. 3. Averages the activity observed in each minute slot. 4. Proportionally includes partial first and final minutes in the requested window. 5. Normalizes the window into a cumulative OI-activity trajectory. MMT normalizes the source data before Market Lab combines it. OIWAP therefore does not mix raw venue-specific OI units. ## Live OI Progress [#live-oi-progress] The selected MMT sources remain connected after the historical curve is built. Live one-minute OI candle updates from those same exchanges drive actual trajectory progress: ```txt target size = parent size × actual OI activity / (actual OI activity + forecast remaining OI activity) ``` Higher-than-expected live OI activity pulls execution forward. Lower activity slows it down. The target reaches the complete parent size at the deadline. The incomplete minute in progress when the job starts is omitted. Counting begins at the next clean one-minute boundary. Updates to a still-forming candle revise that minute's activity instead of being added repeatedly. If an MMT OI source disconnects, the job records `strategy.market_data.degraded` and substitutes forecast progress instead of treating the missing source as zero activity. ## Directional Side Advisory [#directional-side-advisory] The OIWAP plan includes an informational side check using the previous 15 completed one-minute intervals. It compares execution-venue price movement with signed OI movement across the selected MMT sources: | Price | Open interest | Reported regime | Bias | | ----- | ------------- | --------------------------------------- | ------ | | Up | Up | upward position expansion | `buy` | | Down | Up | downward position expansion | `sell` | | Up | Down | short covering or deleveraging | `buy` | | Down | Down | long unwinding or possible liquidations | `sell` | Price or aggregate OI changes smaller than `0.05%` are treated as noise and produce a neutral bias. Source agreement reports how many selected exchanges share the aggregate OI direction. Expansion with complete source agreement receives moderate confidence; disagreement and falling-OI regimes remain low confidence. The plan compares this bias with the supplied side and reports `aligned`, `countertrend`, or `neutral`: ```txt context window: 15m price change: +1.84% OI change: +3.12% source agreement: 2/2 market regime: upward position expansion directional bias: buy requested side: sell (countertrend) bias confidence: moderate advisory: requested sell is countertrend to the current price/OI context; this is advisory and does not block submission ``` This check never changes the supplied side, rejects the plan, or adds another confirmation. OIWAP remains an execution strategy. Falling OI can result from voluntary position closure, so liquidation wording is deliberately presented only as a possibility. If recent price or OI data is incomplete, the plan reports the advisory as unavailable and continues normal feasibility validation. ### Why Direct Venue OI Is Not Included [#why-direct-venue-oi-is-not-included] Direct execution-venue OI is deliberately excluded from live OIWAP progress. The forecast is constructed from the selected MMT exchanges' historical OI, so the live numerator must use those same sources and units. Adding BULK or Hyperliquid only to live progress would compare a different market set against the historical forecast and distort the trajectory. The selected venue still participates fully in execution: its trades create participation capacity, its orderbook limits taker depth, and its fills determine completed quantity. A venue can appear separately as an MMT trajectory source, such as `hyperliquidf@mmt`, without mixing direct venue OI into the calculation. ## Execution-Venue Capacity [#execution-venue-capacity] Open-interest activity controls desired pacing; it never directly determines a child order's executable size. Market Lab maintains a separate cumulative participation ledger from execution-venue trades observed after startup: ```txt trajectory deficit = max(0, trajectory target - filled - working) available venue capacity = max( 0, cumulative participation credit - filled - working ) ``` The required starting participation rate is derived from the parent size and forecast execution-venue volume. Urgency can raise the rate when the strategy falls behind, but it cannot exceed the hard 10% participation cap. Passive maker sizing may use a small amount of forecast venue volume so an order can rest before the next trade. Taker sizing uses only participation credit earned from actual venue trades. The dry-run plan reports forecast OI activity, forecast execution volume, required and maximum participation, forecast capacity, expected shortfall, and feasibility. An infeasible dry run still prints the estimate; live deployment is rejected until the amount is reduced or the duration is increased. ## Maker-First Execution [#maker-first-execution] OIWAP reuses Market Lab's weighted-execution controller: * near the trajectory, it maintains an ALO post-only order at the passive touch * while ahead, it cancels its working maker and waits * when the touch or required amount changes materially, it cancels and replaces its own order * when sufficiently behind, it submits a participation- and depth-bounded market child * urgency increases with deficit and as the deadline approaches * at the deadline, it cancels the maker and handles only the remainder allowed by earned participation and guarded depth Market children are limited by the cumulative 10% venue participation cap and displayed opposing depth within 20 basis points of the best price. If the remaining amount cannot execute inside both guards, the job fails rather than silently consuming more liquidity. All submit and cancel requests are job-owned and idempotent inside `mlabd`. An OIWAP worker cannot cancel an order created by another job or by the user. ## Arguments [#arguments] | Argument | Required | Meaning | | --------------- | ---------- | ------------------------------------------------------------- | | `SYMBOL` | Yes | Market Lab symbol such as `BTC` or `xyz:TSLA` | | `--venue` | No | `bulkf`, `hyperliquidf`, or `hyperlinkf` | | `--testnet` | No | Use BULK or Hyperliquid testnet; not valid with `hyperlinkf` | | `--side` | Yes | Parent side: `buy` or `sell` | | `--size` | One amount | Exact total base-asset size | | `--margin` | One amount | Quote collateral; multiplied by leverage before size flooring | | `--duration` | Yes | Execution window in seconds; minimum `60` | | `--oi-sources` | Yes | Comma-separated `exchange@mmt` futures or perpetual selectors | | `--leverage` | No | Leverage attached to every child; defaults to `1` | | `--reduce-only` | No | Marks every child as reduce-only | | `--dry-run` | No | Build and print the plan without creating a job | | `--yes` | No | Skip live terminal confirmation | | `--output` | No | `terminal`, `json`, or `jsonl` | Set exactly one of `--size` or `--margin`. ## Deploy and Monitor [#deploy-and-monitor] Remove `--dry-run` to deploy the detached worker: ```bash mlab strategy run oiwap BTC \ --venue bulkf \ --side buy \ --margin 100 \ --duration 3600 \ --oi-sources binancef@mmt,hyperliquidf@mmt ``` The CLI prints the job ID and returns control to the terminal. Monitor or stop it with the shared strategy commands: ```bash mlab strategy jobs mlab strategy status mlab strategy logs --follow mlab strategy stop ``` Logs identify the trajectory metric as `absolute_open_interest_change` and include live OI activity, execution-venue volume, active participation rate, participation credit, child orders, fill progress, degraded-data notices, and the final fill VWAP and arrival-price slippage. Stopping cancels the strategy's current maker order and prevents further children. It does not reverse fills or close the resulting position.