> For the complete documentation index, see [llms.txt](https://docs.dimes.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dimes.fi/positions/position-lifecycle.md). # Position Lifecycle This section describes how a leveraged prediction market position moves from creation to settlement. All user actions occur through the originating front-end. Dimes executes and maintains the underlying hedge through Multiply. {% stepper %} {% step %} **Opening a Position** The user selects: * a supported prediction market * a direction (YES or NO) * a leverage level {% endstep %} {% step %} **The terminal requests a quote from Multiply, passing information such as:** * market and trader * direction * requested leverage * notional demand and collateral value {% endstep %} {% step %} **Multiply evaluates:** * current venue price and market microstructure * hedgeability of requested size within slippage bounds * required collateral and margin * per-market, per-side, and per-user cap headroom {% endstep %} {% step %} **Multiply returns a firm executable quote that includes:** * entry price and execution cost * required collateral * maximum allowed size (if clipped by caps or depth) * implied liquidation price * an expiry timestamp — the offer is only valid for a limited window. The `expires_at` field in the API response indicates the deadline. If the user does not execute before this time, the offer becomes invalid and a new quote must be requested. {% endstep %} {% step %} **Hedge-first execution** If the user accepts, the front-end submits an execute call. Multiply executes the hedge on the external venue first. * Only if the hedge fills within slippage bounds is the position created, user collateral is locked, and the leveraged exposure is established. * If the hedge fails or slippage exceeds bounds, the order is rejected and no position is created. After the hedge fills, the position payload exposes both the indicative entry price quoted on the offer (`entry.price_*`) and the actual fill price reported by the venue ( `entry.effective_entry_price_*`). The difference is reported as `entry.effective_slippage_bps` — signed basis points, positive when the fill came in worse than the quote and negative when better. These three fields are `null` until the onchain fill is recorded. {% endstep %} {% step %} **Active monitoring** The position becomes active and appears in the front-end's portfolio view. Once active: * Multiply monitors margin, venue health, and eligibility continuously * Limits and maximum leverage evolve dynamically based on market conditions * The market may enter close-only if any eligibility threshold is breached {% endstep %} {% step %} [**Leverage decay (J-factor)**](/leverage-and-risk/leverage-decay-j-factor.md) * J-factor is Multiply's dynamic risk engine. It continuously monitors depth profile, odds dynamics, open interest microstructure, and resolution conditions, defining when leverage should be reduced. * Leverage reduction is triggered only when microstructure conditions warrant it. On the winning side, this means leverage often remains intact through resolution. On the losing side, deteriorating microstructure typically triggers deleverage earlier, protecting both the user and the facility. * Each unwind in a position's history (via `expand=unwinds`) carries a `reason` — the specific microstructure signal that drove that deleverage, such as `spread_blowout`, `depth_decay`, or `price_drop_severe`. It is `null` for unwinds not driven by the risk engine (e.g. manual admin deleveraging). See the API reference for the full list of reasons. {% endstep %} {% step %} **Liquidation** **(if triggered)** * Multiply is designed to keep your position alive. The J-factor risk engine works continuously to ease your leverage down as a position deteriorates, giving your collateral room to recover before hard limits are reached. As such, forced liquidations are rare. But the system can't guard against every market move. If your remaining collateral falls to maintenance margin at any point during the position lifecycle, Multiply liquidates to protect what's left: the hedge is unwound on the originating venue and all execution costs are deducted from your collateral. {% endstep %} {% step %} **Voided markets** * Occasionally a market is voided — cancelled, forfeited, or closed with no winner (e.g. rescheduled sporting events). When this happens, both YES and NO tokens pay out at $0.50 each via the Conditional Token Framework. The position's mark price updates to $0.50 immediately. The `timing.is_voided` field on the position becomes `true`, and `timing.is_settlement_pending` indicates that settlement is incoming. PnL is calculated against the trading venue refund. {% endstep %} {% endstepper %} ## Entry vs exit notional A closed position reports two notional figures so you can show the round trip. `entry.notional_usd` is the levered exposure the position opened with (entry shares × entry price). `result.exit_notional_usd` is the volume-weighted notional realized as the position wound down — the sum of shares sold × fill price across every force-unwind plus the final close. Because positions are partially deleveraged over their lifetime at different prices, this is not a single exit price; it is the aggregate of all exit fills. It is distinct from `result.proceeds_usd`, which is the de-levered cash equity returned to the wallet after repaying the loan and fees. Exit notional is `null` for `reverted` and `cancelled` positions, where no shares were ever sold. ## On-chain transaction visibility Every on-chain step above — opening, finalizing, closing, liquidating, settling, force-unwinding, and redeeming — is recorded as a transaction the position owner can inspect. The [position transactions endpoint](/for-developers/api-and-events/api-reference.md#position-transactions-sub-resource) returns these transactions grouped by operation type, including the on-chain hashes of the nested exchange (CLOB/DEX) fills that hedge the position. Only transactions that landed and finalized on-chain are returned — pending, failed, and reverted attempts are excluded — so the result reflects the transfers that actually moved funds. ## Reverted opens If an open fails after the on-chain position is created — most often because the hedging exchange order could not be filled — the protocol reverts the open and returns the collateral and origination fee in full. No position is held. The closed-position response carries `close_reason: "reverted"` and a `revert_reason` enum explaining why: * `exchange_unavailable` — the prediction-market venue was temporarily unavailable (e.g. its matching engine was restarting). This is transient; submitting the same offer again shortly after will usually succeed. * `slippage_exceeded` — the price moved beyond the offer's slippage tolerance before the order could fill. Re-quote and retry. * `unknown` — the revert could not be attributed to a specific cause. `revert_reason` is null for any non-reverted close. ## Deferred closes If you request a close but the market resolves before the remaining shares can be sold on the order book, the close cannot complete as a normal sale. Rather than fail the request, the protocol defers it: the remaining tokens are redeemed when the market settles instead of being sold. While this is pending, the position stays `open` and carries a `close_attempt` object describing the deferral: * `outcome: "deferred"` — the close was postponed rather than completed. * `reason: "awaiting_settlement"` — the market resolved before the position could be sold, so the remaining tokens will be redeemed at settlement. * `deferred_at` — ISO-8601 timestamp of when the close was requested. `close_attempt` is `null` for any open position without a deferred close. When the market settles, the position transitions to a closed/settled state in the usual way and the redeemed proceeds are reported under `result`.