> ## 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.

# What is Nile Markets?

> FX, non-deliverable forward (NDF) trading on Ethereum with fixed maturity dates

Nile Markets is an onchain protocol for trading currency markets through dated FX derivatives.
It provides open access to global currency markets by allowing users to take positions on exchange rates between any supported currencies, with trades settled in stablecoins and priced using oracle-derived forward rates.

Unlike traditional FX infrastructure, which is fragmented across banks, brokers, and trading venues, Nile Markets creates a single onchain liquidity pool that acts as the central counterparty to all trades. This enables transparent pricing, continuous liquidity, and programmable financial products built on top of currency markets.

<Note>
  The protocol is deployed on Ethereum Sepolia testnet (M2 milestone). All tokens are test tokens with
  no monetary value. Do not use real funds.
</Note>

## A global market, open onchain

Foreign exchange is the largest financial market in the world, with over \$7 trillion traded daily, yet access remains limited and infrastructure largely unchanged for decades. Nile Markets brings FX trading onchain:

<Columns cols={2}>
  <Card title="Open participation" icon="globe">
    Anyone can take positions on global currency pairs
  </Card>

  <Card title="Programmable hedging" icon="code-branch">
    Smart-contract strategies for treasury and risk
  </Card>

  <Card title="Continuous liquidity" icon="droplet">
    Shared pool acts as counterparty to every trade
  </Card>

  <Card title="Automated settlement" icon="bolt">
    Positions settle onchain at maturity, no intermediary
  </Card>
</Columns>

Nile Markets is designed as a universal framework for trading global currency pairs, and more.

## Dated FX markets

Most crypto derivatives rely on perpetual futures. Nile Markets instead focuses on dated markets, where positions have a fixed maturity. Each market represents a forward contract on a currency pair, allowing users to lock in an exchange rate for settlement at a future date.

<AccordionGroup>
  <Accordion title="Currency hedging">
    Lock in a future rate to protect revenue or liabilities denominated in a foreign currency.
  </Accordion>

  <Accordion title="Interest-rate-differential yield">
    Capture the carry between two currencies by holding a forward to maturity.
  </Accordion>

  <Accordion title="Structured products">
    Build bespoke payoffs by combining forwards with other onchain primitives.
  </Accordion>

  <Accordion title="Programmable treasury">
    Automate FX exposure management via scheduled or rule-based contract calls.
  </Accordion>
</AccordionGroup>

For a detailed comparison with perpetual futures, see [Forwards vs Perpetuals](/nile-markets/forwards-vs-perpetuals).

## Pooled liquidity and clearing mechanics

All trades interact with a shared liquidity pool that acts as the protocol’s central counterparty. This architecture differs from order book exchanges where traders match directly with each other.

<Steps>
  <Step title="Trader takes a side">
    Positions open against the pool, which is always the counterparty.
  </Step>

  <Step title="Pool prices respond to exposure">
    Forward quotes skew based on net pool exposure and tenor.
  </Step>

  <Step title="Spreads rebalance the book">
    Tighter pricing attracts offsetting flow, wider pricing deters further concentration.
  </Step>

  <Step title="Settlement against pool collateral">
    Profits paid from pool equity; losses accrue to pool equity.
  </Step>
</Steps>

This clearing-style market design allows Nile Markets to provide continuous liquidity while automatically managing exposure through pricing adjustments and margin requirements.

## Programmable currency markets

Because markets live onchain, Nile Markets can serve as infrastructure for a new generation of financial applications — automated treasury hedging, structured yield vaults, currency-hedged investment products, and programmable FX strategies. By combining global currency markets with smart contracts, Nile Markets aims to make FX trading open, programmable, and accessible to anyone.

## Key Features

