# WorldRouter API

> Pay-per-token AI inference. 30+ models. OpenAI-compatible. No API keys, no accounts, no subscriptions. Powered by MPP micropayments (USDC.e on Tempo chain).

## How It Works

Send a standard OpenAI-compatible chat completion request. Payment is handled automatically via MPP protocol headers. No signup, no tokens, no OAuth. Payment IS authentication.

## Quick Start

### Using AgentPay SDK (Recommended)

```bash
# Install AgentPay SDK
curl -fsSL https://wlfi.sh | sh

# One-shot completion (Charge Intent)
agentpay mpp https://api-infer.agentsey.ai/x402/v1/chat/completions \
  --method POST --header "Content-Type: application/json" \
  --json-body '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Hello, world!"}]}' \
  --json

# Streaming completion (Session Intent)
agentpay mpp https://api-infer.agentsey.ai/x402/v1/chat/completions/stream \
  --deposit 0.1 --header "Content-Type: application/json" \
  --json-body '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Write a haiku about payments."}]}' \
  --json
```

### Using mppx (Alternative)

```bash
# One-shot completion (Charge Intent)
npx mppx fetch "https://api-infer.agentsey.ai/x402/v1/chat/completions" \
  -X POST -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Hello, world!"}]}'

# Streaming completion (Session Intent)
npx mppx fetch "https://api-infer.agentsey.ai/x402/v1/chat/completions/stream" \
  -X POST -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"Write a haiku about payments."}]}'
```

## Endpoints

| Endpoint | Method | Intent | Description |
|---|---|---|---|
| /x402/v1/chat/completions | POST | Charge | One-shot chat completion. Pay per request. |
| /x402/v1/chat/completions/stream | POST | Session | Open session channel + stream response. |
| /x402/v1/chat/completions/stream | HEAD | Session | Session control: voucher, topUp, close. |

> **Note:** The `/x402/` path prefix is a legacy convention. Use `agentpay mpp` to handle MPP payment automatically.

## Payment Modes

### Charge Intent (one-shot)
Best for: single queries, simple completions, stateless requests.

1. Client sends POST with model + messages
2. Server returns HTTP 402 with MPP payment challenge (amount, currency, chain)
3. Client pays on-chain (USDC.e on Tempo)
4. Client retries with payment credential in Authorization header
5. Server verifies, runs inference, returns response + Payment-Receipt header

With `agentpay mpp`, steps 2–4 are handled automatically.

### Session Intent (streaming channel)
Best for: long conversations, streaming, multi-turn sessions.

1. Client sends POST to open channel (deposits funds on-chain)
2. Server streams response via SSE
3. For subsequent requests, client sends HEAD with voucher (incremental payment proof)
4. Client can topUp the channel deposit at any time
5. Either side closes the channel; final settlement on-chain

## Pricing

Pricing is dynamic, calculated per-token based on the model used. Cost is estimated from prompt tokens with an overhead multiplier (default 1.5×) to cover completion tokens.

```
estimated_cost = prompt_tokens × input_cost_per_token × overhead_multiplier
```

Actual cost is settled after inference based on real token usage.

### OpenAI Models

| Model | Input ($/1M tokens) | Output ($/1M tokens) | Notes |
|---|---:|---:|---|
| gpt-5 | $0.125 | $1.00 | Flagship |
| gpt-5.1 | $0.125 | $1.00 | |
| gpt-5.2 | $0.175 | $1.40 | |
| gpt-5.4 | $0.25 | $1.50 | |
| gpt-5-pro | $1.50 | $12.00 | Extended thinking |
| gpt-5.4-pro | — | — | Extended thinking |
| gpt-5-mini | — | — | Lightweight |
| gpt-5-nano | — | — | Fastest |
| gpt-4.1 | — | — | |
| gpt-4.1-mini | — | — | |
| gpt-4.1-nano | — | — | |
| gpt-4o | — | — | |
| gpt-4o-mini | — | — | |

Models marked — use LiteLLM's built-in cost registry (standard OpenAI/Anthropic pricing).

### OpenAI Codex (Code-Optimized)

| Model | Input ($/1M tokens) | Output ($/1M tokens) |
|---|---:|---:|
| gpt-5.1-codex | $0.125 | $1.00 |
| gpt-5.1-codex-max | $0.125 | $1.00 |
| gpt-5.2-codex | $0.175 | $1.40 |
| gpt-5.3-codex | $0.175 | $1.40 |

### Anthropic Models

| Model | Input ($/1M tokens) | Output ($/1M tokens) |
|---|---:|---:|
| claude-opus-4-6 | — | — |
| claude-opus-4-5 | — | — |
| claude-opus-4-1 | — | — |
| claude-opus-4 | — | — |
| claude-sonnet-4-5 | — | — |
| claude-sonnet-4 | — | — |

Anthropic models use standard Anthropic pricing via LiteLLM cost registry.

## Request Format

OpenAI-compatible chat completions. Supports all standard parameters:

```json
{
  "model": "gpt-5",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is MPP?"}
  ],
  "temperature": 0.7,
  "max_tokens": 1024,
  "stream": false
}
```

### Required Fields
- **model** (string): Model name from the supported models list
- **messages** (array): OpenAI-format messages (role + content)

### Optional Fields
- **temperature** (float): Sampling temperature, 0–2
- **max_tokens** (int): Maximum completion tokens
- **top_p** (float): Nucleus sampling
- **stream** (bool): Enable SSE streaming (use Session Intent endpoint for streaming)
- **stop** (string|array): Stop sequences
- All other OpenAI chat completion parameters are supported

## Response Format

Standard OpenAI chat completion response:

```json
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1711000000,
  "model": "gpt-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "MPP is an HTTP-native micropayment protocol..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 150,
    "total_tokens": 175
  }
}
```

The response includes a `Payment-Receipt` header with the settlement proof.

## Authentication

No API keys. Payment via USDC.e on Tempo chain (MPP protocol) serves as authentication. Use any MPP-compatible client:

- `agentpay mpp` — AgentPay SDK (recommended)
- Any HTTP client that implements the MPP payment flow

## Settlement

- Chain: Tempo (chain ID 4217)
- Currency: USDC.e (`0x20C000000000000000000000b9537d11c60E8b50`)
- Fee payer: Tempo sponsor relay (user pays no gas)
- Settlement: immediate for Charge; on channel close for Session

## Links

- API base: https://api-infer.agentsey.ai
- MPP protocol: https://mpp.dev
- Tempo chain: https://tempo.xyz