> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nilemarkets.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How Nile Markets Works

> Four-step trading flow: deposit USDC margin, open a forward position at oracle-driven strike price, track real-time PnL, and settle at maturity fixing price — pool serves as sole counterparty.

The Nile Markets protocol enables traders to take leveraged positions on future EUR/USD exchange rates.
A shared USDC liquidity pool acts as the counterparty to every trade. This page walks through the core
mechanics — from opening a position to final settlement.

## The Core Loop

<Steps>
  <Step title="LPs deposit USDC into the vault">
    A liquidity provider deposits USDC into the pool. The vault mints share tokens proportional to the
    current share price, representing the LP's ownership of the pool. The deposited USDC becomes
    available as counterparty capital for trader positions.
  </Step>

  <Step title="Trader deposits collateral">
    A trader adds USDC to their margin account. This collateral backs their positions but is not yet
    locked — it sits as free balance until a position is opened.
  </Step>

  <Step title="Trader opens a position">
    The trader specifies:

    * **Side**: LONG (betting EUR/USD goes up) or SHORT (betting it goes down)
    * **Tenor**: 1 Day, 1 Week, or 1 Month
    * **Notional**: The face value of the contract in USDC
    * **Margin**: The amount of collateral to lock (must be at least 2% of notional)

    The protocol locks the trader's margin, records the position, and charges an opening trading fee.
  </Step>

  <Step title="Entry price is locked">
    At the moment of opening, the protocol fetches the current forward price for the position's
    maturity date. This becomes the **entry strike** — the reference price against which all PnL is
    calculated. The entry strike never changes.
  </Step>

  <Step title="Position is live — PnL moves with the market">
    While the position is open, unrealized PnL fluctuates as the forward price changes. During this
    period, the trader can:

    * Add margin to reduce liquidation risk
    * Remove excess margin to free collateral
    * Partially reduce the position
    * Close the position early at the current forward price
  </Step>

  <Step title="Liquidation guard">
    If a position's equity (locked margin + unrealized PnL) drops below the **maintenance margin**
    threshold (1% of notional), the position becomes liquidatable. Anyone can trigger the liquidation,
    with a penalty deducted from the trader's remaining margin.
  </Step>

  <Step title="Maturity settlement">
    When the maturity date arrives, the position settles. The **fixing price** — the Pyth EUR/USD spot
    price recorded at 4 PM UTC on the maturity business day — determines the final PnL.
  </Step>

  <Step title="PnL settlement">
    Final PnL is calculated and settled:

    * **Trader wins**: Profit is transferred from the pool to the trader's margin account
    * **Trader loses**: Loss is deducted from locked margin and credited to the pool
    * **Bad debt**: If loss exceeds locked margin, the excess is absorbed by pool equity
  </Step>
</Steps>

## Zero-Sum Dynamics

The protocol creates no value and destroys no value in trading itself. Every unit of USDC that flows
to a trader as profit is drawn from the pool, and every unit lost by a trader flows into the pool.

```
Trader PnL + Pool PnL = 0   (excluding fees)
```

Fees are the only extraction from the system. They are charged on position open, close, and
settlement, and split between the pool (70%) and the protocol treasury (30%). This means the pool has
a structural edge: even if trader wins and losses perfectly balance, the pool accumulates fee revenue.

<Info>
  The zero-sum property is enforced as an onchain invariant. The sum of all trader PnL plus pool PnL
  equals zero at all times.
</Info>

## Forward Pricing

Forward prices are the core pricing mechanism. Unlike spot prices that reflect current exchange rates,
forward prices project the rate at a specific future date by incorporating the interest rate
differential between EUR and USD. See [Oracle & Forward Pricing](/protocol/oracle-pricing) for the
full formula and parameter details.

<Tip>
  The forward rate represents the annualized interest rate differential between EUR and USD. A
  positive rate means the forward price is above spot (USD rates higher than EUR rates), which is the
  typical market condition.
</Tip>

## Margin Model

The protocol uses **isolated margin** — each position has its own independent margin that does not
interact with other positions or free collateral.

<AccordionGroup>
  <Accordion title="Initial Margin (IM)">
    The minimum collateral required to open a position: **2% of notional** by default (50x max
    leverage). Traders can choose to lock more margin, reducing their leverage and liquidation risk.
  </Accordion>

  <Accordion title="Maintenance Margin (MM)">
    The minimum equity threshold below which a position becomes liquidatable: **1% of notional** by
    default. If position equity drops below this level, anyone can liquidate it.
  </Accordion>

  <Accordion title="Equity and Liquidation">
    Position equity = locked margin + unrealized PnL. A position is healthy when equity >= MM, and
    liquidatable when equity \< MM.

    Example: A LONG position with 200 USDC margin and -110 USDC unrealized PnL has equity of 90 USDC.
    If maintenance margin is 100 USDC, this position is liquidatable (90 \< 100).
  </Accordion>

  <Accordion title="Variable Leverage">
    | Margin             | Notional    | Leverage | Liquidation Distance |
    | ------------------ | ----------- | -------- | -------------------- |
    | 200 USDC (2%)      | 10,000 USDC | 50x      | \~1% price move      |
    | 500 USDC (5%)      | 10,000 USDC | 20x      | \~4% price move      |
    | 2,000 USDC (20%)   | 10,000 USDC | 5x       | \~19% price move     |
    | 10,000 USDC (100%) | 10,000 USDC | 1x       | Cannot be liquidated |
  </Accordion>
</AccordionGroup>

## Settlement

A position can close in four ways:

<Tabs>
  <Tab title="Maturity">
    **When**: The maturity date has passed and a fixing price has been recorded.

    **Price used**: The fixing price — Pyth EUR/USD spot at 4 PM UTC on the maturity business day.

    **Fee**: Standard trading fee (0.05% of notional).
  </Tab>

  <Tab title="Early Termination">
    **When**: The trader chooses to close before maturity.

    **Price used**: The current forward price for the position's maturity date.

    **Fee**: Standard trading fee plus oracle fee for the price lookup.
  </Tab>

  <Tab title="Liquidation">
    **When**: Position equity drops below the maintenance margin threshold.

    **Price used**: The current forward price.

    **Fee**: Trading fee plus liquidation penalty (0.30% of notional).
  </Tab>

  <Tab title="Partial Reduction">
    **When**: The trader wants to reduce exposure without fully closing.

    **Price used**: The current forward price.

    **Effect**: Notional is reduced, proportional PnL is settled immediately. The position stays open
    with reduced notional and margin. Entry strike does not change.
  </Tab>
</Tabs>

<Note>
  Fixing timestamps are business-day adjusted. If a position's theoretical maturity falls on a weekend,
  the fixing timestamp is rolled forward to the next Monday at 4 PM UTC.
</Note>

## Next Steps

<Columns cols={3}>
  <Card title="Quick Start" icon="rocket" href="/build/quick-start">
    Set up your environment and query the protocol on Sepolia in 15 minutes.
  </Card>

  <Card title="Core Concepts" icon="book" href="/nile-markets/ndf-fx-forwards">
    Deep dive into non-deliverable forwards, tenors, sides, margin, and protocol modes.
  </Card>

  <Card title="Position Lifecycle" icon="arrows-spin" href="/protocol/position-lifecycle">
    Detailed walkthrough of every state transition from open to close.
  </Card>
</Columns>