<Columns cols={2}>
  <Card title="Non-Deliverable Forwards" icon="chart-line">
    Trade FX forward contracts on any supported currency pair, with multiple maturities: 1-day, 1-week, and 1-month. Positions
    settle at the fixing price for the traded currency pair on the maturity date -- no physical currency delivery required.
  </Card>

  <Card title="Zero-Sum Pool Model" icon="scale-balanced">
    Liquidity providers deposit USDC into an ERC-4626 vault that serves as the counterparty to every
    trade. When traders profit, the pool pays. When traders lose, the pool gains. Fees are extracted
    separately on every open, close, and settlement.
  </Card>

  <Card title="Isolated Margin" icon="shield-halved">
    Each position's risk is contained to its own locked margin. A liquidation on one position does not
    affect other positions or free collateral held by the same trader. Bad debt is absorbed by the pool,
    not by other traders.
  </Card>

  <Card title="Permissionless Settlement" icon="gavel">
    Anyone can settle matured positions or liquidate underwater ones. The keeper service automates this,
    but the smart contracts impose no restrictions on who may call settlement or liquidation functions.
  </Card>

  <Card title="Pyth Oracle Integration" icon="satellite-dish">
    Real-time FX spot prices for all supported currency pairs are sourced from Pyth Network. Forward prices are computed off-chain
    using interest-rate parity and published onchain by the authorized publisher service, with
    safeguard checks on price movement, staleness, and deviation.
  </Card>

  <Card title="Multiple Integration Paths" icon="plug">
    Access the protocol via TypeScript SDK, GraphQL subgraph, MCP server, x402 pay-per-call API,
    CLI tool, or direct smart contract interaction. Built for both human developers and AI agents.
  </Card>
</Columns>

## Who Is This For?

<Tabs>
  <Tab title="Traders">
    Speculate on or hedge FX exchange rate movements across any supported currency pair using non-deliverable forward (NDF) contracts. Choose
    your tenor (1D, 1W, 1M), side (LONG or SHORT), and leverage (up to 50x). Positions settle
    automatically at maturity, or you can close early at the current forward price.

    * Open positions with as little as 2% initial margin (default)
    * Monitor real-time PnL as forward prices move
    * Add or remove margin to manage risk
    * Close positions early or let them settle at maturity
  </Tab>

  <Tab title="Liquidity Providers">
    Earn trading fees and liquidation penalties by depositing USDC into the protocol's ERC-4626 vault.
    You receive share tokens representing your proportional ownership of the pool. Share price reflects
    cumulative pool performance -- fees earned minus trader profits paid out.

    * Deposit and withdraw USDC at any time (subject to utilization limits)
    * Track share price and pool equity in real time
    * Diversified exposure across all trader positions
  </Tab>

  <Tab title="Developers">
    Build on the protocol using multiple integration points. Contract source is verified on Etherscan.

    * **TypeScript SDK** — Type-safe ABIs, enums, and constants for browser and Node.js
    * **Rust SDK** — Native Rust bindings for high-performance off-chain services
    * **Subgraph API** — GraphQL interface for historical data, positions, and analytics
    * **CLI Tools** — Command-line interface for all protocol operations
    * **MCP Endpoint** — Model Context Protocol server for AI agent integration
    * **x402 API** — Pay-per-call HTTP API using the x402 payment protocol
    * **Smart Contracts** — Direct ABI interaction with verified Solidity contracts
  </Tab>

  <Tab title="AI Agents">
    Programmatic access designed for autonomous agents and LLM-powered tools. The protocol exposes
    multiple machine-friendly interfaces that require no browser or wallet UI.

    * **MCP Server**: Model Context Protocol server for Claude, Cursor, and other MCP-compatible agents
    * **x402 API**: Pay-per-call HTTP API using the x402 payment protocol -- no API keys needed
    * **CLI Agent Mode**: Structured JSON output for piping into agent workflows
    * **llms.txt**: Machine-readable protocol summary at the documentation root
  </Tab>
</Tabs>

## Current Status

<Warning>
  The Open Nile Protocol is currently at the **M2 (External Testnet)** milestone, deployed
  on Ethereum Sepolia. This is experimental software under active development. Contract addresses,
  parameters, and behaviors may change between deployments. Do not use real funds.
</Warning>

The project follows a milestone-based roadmap:

