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

# Claude Code Plugin

> Claude Code plugin with 4 orchestration skills (query, integrate, explain, execute) and 23 MCP tools for interacting with the Nile Markets protocol — install via marketplace or local checkout.

## Installation

<Tabs>
  <Tab title="Marketplace (recommended)">
    Add the plugin from the Claude Code marketplace, then install:

    ```bash theme={null}
    /plugin marketplace add nil3labs/nile-markets-claude-plugin
    /plugin install nile-markets@nile-markets-claude-plugin
    ```

    The plugin auto-configures the Nile Markets MCP server and registers all four skills. Verify with:

    ```bash theme={null}
    /plugin list
    ```
  </Tab>

  <Tab title="Local checkout">
    If you have the plugin repository cloned locally, point Claude Code at it:

    ```bash theme={null}
    claude --plugin-dir ./path-to-plugin
    ```

    Replace `./path-to-plugin` with the path to the `nile-markets-claude-plugin` directory on your machine. This loads skills from the local file system, useful for development or customization.
  </Tab>
</Tabs>

After installation, 23 MCP tools become available via natural language, and you can invoke any of the four skills explicitly using slash commands.

## Skills

The plugin bundles four orchestration skills. Each skill provides structured guidance to Claude Code for a specific workflow pattern.

| Skill         | Slash Command             | Purpose                                                                             |
| ------------- | ------------------------- | ----------------------------------------------------------------------------------- |
| **Query**     | `/nile-markets:query`     | Query protocol data — pool state, positions, oracle prices, account balances        |
| **Integrate** | `/nile-markets:integrate` | Generate TypeScript or Rust integration code using the official SDK                 |
| **Explain**   | `/nile-markets:explain`   | Explain protocol concepts — margin, liquidation, modes, settlement, forward pricing |
| **Execute**   | `/nile-markets:execute`   | Orchestrate write operations with signing guidance (CLI, MCP, or external wallet)   |

### /nile-markets:query

Queries live protocol data through MCP tools. Claude Code selects the appropriate tool based on your question.

**Example prompts:**

* "What's the current pool utilization and TVL?"
* "Show me all open positions for 0x1234...abcd"
* "Is the protocol operating normally?"
* "Get the EUR/USD 1-week forward price"

### /nile-markets:integrate

Generates integration code using the `@nile-markets/sdk` (TypeScript) or `fx-contracts` crate (Rust). Produces working code with correct ABIs, contract addresses, and numeric precision handling.

**Example prompts:**

* "Write TypeScript code to read the current share price using viem"
* "Generate a Rust function that opens a LONG 1M position using alloy-rs"
* "Show me how to monitor position PnL in a Node.js script"
* "Create a script that deposits USDC into the liquidity pool"

### /nile-markets:explain

Explains protocol mechanics grounded in the documentation. Returns clear, accurate explanations with links to the relevant docs pages.

**Example prompts:**

* "How does liquidation work in Nile Markets?"
* "What's the difference between initial margin and maintenance margin?"
* "Explain the four protocol modes and when they activate"
* "How is PnL calculated for a SHORT position?"

### /nile-markets:execute

Orchestrates onchain operations with step-by-step signing guidance. Supports three signing paths: Nile CLI with OWS wallet, MCP calldata with external signing, or direct contract interaction.

**Example prompts:**

* "Open a 1000 USDC long 1-week EUR/USD position"
* "Deposit 500 USDC as margin collateral"
* "Close position #42"
* "Deposit 10,000 USDC into the liquidity pool"

<Warning>
  The execute skill never handles private keys or passphrases. All key management and transaction signing happen outside the plugin, in your wallet tool of choice.
</Warning>

## MCP Tools

Once the plugin is loaded, all 23 MCP tools are available through natural language — you do not need to call them explicitly. Claude Code automatically selects the right tool based on your question.

### Read Tools (14)

| Tool                     | Description                                                                  |
| ------------------------ | ---------------------------------------------------------------------------- |
| `get_pool_state`         | Pool metrics: total assets, shares, share price, exposure, utilization, fees |
| `get_protocol_mode`      | Operating mode (NORMAL, DEGRADED, REDUCE\_ONLY, PAUSED)                      |
| `get_pool_transactions`  | Historical vault deposits and withdrawals                                    |
| `get_daily_stats`        | Daily volume, fees, position opens/closes                                    |
| `get_positions`          | Positions for a specific account                                             |
| `get_position`           | Single position with real-time PnL                                           |
| `search_positions`       | Search positions with side, tenor, status, notional filters                  |
| `get_forward_price`      | Forward price for one or all tenors                                          |
| `get_oracle_state`       | Full oracle state: spot, all forward prices, validity                        |
| `get_account`            | Account margin: collateral, locked, available, position count                |
| `get_fee_events`         | Fee event breakdown by type                                                  |
| `get_token_balance`      | ERC-20 token balance (defaults to USDC)                                      |
| `check_allowance`        | ERC-20 allowance for an owner/spender pair                                   |
| `simulate_open_position` | Preview margin, fee, and entry strike for a new position                     |

### Write Tools (8)

Write tools return unsigned transaction calldata. Your wallet signs and broadcasts.

| Tool              | Description                             |
| ----------------- | --------------------------------------- |
| `open_position`   | Open a new FX forward position          |
| `close_position`  | Close a position via early termination  |
| `deposit_margin`  | Deposit USDC as margin collateral       |
| `withdraw_margin` | Withdraw available USDC margin          |
| `vault_deposit`   | Deposit USDC into the liquidity pool    |
| `vault_withdraw`  | Withdraw USDC from the liquidity pool   |
| `approve_token`   | Approve a Nile contract to spend tokens |
| `mint_test_token` | Mint test tokens (Sepolia testnet only) |

## Natural Language Examples

You do not need to remember tool names. Ask questions naturally and Claude Code routes to the correct tool:

* **"What is the EUR/USD 1W forward price?"** -- calls `get_forward_price` with `tenor: "1W"`
* **"Show me all open positions for 0x1234..."** -- calls `get_positions` with `account` and `status: "OPEN"`
* **"How much margin do I need for a 5000 USDC short 1-month position?"** -- calls `simulate_open_position`
* **"What fees has the protocol collected today?"** -- calls `get_daily_stats` with `days: 1`
* **"Check my USDC balance"** -- calls `get_token_balance` with your address

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

<Note>
  The plugin connects to the Nile Markets MCP server on Ethereum Sepolia. All data and transactions are testnet-only with no real-world value.
</Note>