x402 API - Nile Markets

Sepolia Testnet Only — All data is from Ethereum Sepolia. Token balances and positions have no real-world value. Write payments use Sepolia USDC.

What is x402?

The x402 protocol enables HTTP-native micropayments using the 402 Payment Required status code. When you call a paid endpoint without payment, the server returns a 402 response with payment requirements. Your client pays the specified amount (onchain USDC transfer), attaches the payment proof to a retry, and the server fulfills the request. The Nile Markets x402 API splits access into two tiers:

Read endpoints (GET) — Free, no payment required
Write endpoints (POST) — $0.01 USDC per request via x402

Base URL: https://x402.nilemarkets.com

Free Endpoints (14 GET)

Pool and Protocol

Method	Path	Description	Query Params
GET	`/api/x402/pool/state`	Pool metrics: total assets, shares, share price, utilization	`network?`
GET	`/api/x402/pool/transactions`	Historical vault deposits and withdrawals	`first?`, `skip?`, `network?`
GET	`/api/x402/protocol/mode`	Operating mode: NORMAL, DEGRADED, REDUCE_ONLY, or PAUSED	`network?`
GET	`/api/x402/stats/daily`	Daily volume, fees, position opens/closes, pool PnL	`days?`, `network?`

Positions

Method	Path	Description	Query Params
GET	`/api/x402/positions`	Positions for an account	`account` (required), `status?`, `first?`, `skip?`, `network?`
GET	`/api/x402/positions/search`	Search all positions with filters	`side?`, `tenor?`, `status?`, `minNotional?`, `first?`, `skip?`, `network?`
GET	`/api/x402/position/[id]`	Single position with real-time PnL	—

Oracle and Pricing

Method	Path	Description	Query Params
GET	`/api/x402/oracle/state`	Full oracle state: spot, all forward prices, validity	`pairId?`, `network?`
GET	`/api/x402/oracle/forward`	Forward price for a specific tenor	`tenor` (required), `pairId?`, `network?`

Accounts and Fees

Method	Path	Description	Query Params
GET	`/api/x402/account/[address]`	Account margin: collateral, locked, available, position count	—
GET	`/api/x402/fees`	Fee event breakdown (trading, liquidation, termination, oracle)	`first?`, `skip?`, `network?`

Token and Simulation

Method	Path	Description	Query Params
GET	`/api/x402/token/balance`	ERC-20 token balance for an address	`address` (required), `token?`, `network?`
GET	`/api/x402/token/allowance`	ERC-20 allowance for an owner/spender pair	`owner` (required), `spender` (required), `token?`, `network?`
GET	`/api/x402/simulate/open`	Preview margin, fee, and entry strike	`side`, `tenor`, `notional` (all required), `margin?`, `from?`, `network?`

Paid Endpoints (8 POST)

Each POST request costs $0.01 USDC on Sepolia, paid via the x402 protocol. The payment is a separate onchain USDC transfer to the configured payee address, verified by an x402 facilitator before the request is fulfilled.

Trading

Method	Path	Description	Body Fields
POST	`/api/x402/position/open`	Calldata to open a new FX forward position	`side`, `tenor`, `notional`, `margin`, `pairId?`, `from?`
POST	`/api/x402/position/close`	Calldata to close a position via early termination	`positionId`, `from?`

Margin

Method	Path	Description	Body Fields
POST	`/api/x402/margin/deposit`	Calldata to deposit USDC as margin collateral	`amount`, `from?`
POST	`/api/x402/margin/withdraw`	Calldata to withdraw available USDC margin	`amount`, `from?`

Vault (Liquidity Providers)

Method	Path	Description	Body Fields
POST	`/api/x402/vault/deposit`	Calldata to deposit USDC into the pool vault	`amount`, `receiver`, `from?`
POST	`/api/x402/vault/withdraw`	Calldata to withdraw USDC from the pool vault	`amount`, `receiver`, `owner`, `from?`

Token Approval and Testnet

Method	Path	Description	Body Fields
POST	`/api/x402/token/approve`	Calldata to approve a Nile contract to spend tokens	`spender`, `amount`, `token?`, `from?`
POST	`/api/x402/token/mint`	Calldata to mint test tokens (testnet only)	`to`, `amount`, `from?`

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

Response Format

Every response uses a standard JSON envelope:

{
  "success": true,
  "data": { },
  "protocol": { "name": "Nile Markets", "version": "0.3.2" },
  "network": "sepolia",
  "timestamp": "2025-06-15T12:00:00.000Z",
  "blockNumber": "12345678",
  "source": "rpc+subgraph"
}

