Shared API Architecture

Why Three Surfaces?

Each surface serves a different runtime environment, transport model, and authentication strategy. No single API format satisfies all three use cases.

Surface	Target User	Transport	Auth Model
MCP Server	AI agents (Claude, ChatGPT, Cursor, VS Code)	Streamable HTTP (JSON-RPC)	None
x402 API	Programmatic clients, pay-per-request agents	REST (HTTP GET/POST)	Free reads; $0.01 USDC per write via x402
CLI	Shell-based agents, CI pipelines, terminal users	stdin/stdout (subprocess)	None (local binary)

All three expose the same 22 operations (15 read, 8 write) with the same data semantics. The difference is transport, auth, and output formatting.

The Shared API Layer

Rather than duplicating data-access code across surfaces, a shared TypeScript module (@nile-markets/api) sits between the surfaces and the data sources. Each surface imports shared functions and adds only its transport-specific layer.

+-------------------+     +-------------------+     +-------------------+
|    MCP Server     |     |    x402 Gateway    |     |       CLI         |
|  (JSON-RPC tools) |     |  (REST endpoints)  |     |  (Rust commands)  |
+--------+----------+     +--------+----------+     +--------+----------+
         |                         |                          |
         |    TypeScript           |    TypeScript             |    Rust
         v                         v                          v
+--------+-------------------------+----------+     +--------+----------+
|              @nile-markets/api              |     |  crates/cli/      |
|  config | clients | queries | encoding      |     |  (mirrors same    |
|  types  | logger  | rate-limit | context    |     |   query semantics)|
+--------+-------------------------+----------+     +--------+----------+
         |                         |                          |
         v                         v                          v
+--------+-------------------------+-------------------------+----------+
|                  Ethereum RPC (viem / alloy-rs)                       |
+----------------------------------------------------------------------+
|                  The Graph Subgraph (GraphQL)                         |
+----------------------------------------------------------------------+

The two TypeScript surfaces import directly from @nile-markets/api. The Rust CLI implements the same logical queries independently via graphql_client derive macros, maintaining semantic parity.

What Is Shared

Config Resolution

Network configuration resolves through a consistent fallback chain across all surfaces:

RPC_URL_{NETWORK} > RPC_URL (legacy) > per-network default > error

The withNetwork() function sets the active network at each request’s entry point using AsyncLocalStorage. All downstream calls (getConfig(), getPublicClient(), getGraphQLClient()) read from this context automatically — no parameter threading needed.

RPC Clients

A cached viem PublicClient per network handles all onchain reads: contract state, forward prices, margin balances, oracle validity, and position simulation via eth_call. Clients are created once and reused across requests.

GraphQL Queries

Seven shared subgraph query functions fetch historical and aggregate data:

Query	Data
`fetchPositions`	Account positions with optional status filter
`searchPositions`	Cross-account position search with side/tenor/notional filters
`fetchPoolState`	Pool singleton (TVL, shares, fees, exposure)
`fetchDailyStats`	Daily trading volume, PnL, and fee aggregates
`fetchPoolTransactions`	Vault deposit/withdrawal history
`fetchFeeEvents`	Fee collection events by type
`fetchAccount`	Account aggregate stats (position count, realized PnL, LP shares)

Some operations combine RPC and subgraph data. For example, fetchPoolStateRpc() reads real-time state (total assets, share price, utilization) from RPC and historical fee totals from the subgraph. If the subgraph is unavailable, it returns RPC data with zeroed aggregate fields rather than failing.

Transaction Encoding

All write operations return unsigned calldata rather than executing transactions:

{
  "to": "0x...",
  "data": "0x...",
  "value": "0",
  "estimatedGas": "150000",
  "chainId": 11155111,
  "description": "Open LONG position with 100000000 notional"
}

Signing and broadcasting happen externally via the user’s wallet. This keeps all surfaces zero-custody.

Response Metadata

Every response includes domain-layer metadata with the same structure:

Field	Description
`protocol.name`	`"nile-markets"`
`protocol.version`	`"0.3.2"` (single source of truth in `@nile-markets/api`)
`network`	Active network (`"sepolia"`, `"local"`)
`blockNumber`	Subgraph indexing head (when subgraph data is included)
`source`	`"rpc"`, `"subgraph"`, or `"rpc+subgraph"`

Enum and Label Maps

