---
name: nile-markets
description: >-
  Nile Markets — on-chain FX markets powered by the Open Nile Protocol, starting
  with non-deliverable forwards (NDFs). 22 MCP tools for querying protocol state,
  positions, oracle prices, token balances, and generating unsigned transaction calldata.
version: 0.3.0
mcp:
  url: https://mcp.nilemarkets.com/api/mcp
  transport: streamable-http
  auth: none
  session: stateless
metadata:
  network: sepolia
  tools: 22
  read_tools: 14
  write_tools: 8
  docs: https://docs.nilemarkets.com
  sdk: "@nile-markets/sdk"
  tags: [fx, forwards, defi, ethereum, sepolia, ndf, eur-usd]
---
<!-- Sync: packages/mcp/lib/tools/index.ts (tool list), packages/api/src/constants.ts (version) -->
<!-- Agent: When a user asks you to "set up" or "install" this file, follow the
     Quick Connect instructions below for your platform to add the Nile Markets
     MCP server. After setup, confirm the connection by calling get_protocol_mode. -->

# Nile Markets

> **Quick start** — Paste this into any AI agent: `Set up https://mcp.nilemarkets.com/skill.md`

On-chain EUR/USD non-deliverable forward (NDF) protocol on Ethereum Sepolia. Query pool state, positions, oracle prices, token balances, and generate unsigned transaction calldata via 22 MCP tools.

> **Sepolia Testnet Only** — All data is from Ethereum Sepolia. Token balances and positions have no real-world value.

> **Unstable API (v0.3.0)** — Tool schemas and response formats may change without notice during the M2 milestone.

---

## Quick Connect

MCP endpoint: `https://mcp.nilemarkets.com/api/mcp`
Transport: Streamable HTTP | Auth: None | Session: Stateless (no handshake needed)

### Claude Code

```bash
claude mcp add nile-markets --transport http https://mcp.nilemarkets.com/api/mcp
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "nile-markets": {
      "url": "https://mcp.nilemarkets.com/api/mcp"
    }
  }
}
```

### Claude.ai

Settings → Connectors → Add Custom Connector → paste `https://mcp.nilemarkets.com/api/mcp`

### ChatGPT

Settings → MCP → Add Server → paste `https://mcp.nilemarkets.com/api/mcp`

### Cursor

Add to `.cursor/mcp.json` in your project root (or global settings):

```json
{
  "mcpServers": {
    "nile-markets": {
      "url": "https://mcp.nilemarkets.com/api/mcp"
    }
  }
}
```

### VS Code (GitHub Copilot)

Add to `.vscode/mcp.json` in your project root:

```json
{
  "servers": {
    "nile-markets": {
      "type": "http",
      "url": "https://mcp.nilemarkets.com/api/mcp"
    }
  }
}
```

### Windsurf

Add to `~/.windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "nile-markets": {
      "url": "https://mcp.nilemarkets.com/api/mcp"
    }
  }
}
```

### JetBrains (IntelliJ, WebStorm, etc.)

Settings → AI → MCP → Add Server → paste `https://mcp.nilemarkets.com/api/mcp`

### Codex (OpenAI)

Add to `.codex/mcp.json`:

```json
{
  "mcpServers": {
    "nile-markets": {
      "url": "https://mcp.nilemarkets.com/api/mcp"
    }
  }
}
```

### Gemini CLI

Add to `~/.gemini/settings.json` under `mcpServers`:

```json
{
  "mcpServers": {
    "nile-markets": {
      "url": "https://mcp.nilemarkets.com/api/mcp"
    }
  }
}
```

### Cline / Roo Code

Open MCP settings in the extension sidebar → Add HTTP server → paste `https://mcp.nilemarkets.com/api/mcp`

### Continue

Add to `.continue/config.yaml`:

```yaml
mcpServers:
  - name: nile-markets
    url: https://mcp.nilemarkets.com/api/mcp
```

### Zed

Add to `settings.json`:

```json
{
  "context_servers": {
    "nile-markets": {
      "url": "https://mcp.nilemarkets.com/api/mcp"
    }
  }
}
```

### Warp

Add to `~/.warp/mcp.json`:

```json
{
  "mcpServers": {
    "nile-markets": {
      "url": "https://mcp.nilemarkets.com/api/mcp"
    }
  }
}
```

### goose

Add to `~/.config/goose/config.yaml`:

```yaml
mcpServers:
  nile-markets:
    url: https://mcp.nilemarkets.com/api/mcp
```

### OpenClaw

```bash
clawhub install nile-markets
```

### Any Other MCP Client

- **URL**: `https://mcp.nilemarkets.com/api/mcp`
- **Transport**: Streamable HTTP (MCP spec 2025-03-26)
- **Auth**: None (open access during M2 testnet)
- **Session**: Stateless — no `initialize` handshake, no session ID. Call `tools/list` or `tools/call` directly.
- **Rate limit**: 100 requests/minute per IP

