| name | limit-offset-bps-calculation |
| description | Use when placing any post-only limit order on HyperLiquid to calculate the optimal price offset from mid that maximizes fill probability while preserving maker status, accounting for spread, volatility, book depth, and asset tick size. |
| category | agentic |
Limit Order Offset (BPS) Calculation
When This Skill Activates
Apply this skill every time an Alo (post-only) limit order price must
be determined before submission. The skill answers: how many basis
points inside or outside the spread should the limit price be placed?
Also apply when:
- An
Alo order was rejected (price crossed spread) and a new offset
must be computed before reposting
- Fill rate on resting limit orders is unacceptably low and offset
calibration needs review
- A new asset is being traded for the first time and no historical
offset data exists yet
- Spread has widened significantly (low liquidity period, news event)
and the standard offset is stale
Core Principle
A post-only limit order placed too far from mid rests on the book
for a long time and may never fill — opportunity cost. Placed too
close to mid it risks crossing the spread on a momentary tick and
being rejected as a taker (or, with Gtc, accidentally paying taker
fee). The optimal offset is the minimum distance from mid that reliably
lands inside the book as a resting maker order given current spread and
volatility, without being so far away that fill probability collapses.
Rule: Place limit orders at mid ± offset_bps where offset_bps
is computed fresh from live spread and recent volatility at the time
of each order. Never use a hardcoded static offset across all market
conditions.
Inputs Required
Fetch all of the following from HyperLiquid before computing offset:
best_bid = l2book["levels"][0][0]["px"]
best_ask = l2book["levels"][1][0]["px"]
mid_price = (best_bid + best_ask) / 2
raw_spread_bps = (best_ask - best_bid) / mid_price * 10000
mark_price = asset_ctx["markPrice"]
tick_size = asset_meta["szDecimals"]
import statistics
trade_prices = [t["px"] for t in recent_trades]
volatility_bps = statistics.stdev(trade_prices) / mid_price * 10000
Offset Calculation
Base Offset Formula
def compute_limit_offset_bps(
raw_spread_bps: float,
volatility_bps: float,
side: str,
order_urgency: str = "normal",
book_fragility: float = 0.0,
) -> float:
"""
Returns the offset in basis points from mid.
Positive offset = deeper into the book (better fill safety, worse fill rate).
"""
half_spread_bps = raw_spread_bps / 2
safety_buffer_bps = max(0.5, half_spread_bps * 0.10)
vol_buffer_bps = volatility_bps * 0.20
base_offset = half_spread_bps + safety_buffer_bps + vol_buffer_bps
urgency_multiplier = {
"urgent": 0.5,
"normal": 1.0,
"patient": 1.5,
}[order_urgency]
fragility_multiplier = + (book_fragility * )
offset_bps = base_offset * urgency_multiplier * fragility_multiplier
(, (, offset_bps))
Applying Offset to Order Price
def compute_limit_price(
mid_price: float,
offset_bps: float,
side: str,
tick_size_decimals: int,
) -> float:
"""
Buy orders: place BELOW mid (offset into bid side)
Sell orders: place ABOVE mid (offset into ask side)
Round to asset tick size to avoid rejection for invalid price precision.
"""
offset_price = mid_price * (offset_bps / 10000)
if side == "buy":
raw_price = mid_price - offset_price
else:
raw_price = mid_price + offset_price
factor = 10 ** tick_size_decimals
if side == "buy":
return math.floor(raw_price * factor) / factor
else:
return math.ceil(raw_price * factor) / factor
Offset Calibration by Market Condition
Spread Regime Classification
Classify current spread before applying offset to set urgency defaults:
| Spread (bps) | Regime | Suggested Urgency | Notes |
|---|
| < 1.0 | Tight | normal | Liquid; standard offset works well |
| 1.0–2.5 | Normal | normal | Typical for mid-cap perps |
| 2.5–5.0 | Wide | patient | Low liquidity; widen offset or wait |
| 5.0–10.0 | Very wide | patient + size reduction | Consider deferring non-urgent entries |
| > 10.0 | Illiquid | Defer or use Ioc taker if urgent | Maker fill unlikely at reasonable offset |
When spread > 10 bps and the entry is time-critical, the cost of
waiting for a maker fill (missing the move) may exceed taker fee.
Defer to maker-order-preference-fee-reduction for the explicit
taker-vs-maker decision; this skill only handles the offset calculation
for the maker path.
Volatility Regime Adjustment
| 5m Volatility (bps) | Vol Regime | vol_buffer_bps | Effect on Offset |
|---|
| < 2 | Low vol | 0.4 | Offset stays near minimum |
| 2–5 | Normal vol | 0.4–1.0 | Standard offset range |
| 5–10 | Elevated vol | 1.0–2.0 | Offset widens meaningfully |
| 10–20 | High vol | 2.0–4.0 | Approach upper clamp; consider patient |
| > 20 | Extreme vol | Clamp at 5.0 | Near-cascade conditions; see liquidation-cascade-risk |
Asset-Specific Tick Size Reference
HyperLiquid enforces strict price precision per asset. Submitting an
order with more decimal places than allowed causes immediate rejection.
asset_tick_map = {
asset["name"]: asset["szDecimals"]
for asset in meta["universe"]
}
The compute_limit_price() function above handles rounding automatically
when tick_size_decimals is passed correctly. Always fetch tick size
from live meta, never hardcode it.
Worked Examples
Example 1 — BTC, Normal Conditions
Inputs:
mid_price = 91,500.00
best_bid = 91,494.00
best_ask = 91,506.00
raw_spread_bps = 12 / 91,500 * 10,000 = 1.31 bps
volatility_bps = 3.2 bps (last 5m trades)
side = "buy"
urgency = "normal"
book_fragility = 0.10
Calculation:
half_spread = 0.655 bps
safety_buffer = max(0.5, 0.655 * 0.10) = 0.50 bps
vol_buffer = 3.2 * 0.20 = 0.64 bps
base_offset = 0.655 + 0.50 + 0.64 = 1.795 bps
urgency_mult = 1.0
fragility_mult = 1.0 + (0.10 * 0.5) = 1.05
offset_bps = 1.795 * 1.0 * 1.05 = 1.885 bps → clamped to range: 1.885
Limit price:
offset_price = 91,500 * (1.885 / 10,000) = 1.725
raw_price = 91,500 - 1.725 = 91,498.275
tick_size = 1 decimal → floor to 91,498.2
Order submitted: BUY limit 91,498.2 (Alo, tif="Alo")
Example 2 — ETH, Elevated Volatility
Inputs:
mid_price = 1,792.00
raw_spread_bps = 2.80 bps
volatility_bps = 8.5 bps (elevated; approaching news event)
side = "sell" (TP exit)
urgency = "patient"
book_fragility = 0.25
Calculation:
half_spread = 1.40 bps
safety_buffer = max(0.5, 1.40 * 0.10) = 0.50 bps
vol_buffer = 8.5 * 0.20 = 1.70 bps
base_offset = 1.40 + 0.50 + 1.70 = 3.60 bps
urgency_mult = 1.5 (patient)
fragility_mult = 1.0 + (0.25 * 0.5) = 1.125
offset_bps = 3.60 * 1.5 * 1.125 = 6.075 bps → clamped to 5.0 bps
Limit price:
offset_price = 1,792 * (5.0 / 10,000) = 0.896
raw_price = 1,792 + 0.896 = 1,792.896
tick_size = 2 decimals → ceil to 1,792.90
Order submitted: SELL limit 1,792.90 (Alo, tif="Alo")
Fill Rate Monitoring and Self-Calibration
MetaClaw’s skills auto-evolve from deployment experience. To enable
this skill to improve its offset calibration over time, log sufficient
data for the RL replay buffer:
{
"event": "limit_order_offset_calc",
"asset": "BTC",
"timestamp_utc": "2026-04-07T22:00:00Z",
"side": "buy",
"mid_price": 91500.00,
"raw_spread_bps": 1.31,
"volatility_bps_5m": 3.2,
"book_fragility": 0.10,
"urgency": "normal",
"offset_bps_computed": 1.885,
"limit_price": 91498.2,
"order_result": "filled",
"fill_latency_seconds": 14.3,
"fill_price"
Fill Rate Thresholds for Recalibration
If the rolling 50-order fill rate for a given asset falls outside the
acceptable range, recalibrate the offset multipliers:
| Fill Rate | Diagnosis | Recalibration Action |
|---|
| > 95% | Offset too deep | Reduce urgency_multiplier by 0.1; or reduce safety_buffer |
| 80–95% | Optimal range | No change |
| 60–80% | Offset borderline | Review spread regime; check for persistent wide spread |
| < 60% | Offset too tight | Increase vol_buffer coefficient (0.20 → 0.25); or switch urgency to patient |
| High rejection rate | Alo crossing spread | Increase safety_buffer to 1.0 bps; review mid-price staleness |
Failure Modes to Avoid
- Using a static offset across all assets and conditions: BTC at
1 bps spread needs a different offset than DOGE at 8 bps spread.
Offset must be computed per-asset per-order from live data.
- Anchoring to
mid_price from a stale snapshot: Mid-price from
the last REST poll may be 200–500ms old on a fast market. Use the
WebSocket l2Book subscription for real-time mid when placing orders
in volatile conditions (volatility_bps > 5).
- Ignoring tick size rounding direction: Rounding a buy limit price
up instead of down can push it above best ask, crossing the spread
and triggering
Alo rejection. Always floor buy prices and ceil sell
prices after offset application.
- Applying the upper clamp (5.0 bps) as a routine offset: The 5.0 bps
clamp is a safety ceiling, not a target. Consistently hitting the clamp
means market conditions are too volatile or illiquid for maker execution;
the correct response is to defer the order, not to accept a 5 bps
penalty as standard.
- Not refreshing offset on order re-queue: If an
Alo order expires
or is cancelled and must be reposted, recompute the offset from fresh
data. Market conditions at repost time may be materially different
from the original placement.
- Conflating offset with slippage: Offset is the deliberate distance
placed into the book on the maker side. Slippage is unintended price
deviation on taker fills. They are separate quantities; do not use
slippage tolerance parameters to govern maker order offsets.
Integration with Other Skills
maker-order-preference-fee-reduction (execution/): Run first to
decide whether to use Alo. This skill runs second to decide where
to place the Alo order. They are always used together.slippage-budget-enforcement (execution/): For taker orders, that
skill governs the price tolerance. This skill is maker-path only.liquidation-cascade-risk (regime-detection/): Passes
book_fragility score as an input to this skill’s offset formula.
Higher fragility → wider offset → less chance of Alo rejection
from a volatile book.trending-bull-entry-timing (regime-detection/): Provides
the Fibonacci target price as the anchor for the offset calculation.
This skill computes the final submitted price around that anchor.
Quick Decision Tree
Need to place an Alo limit order — what price?
│
├── 1. Fetch live l2Book → best_bid, best_ask, mid_price
├── 2. Compute raw_spread_bps and volatility_bps (last 5m trades)
├── 3. Get book_fragility from liquidation-cascade-risk if available
├── 4. Classify spread regime (tight / normal / wide / illiquid)
│ └── Illiquid (> 10 bps)? → Defer or escalate to taker decision
├── 5. Set urgency: normal (default) / patient (wide spread or low urgency)
├── 6. Run compute_limit_offset_bps() → offset_bps
├── 7. Run compute_limit_price() with tick_size from live meta → limit_price
├── 8. Submit order with tif="Alo" at computed limit_price
│
├── Alo FILLS → log event with fill_latency. Done.
├── Alo REJECTS → price moved. Recompute offset from fresh data. Reassess entry.
└── Alo EXPIRES (GTC timeout) → Recompute. Re-evaluate setup validity.