Solidity enum ordinals (stored in contract state and subgraph) are mapped to human-readable labels by shared functions: sideLabel(), tenorLabel(), modeLabel(), mapCloseReason(), feeTypeLabel(). All surfaces use the same mappings, so a position shows "LONG" and "1W" regardless of whether you query via MCP, REST, or CLI.

What Is Surface-Specific

Each surface adds only its transport and formatting layer on top of the shared API.

MCP Server
x402 Gateway
CLI

Transport: Streamable HTTP with JSON-RPC framing via mcp-handler
Tool registration: MCP tool schemas with name, description, inputSchema
Network context: withNetwork() called per tool invocation
Auth: None
Response format: content[0].text JSON string inside MCP tool result
Rate limiting: Shared createRateLimiter() from @nile-markets/api

Transport: Next.js API routes (GET for reads, POST for writes)
Auth: Free reads; writes require x402 micropayment header ($0.01 USDC)
Network context: withNetwork() called per route handler from query param
Response format: REST JSON envelope ({ success, data, protocol, network, timestamp })
Rate limiting: Inline middleware (separate from shared limiter due to x402 payment verification ordering)

Transport: stdin/stdout subprocess, --output json flag for structured output
Language: Rust (cannot import TypeScript package directly)
Auth: None (local binary); wallet signing via OWS or external signer
Network context: --network flag or NILE_NETWORK env var
Query parity: Separate .graphql files in crates/cli/graphql/ mirror shared query semantics
Response format: JSON or formatted table via comfy-table

Adding a New Surface

To add a fourth API surface (WebSocket, gRPC, or another transport):

Import shared functions

Add @nile-markets/api as a workspace dependency. Import config, clients, queries, and encoding functions.

Set network context at entry point

Call withNetwork(network, handler) at each request boundary. All downstream calls resolve network automatically.

Add transport layer

Implement request parsing, response formatting, and auth for the new transport. The shared module handles all data access.

Update downstream sync rules

Add the new surface to the API surface parity checklist. Every MCP tool and x402 endpoint must have a corresponding operation in the new surface.

Supporting two testnets

M2 is deployed on both Ethereum Sepolia (L1, chainId 11155111) and Arbitrum Sepolia (L2, chainId 421614). Both networks run identical contracts with identical parameters; the protocol surface is the same. The two-testnet choice is additive coverage, not a switch:

The L1 case. Sepolia mirrors Ethereum mainnet’s gas market and ~12 s confirmation cadence. Validating gas-cap behavior, fee-driven publisher pauses, and L1-scale settlement timing requires a live L1 testnet — without it, operators cannot rehearse mainnet conditions. Sepolia is also the canonical L1 testnet for ecosystem dependencies (Pyth, Graph Studio, third-party tooling).
The L2 case. Arbitrum Sepolia provides a deployment target with the cost / latency profile that agent integrations (MCP / x402 / CLI) tend to want. A typical 5-tx agent task (approve USDC → deposit margin → open position → poll → close) settles at L1 cadence on Sepolia and at L2 cadence on Arb Sep; both behaviors are correct, but agent iteration loops that want sub-second confirmation need the L2 option.

Neither network is “better”. They cover different validation regimes. Mainnet (M3) decisions for L1 vs L2 deployment are scoped separately and informed by data collected from both testnets.

Choosing a network for agent flows

Use case	Recommended network
Validate behavior under mainnet-shape gas variance	Ethereum Sepolia
Validate L1 confirmation cadence (12 s blocks) and ecosystem dependencies	Ethereum Sepolia
Benchmark agent throughput / fast iteration loops	Arbitrum Sepolia
Long-running scenarios where fee predictability matters	Arbitrum Sepolia
End-to-end coverage of protocol on both fee regimes	Both — run integrations in parallel

The protocol surface (function names, parameter types, revert conditions, response envelopes) is identical on both chains. Switching is a one-flag change: --network arbitrumSepolia on the CLI, ?network=arbitrumSepolia on x402, network parameter on MCP, or wallet chain switch in the frontend.

​Why Three Surfaces?

​The Shared API Layer

​What Is Shared

​Config Resolution

​RPC Clients

​GraphQL Queries

​Transaction Encoding

​Response Metadata

​Enum and Label Maps

​What Is Surface-Specific

​Adding a New Surface

​Supporting two testnets

​Choosing a network for agent flows