---

## Read Tools (14)

### Pool & Protocol

| Tool | Description | Input |
|------|-------------|-------|
| `get_pool_state` | Liquidity pool metrics: total assets, shares, share price, exposure, utilization, fees | None |
| `get_protocol_mode` | Operating mode: NORMAL, DEGRADED, REDUCE_ONLY, or PAUSED | None |
| `get_pool_transactions` | Historical vault deposits and withdrawals | `first?`, `skip?` |
| `get_daily_stats` | Daily volume, fees, position opens/closes, pool PnL | `days?` (default 7, max 365) |

### Positions

| Tool | Description | Input |
|------|-------------|-------|
| `get_positions` | Positions for a specific account | `account` (required), `status?` (OPEN/CLOSED), `first?`, `skip?` |
| `get_position` | Single position with real-time PnL via RPC | `positionId` (required) |
| `search_positions` | Search all positions with filters | `side?` (0=LONG, 1=SHORT), `tenor?` (0=1D, 1=1W, 2=1M), `status?`, `minNotional?`, `first?`, `skip?` |

### Oracle & Pricing

| Tool | Description | Input |
|------|-------------|-------|
| `get_forward_price` | Forward price for a specific tenor | `tenor` (1D, 1W, or 1M), `pairId?` |
| `get_oracle_state` | Full oracle state: spot, all forward prices, validity | `pairId?` |

### Accounts & Fees

| Tool | Description | Input |
|------|-------------|-------|
| `get_account` | Account margin: collateral, locked, available, position count | `address` (required) |
| `get_fee_events` | Fee event breakdown (trading, liquidation, termination, oracle) | `first?`, `skip?` |

### Token

| Tool | Description | Input |
|------|-------------|-------|
| `get_token_balance` | ERC-20 token balance for an address (defaults to USDC) | `address` (required), `token?` |
| `check_allowance` | ERC-20 allowance for an owner/spender pair | `owner` (required), `spender` (contract name or address), `token?` |

### Simulation

| Tool | Description | Input |
|------|-------------|-------|
| `simulate_open_position` | Preview margin, fee, and entry strike for a new position | `side` (LONG/SHORT), `tenor` (1D/1W/1M), `notional` (USDC string), `margin?`, `from?` |

---

## Write Tools (8)

> **Wallet required.** Write tools return unsigned transaction calldata for client-side signing. They do NOT execute transactions. Your agent or wallet must sign and broadcast the returned calldata.

### Trading

| Tool | Description | Input |
|------|-------------|-------|
| `open_position` | Calldata to open a new FX forward position | `side`, `tenor`, `notional`, `margin`, `pairId?`, `from?` |
| `close_position` | Calldata to close a position via early termination | `positionId`, `from?` |

### Margin

| Tool | Description | Input |
|------|-------------|-------|
| `deposit_margin` | Calldata to deposit USDC as margin collateral (requires prior USDC approval) | `amount`, `from?` |
| `withdraw_margin` | Calldata to withdraw available USDC margin | `amount`, `from?` |

### Vault (Liquidity Providers)

| Tool | Description | Input |
|------|-------------|-------|
| `vault_deposit` | Calldata to deposit USDC into the pool vault (requires prior USDC approval) | `amount`, `receiver`, `from?` |
| `vault_withdraw` | Calldata to withdraw USDC from the pool vault | `amount`, `receiver`, `owner`, `from?` |

### Token Approval & Testnet

| Tool | Description | Input |
|------|-------------|-------|
| `approve_token` | Calldata to approve a Nile contract to spend tokens | `spender` (contract name or address), `amount`, `token?`, `from?` |
| `mint_test_token` | Calldata to mint test tokens (testnet only) | `to`, `amount`, `from?` |

All amounts are strings in USDC smallest unit (6 decimals). Example: `"1000000000"` = 1,000 USDC.

---

## Usage Guide

### Numeric Conventions

| Type | Decimals | Example |
|------|----------|---------|
| USDC amounts | 6 | `"1234567890"` = 1,234.567890 USDC |
| Forward/spot prices | 18 | `"1085000000000000000"` = 1.085000 |
| Utilization, fees | Basis points | `"4500"` = 45% |

### Pagination

Tools returning lists support `first` (page size, default 25, max 1000) and `skip` (offset, default 0).

### Response Envelope

All responses include:

```json
{
  "protocol": { "name": "Nile Markets", "version": "0.3.0" },
  "network": "sepolia",
  "data": { ... }
}
```

Subgraph-sourced responses also include `_meta.lastIndexedBlock` for freshness checking.

### Best Practices

