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

# AI & Agents Overview

> Six integration surfaces connect AI agents to the Nile Markets protocol — MCP server (23 tools), x402 REST API (23 endpoints), CLI (30+ commands), Claude Code plugin (4 skills), OpenClaw skill, and The Graph MCP shim.

<Warning>
  **Testnet Only** — All integration surfaces connect to Ethereum Sepolia (L1, chainId `11155111`) or Arbitrum Sepolia (L2, chainId `421614`). Token balances and positions have no real-world value. Select the target chain via `--network` (CLI), `?network=` (x402), or the `network` tool parameter (MCP).
</Warning>

<Note>
  **Unstable API (v0.3.2)** — Tool schemas, endpoint paths, and response formats may change without notice during the M2 milestone.
</Note>

## Integration Surfaces

Six surfaces expose the same protocol operations with different transports, auth models, and target audiences.

| Surface                                             | Transport                 | Tools / Endpoints                             | Auth                                       | Best For                                                      |
| --------------------------------------------------- | ------------------------- | --------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------- |
| [MCP Server](/ai-agents/mcp-server)                 | Streamable HTTP           | 23 MCP tools (15 read, 8 write)               | None                                       | AI agents with MCP support (Claude, ChatGPT, Cursor, VS Code) |
| [x402 API](/ai-agents/x402-api)                     | REST (HTTP)               | 23 endpoints (15 GET, 8 POST)                 | Free reads; \$0.01 USDC per write via x402 | Programmatic clients, pay-per-request agents                  |
| [CLI Agent Mode](/ai-agents/cli-agent-mode)         | stdin/stdout, JSON output | 30+ commands                                  | None (local binary)                        | Shell-based agents, scripting, CI pipelines                   |
| [Claude Code Plugin](/ai-agents/claude-code-plugin) | Claude Code skills        | 4 skills (query, execute, explain, integrate) | None (local plugin)                        | Claude Code users building on the protocol                    |
| [OpenClaw Skill](/ai-agents/openclaw-skill)         | ClawhHub registry         | 1 skill (MCP-backed)                          | None                                       | OpenClaw agents via `clawhub install`                         |
| [Graph MCP](/ai-agents/graph-mcp)                   | Streamable HTTP           | Subgraph queries                              | None                                       | Direct GraphQL access to indexed protocol data                |

## Which Surface Should You Use?

**Building an AI agent that trades or queries positions?** Start with the [MCP Server](/ai-agents/mcp-server). It has the richest tool set, works with every major AI platform, and requires no auth. Connect in one command:

```bash theme={null}
claude mcp add nile-markets --transport http https://mcp.nilemarkets.com/api/mcp
```

**Building a traditional API integration?** Use the [x402 API](/ai-agents/x402-api). Standard REST with JSON responses — reads are free, writes cost \$0.01 USDC via the x402 micropayment protocol.

**Automating from a shell or CI pipeline?** Use the [CLI in agent mode](/ai-agents/cli-agent-mode). The `nile` binary outputs structured JSON with `--output json` and works zero-config; pass `--network arbitrumSepolia` or `--network sepolia` to select the chain.

## Choosing a network for agent flows

A typical 5-transaction agent task (approve USDC → deposit margin → open position → poll fixings → close) plays out differently on the two testnets:

| Property                    | Ethereum Sepolia (L1)           | Arbitrum Sepolia (L2) |
| --------------------------- | ------------------------------- | --------------------- |
| Per-tx confirmation latency | \~12 s                          | sub-second            |
| 5-tx flow end-to-end        | \~60–120 s                      | \< 5 s                |
| Gas fee variance            | Mainnet-shape (spikes possible) | Low and steady        |

Neither is "wrong" — they validate the protocol under different confirmation regimes. Lead with Arbitrum Sepolia when your integration benchmarks throughput or relies on rapid iteration; lead with Ethereum Sepolia when you're validating L1-fidelity behavior. Both surfaces accept the same operations with the same response shapes.

**Using Claude Code for protocol development?** Install the [Claude Code Plugin](/ai-agents/claude-code-plugin) for four specialized skills that understand protocol internals.

**Want raw subgraph access?** The [Graph MCP](/ai-agents/graph-mcp) shim exposes the protocol's subgraph directly for custom GraphQL queries beyond what the MCP tools provide.

## Two MCP Servers

Nile Markets operates two separate MCP servers:

| Server           | URL                           | Purpose                                                                                 |
| ---------------- | ----------------------------- | --------------------------------------------------------------------------------------- |
| **Nile MCP**     | `mcp.nilemarkets.com/api/mcp` | Protocol data — 23 tools for positions, oracle prices, pool state, transaction calldata |
| **Mintlify MCP** | `docs.nilemarkets.com/mcp`    | Documentation search — semantic search over these docs pages                            |

You can connect both simultaneously. They serve different purposes and do not overlap.

## Surface Pages

<Columns cols={2}>
  <Card title="MCP Server" icon="plug" href="/ai-agents/mcp-server">
    23 tools via Streamable HTTP — connect from Claude, ChatGPT, Cursor, VS Code, and more
  </Card>

  <Card title="x402 API" icon="credit-card" href="/ai-agents/x402-api">
    REST API with free reads and \$0.01 micropayment writes via the x402 protocol
  </Card>

  <Card title="CLI Agent Mode" icon="terminal" href="/ai-agents/cli-agent-mode">
    30+ commands with JSON output for shell-based agents and CI pipelines
  </Card>

  <Card title="Claude Code Plugin" icon="puzzle-piece" href="/ai-agents/claude-code-plugin">
    4 skills for querying, executing, explaining, and integrating with the protocol
  </Card>

  <Card title="OpenClaw Skill" icon="book-open" href="/ai-agents/openclaw-skill">
    One-command install via ClawhHub for OpenClaw-compatible agents
  </Card>

  <Card title="Graph MCP" icon="diagram-project" href="/ai-agents/graph-mcp">
    Direct subgraph access for custom GraphQL queries over indexed protocol data
  </Card>
</Columns>

## Shared Conventions

All surfaces share these conventions regardless of transport:

* **Amounts**: Strings in smallest unit — `"1000000000"` = 1,000 USDC (6 decimals), `"1085000000000000000"` = 1.085 (18 decimals for prices)
* **Write operations**: Return unsigned transaction calldata (`to`, `data`, `value`, `chainId`) — signing and broadcasting happen externally via your wallet
* **Response metadata**: Every response includes `protocol` (name + version), `network`, and optionally `blockNumber` and `source` (`"rpc"`, `"subgraph"`, or `"rpc+subgraph"`)
* **Pagination**: List endpoints support `first` (page size, default 25, max 1000) and `skip` (offset)
* **Rate limits**: 100 requests/minute per IP (MCP and x402 free endpoints)