| Milestone                 | Status      | Description                                             |
| ------------------------- | ----------- | ------------------------------------------------------- |
| M0 (Dev Preview)          | Complete    | Local Anvil chain, mock oracle, manual admin operations |
| M1 (Internal Demo)        | Complete    | Sepolia testnet, Pyth integration, publisher service    |
| **M2 (External Testnet)** | **Current** | Full features, keeper automation, subgraph, SDK         |
| M3 (Mainnet Ready)        | Planned     | Professional audit, formal verification, production ops |

## Next Steps

### By Role

<Tabs>
  <Tab title="Traders">
    <Columns cols={3}>
      <Card title="Non-Deliverable Forwards" icon="chart-line" href="/nile-markets/ndf-fx-forwards">
        What FX forwards are and how they work onchain
      </Card>

      <Card title="Trading Scenarios" icon="lightbulb" href="/nile-markets/trading-scenarios">
        Hedging, speculation, and carry trade examples
      </Card>

      <Card title="Margin Model" icon="shield-halved" href="/protocol/margin-model">
        How margin, leverage, and liquidation work
      </Card>

      <Card title="Forwards vs Perpetuals" icon="scale-balanced" href="/nile-markets/forwards-vs-perpetuals">
        When forwards beat perps
      </Card>

      <Card title="Liquidation" icon="triangle-exclamation" href="/protocol/liquidation">
        How and when positions get liquidated
      </Card>

      <Card title="Fee Structure" icon="receipt" href="/protocol/fees">
        Trading fees, liquidation penalties, oracle fees
      </Card>
    </Columns>
  </Tab>

  <Tab title="Liquidity Providers">
    <Columns cols={3}>
      <Card title="Vault Mechanics" icon="vault" href="/deploy/vault-mechanics">
        ERC-4626 vault mechanics and pool dynamics
      </Card>

      <Card title="LP Risk & Reward" icon="scale-balanced" href="/deploy/lp-risk-reward">
        What LPs earn, what they risk, scenario analysis
      </Card>

      <Card title="Depositing & Withdrawing" icon="money-bill-transfer" href="/deploy/depositing-withdrawing">
        Step-by-step LP operations
      </Card>

      <Card title="Share Price" icon="chart-line" href="/deploy/share-price">
        How share price reflects pool performance
      </Card>

      <Card title="Pool Utilization" icon="gauge-high" href="/deploy/pool-utilization">
        Utilization caps and withdrawal restrictions
      </Card>

      <Card title="Fee Distribution" icon="coins" href="/deploy/fee-distribution">
        How collected fees flow to LPs
      </Card>
    </Columns>
  </Tab>

  <Tab title="Developers">
    <Columns cols={3}>
      <Card title="Quick Start" icon="rocket" href="/build/quick-start">
        From zero to querying Sepolia in 15 minutes
      </Card>

      <Card title="TypeScript SDK" icon="code" href="/build/typescript-sdk">
        Type-safe ABIs, constants, and enums
      </Card>

      <Card title="Open Position Tutorial" icon="play" href="/build/open-position-tutorial">
        End-to-end position opening guide
      </Card>

      <Card title="Subgraph API" icon="database" href="/build/subgraph-overview">
        GraphQL API for historical and analytical data
      </Card>

      <Card title="Smart Contracts" icon="file-contract" href="/nile-markets/architecture">
        Contract architecture and API reference
      </Card>

      <Card title="AI & Agents" icon="robot" href="/ai-agents/overview">
        MCP server, x402 API, CLI agent mode
      </Card>
    </Columns>
  </Tab>
</Tabs>

### Overview

<Columns cols={3}>
  <Card title="How It Works" icon="diagram-project" href="/nile-markets/how-it-works">
    Understand the core trading loop, forward pricing, margin model, and settlement mechanics.
  </Card>

  <Card title="Architecture" icon="sitemap" href="/nile-markets/architecture">
    Three-layer architecture: onchain contracts, off-chain services, and external infrastructure.
  </Card>

  <Card title="Quick Start" icon="rocket" href="/build/quick-start">
    Get from zero to querying the protocol on Sepolia in 15 minutes.
  </Card>
</Columns>