1. **Check mode first** — Call `get_protocol_mode` before suggesting trades. If not NORMAL, inform the user of restrictions.
2. **Real-time vs indexed** — `get_position` and `get_forward_price` use RPC (real-time). `get_positions` and `search_positions` use the subgraph (may lag a few seconds).
3. **Simulate before trading** — Use `simulate_open_position` to preview margin requirements and fees before generating `open_position` calldata.
4. **Rate limit** — 100 requests/minute per IP. Returns `429` with `Retry-After` header when exceeded.

---

## Sepolia Network Reference

The Nile Markets protocol is deployed on Ethereum Sepolia. The MCP server handles all network configuration internally — you do not need these details for MCP tool calls. This reference is provided for:

- **Path C signing** — broadcasting transactions returned by MCP write tools
- **Direct contract interaction** — constructing raw transactions outside of MCP
- **Verification** — confirming `TransactionCalldata.to` addresses

Machine-readable config: [`sepolia.json`](https://mcp.nilemarkets.com/config/sepolia.json)

| Parameter | Value |
|-----------|-------|
| **Network** | Ethereum Sepolia (testnet) |
| **Chain ID** | `11155111` |
| **Default RPC** | `https://ethereum-sepolia-rpc.publicnode.com` (free, no API key — override with your own if needed) |
| **Subgraph** | `https://api.studio.thegraph.com/query/1743364/fx-forward-sepolia/v0.0.1` |
| **Collateral** | USDC (6 decimals) |

### Contract Addresses

| Contract | Address | Used For |
|----------|---------|----------|
| Position Manager | `0x8d81E9f1D0F0d1BdAAc0a91AFc2976522429A0cd` | Open/close positions |
| Margin Accounts | `0x12c310A5A5B5771459ff96979931CddE75A6D935` | Deposit/withdraw margin |
| Pool Vault | `0x61208f0337eE40278b0cbc55daEE7A37Fa180618` | LP deposits/withdrawals |
| Settlement Engine | `0x86f9339EC3Ca09aa51E1862911678C696eC09470` | Position settlement |
| Oracle Module | `0x1f78995b606CCF768E0a532Be8A1AB6eDf3Cd4D5` | Price feeds |
| Protocol | `0xC20E775e274314570DAa1d50a191750753F686dA` | Protocol entry point |
| Risk Manager | `0xd82515b62501F011DA2BaFA877B57f8713dc20Ee` | Risk parameters |
| Mode Controller | `0x2b7775De7a4696f05D875BDE8f983303A3d49582` | Operating mode |
| Config | `0x8653f27FB34bF845c7C16Dca07DFf7A0cd2A6557` | Protocol configuration |
| USDC | `0x319FeC6Cc374922A183A354a41E89b7A313EE547` | Collateral token |

> **Note:** MCP write tools return `TransactionCalldata` with the correct `to` address pre-filled. You only need these addresses if constructing raw transactions without MCP or verifying calldata targets.

---

## Operation Workflows

For detailed read and write operation workflows with step-by-step tool call sequences, see [workflow.md](https://mcp.nilemarkets.com/workflow.md).

### Write Operations Summary

1. **Pre-flight** — `get_protocol_mode` (verify NORMAL), `get_token_balance` (check balance)
2. **Prepare** — `check_allowance` → `approve_token` if needed → `deposit_margin` if needed
3. **Simulate** — `simulate_open_position` to preview margin, fees, entry strike
4. **Execute** — `open_position` (or other write tool) → returns unsigned calldata
5. **Sign** — sign and broadcast using one of the three paths below

### Signing Paths

All signing paths require a wallet set up beforehand (key import and passphrase configuration happen outside the Nile workflow).

- **Path A — Nile CLI + OWS wallet** (CLI users, works today):
  The installed `nile` binary works zero-config on Sepolia — addresses, RPC, and subgraph URL are embedded. Install an [OWS-compatible wallet](https://docs.openwallet.sh/), run `nile config set-wallet <name>`, then trade:
  `nile position open --side LONG --tenor 1M --notional 10000 --margin 20` — CLI builds unsigned tx, delegates signing to OWS, broadcasts.
  See [cli.md](https://mcp.nilemarkets.com/cli.md) for full installation, wallet setup, and command reference.

  **CLI ↔ MCP tool mapping:**

  | MCP Tool | CLI Equivalent |
  |----------|----------------|
  | `get_pool_state` | `nile pool state` |
  | `get_protocol_mode` | `nile protocol mode` |
  | `get_pool_transactions` | `nile pool transactions` |
  | `get_daily_stats` | `nile stats daily --days <N>` |
  | `get_positions` | `nile position list --account <addr>` |
  | `get_position` | `nile position get --id <id>` |
  | `search_positions` | `nile position search [--side N] [--status S]` |
  | `get_forward_price` | `nile oracle price --tenor <T>` |
  | `get_oracle_state` | `nile oracle state` |
  | `get_account` | `nile account balance --account <addr>` |
  | `get_fee_events` | `nile fees list` |
  | `get_token_balance` | `nile token balance --account <addr>` |
  | `check_allowance` | `nile token allowance --owner <addr> --spender <name>` |
  | `simulate_open_position` | `nile simulate open --side S --tenor T --notional N --margin M` |
  | `open_position` | `nile position open --side S --tenor T --notional N --margin M` |
  | `close_position` | `nile position close --id <id>` |
  | `deposit_margin` | `nile account deposit --amount <N>` |
  | `withdraw_margin` | `nile account withdraw --amount <N>` |
  | `vault_deposit` | `nile pool deposit --amount <N>` |
  | `vault_withdraw` | `nile pool withdraw --amount <N>` |
  | `approve_token` | `nile token approve --spender <name> --amount <N>` |
  | `mint_test_token` | `nile token mint --to <addr> --amount <N>` |

  > CLI amounts are human-readable (`10000` = 10,000 USDC). MCP amounts are in smallest unit (`10000000000`).

- **Path B — MCP + OWS MCP server** (AI agents, planned):
  `ows serve --mcp` is not yet available in OWS v1.0.0. When shipped, this will allow a fully MCP-native flow: agent calls Nile MCP for calldata, then OWS MCP to sign and broadcast — no CLI required. See [workflow.md](https://mcp.nilemarkets.com/workflow.md#path-b-mcp--ows-mcp-server-no-cli-required) for the planned flow.

- **Path C — MCP + any signing tool** (works today, recommended for agents):
  Use Nile MCP write tools to generate unsigned calldata (`to`, `data`, `value`, `chainId`), then sign and broadcast with any tool. The MCP response includes the correct contract address in `to` and chain ID `11155111`. Use the default RPC `https://ethereum-sepolia-rpc.publicnode.com` (free, no API key) or any Sepolia RPC. See [Sepolia Network Reference](#sepolia-network-reference) for all contract addresses.
  - **Foundry `cast`**: `cast send <to> --data <data> --rpc-url https://ethereum-sepolia-rpc.publicnode.com --private-key <key>`
  - **viem / ethers.js**: sign programmatically in a script or agent runtime
  - **MetaMask / Rabby / Frame**: paste calldata into wallet UI
  - **Any signing MCP server**: when other wallet MCP servers become available

  This is the most flexible path and works with any EVM wallet. Complete step-by-step flow in [workflow.md](https://mcp.nilemarkets.com/workflow.md#path-c-mcp--any-signing-tool).

---

## Example Queries

**"What's the current pool utilization and TVL?"**
→ `get_pool_state` — returns total assets, utilization (basis points), share price

**"Show me all open positions for 0xABC..."**
→ `get_positions` with `account: "0xABC..."`, `status: "OPEN"`

**"What are the EUR/USD forward prices?"**
→ `get_forward_price` with `tenor: "1D"` (or omit tenor via `get_oracle_state` for all)

**"How much margin for a 1000 USDC long 1-week position?"**
→ `simulate_open_position` with `side: "LONG"`, `tenor: "1W"`, `notional: "1000000000"`

**"Is the protocol operating normally?"**
→ `get_protocol_mode` — returns mode and allowed operations

**"Find all open short positions above 5000 USDC notional"**
→ `search_positions` with `side: 1`, `status: "OPEN"`, `minNotional: "5000000000"`

**"Show the last 7 days of protocol stats"**
→ `get_daily_stats` with `days: 7`

**"Check my USDC balance"**
→ `get_token_balance` with `address: "0x..."`

**"Do I need to approve USDC before depositing margin?"**
→ `check_allowance` with `owner: "0x..."`, `spender: "marginAccounts"` — if zero, call `approve_token`

**"Get me some test USDC on Sepolia"**
→ `mint_test_token` with `to: "0x..."`, `amount: "10000000000"` (10,000 USDC)

---

## Resources

- **Documentation**: [docs.nilemarkets.com](https://docs.nilemarkets.com)
- **TypeScript SDK**: `npm install @nile-markets/sdk` — ABIs, typed constants, pair IDs
- **x402 API**: [x402.nilemarkets.com](https://x402.nilemarkets.com) — REST API with x402 micropayments
- **CLI**: `curl -fsSL https://mcp.nilemarkets.com/install.sh | bash` or `cargo install nile-markets-cli` — Zero-config for Sepolia. See [cli.md](https://mcp.nilemarkets.com/cli.md) for setup and commands.
- **Network config**: [mcp.nilemarkets.com/config/sepolia.json](https://mcp.nilemarkets.com/config/sepolia.json) — Machine-readable Sepolia addresses, RPC, and subgraph URL
- **MCP Inspector**: `npx @modelcontextprotocol/inspector --transport http --server-url https://mcp.nilemarkets.com/api/mcp`