Field	Type	Description
`success`	`boolean`	`true` for 2xx responses, `false` for errors
`data`	`object?`	Endpoint-specific payload (omitted on errors)
`error`	`string?`	Error message (omitted on success)
`protocol`	`{ name, version }`	Protocol identity and API version
`network`	`string`	Target network (`"sepolia"`)
`timestamp`	`string`	ISO 8601 response timestamp
`blockNumber`	`string?`	Last indexed block (subgraph-sourced responses)
`source`	`string?`	Data source: `"rpc"`, `"subgraph"`, or `"rpc+subgraph"`

Write endpoints return TransactionCalldata in the data field, identical to the MCP server format.

Examples

Free Read — Pool State

curl -s https://x402.nilemarkets.com/api/x402/pool/state | jq

{
  "success": true,
  "data": {
    "totalAssets": "50000000000",
    "totalShares": "49500000000",
    "sharePrice": "1010101010101010101",
    "riskCapacityUtilization": "3200",
    "longExposure": "10000000000",
    "shortExposure": "6000000000"
  },
  "protocol": { "name": "Nile Markets", "version": "0.3.2" },
  "network": "sepolia",
  "timestamp": "2025-06-15T12:00:00.000Z",
  "source": "rpc+subgraph"
}

Free Read — Forward Price

curl -s "https://x402.nilemarkets.com/api/x402/oracle/forward?tenor=1M" | jq

Paid Write — Open Position

Without payment, the server returns 402 Payment Required with x402 payment requirements:

curl -s -X POST https://x402.nilemarkets.com/api/x402/position/open \
  -H "Content-Type: application/json" \
  -d '{
    "side": "LONG",
    "tenor": "1M",
    "notional": "10000000000",
    "margin": "20000000"
  }'

{
  "error": "X-PAYMENT header is required",
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:11155111",
    "maxAmountRequired": "10000",
    "resource": "https://x402.nilemarkets.com/api/x402/position/open",
    "description": "Open a new FX forward position",
    "mimeType": "application/json"
  }]
}

To complete the payment, use an x402-compatible client library that handles the 402 → pay → retry flow automatically. See x402.org for client SDKs in TypeScript, Python, and Go.

x402 Payment Flow

Initial request

Your client sends a POST to a paid endpoint without payment headers.

402 response

The server returns HTTP 402 with accepts containing the payment scheme, amount ($0.01 USDC), network, and payee address.

Onchain payment

Your client transfers the specified USDC amount to the payee address on Sepolia and obtains a payment proof.

Retry with proof

Your client retries the original request with the X-PAYMENT header containing the payment proof.

Fulfillment

The server verifies the payment via the x402 facilitator and returns the requested data (unsigned transaction calldata for write endpoints).

x402 client libraries (available at x402.org) handle steps 2 through 4 automatically.

Rate Limits

Tier	Limit	Enforcement
Free endpoints (GET)	100 req/min per IP	HTTP 429 with `Retry-After`
Paid endpoints (POST)	No rate limit	Payment itself throttles abuse

MCP vs x402

The MCP server and x402 API expose the same 22 operations with identical data. Choose based on your client:

	MCP Server	x402 API
Transport	Streamable HTTP (MCP protocol)	Standard REST (HTTP)
Client	AI agents with MCP support	Any HTTP client (`curl`, `fetch`, SDKs)
Auth	None	Free reads; $0.01 USDC per write
Response format	MCP content blocks	JSON envelope with `success`, `timestamp`
Best for	Claude, ChatGPT, Cursor, VS Code	Programmatic integrations, scripts, bots

​What is x402?

​Free Endpoints (14 GET)

​Pool and Protocol

​Positions

​Oracle and Pricing

​Accounts and Fees

​Token and Simulation

​Paid Endpoints (8 POST)

​Trading

​Margin

​Vault (Liquidity Providers)

​Token Approval and Testnet

​Response Format

​Examples

​Free Read — Pool State

​Free Read — Forward Price

​Paid Write — Open Position

​x402 Payment Flow

​Rate Limits

​MCP vs x402

What is x402?

Free Endpoints (14 GET)

Pool and Protocol

Positions

Oracle and Pricing

Accounts and Fees

Token and Simulation

Paid Endpoints (8 POST)

Trading

Margin

Vault (Liquidity Providers)

Token Approval and Testnet

Response Format

Examples

Free Read — Pool State

Free Read — Forward Price

Paid Write — Open Position

x402 Payment Flow

Rate Limits

MCP vs x402