# Clervo x402 Gateway

> Low-price, agent-native x402 gateway. One wallet, one OpenAI-compatible API, many AI models.
> Pay per call in USDC on Base mainnet. No API keys, no accounts, no subscriptions.
> Cheaper than BlockRun during launch period.

## Quick Start

```bash
curl -sS https://api.clervo.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"groq/llama-3.1-8b-instant","messages":[{"role":"user","content":"Hello"}]}'
```

No payment needed for free models. For paid models, add `x-clervo-funding: paid` header to receive an x402 challenge, then sign with your wallet.

## Discovery Endpoints

- API Base: https://api.clervo.dev
- OpenAPI: https://api.clervo.dev/openapi.json
- Agent discovery: https://api.clervo.dev/agent.json
- x402 discovery: https://api.clervo.dev/.well-known/x402.json
- Models list: https://api.clervo.dev/v1/models
- Model detail: https://api.clervo.dev/v1/models/{urlEncodedModelId}
- Searchable pages: https://api.clervo.dev/models
- Operation lookup: https://api.clervo.dev/v1/operations/{operationId}
- Quickstart guide: https://api.clervo.dev/quickstart.md

## Payment

- Network: Base mainnet (eip155:8453)
- Token: USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)
- Protocol: x402 v2 (exact scheme)
- Facilitator: Coinbase CDP
- Flow: Request → 402 challenge → Sign USDC → Resend → Response
- Settlement: ~2 seconds on Base

## Services

### Chat Completions — POST /v1/chat/completions

OpenAI-compatible multi-model chat. Supports system/user/assistant messages, JSON mode, and configurable output length.

```json
{"model":"groq/llama-3.1-8b-instant","messages":[{"role":"user","content":"Explain x402 in one paragraph."}],"max_completion_tokens":256}
```

### Web Search — POST /v1/search

Free web search. Returns structured results with titles, URLs, and snippets.

```json
{"query":"x402 protocol AI payments","max_results":5}
```

Response: `{"object":"search.results","query":"...","results":[{"title":"...","url":"...","snippet":"..."}]}`

### Web Scrape — POST /v1/scrape

Convert any URL to clean markdown. Free, no API key needed.

```json
{"url":"https://example.com"}
```

Response: `{"url":"...","content":"# Page Title\n\nMarkdown content...","format":"markdown"}`

## Free Models (no payment needed)

### Clervo Fast — clervo/fast

Low-latency general text and JSON alias. Provider routing may change without changing the public model ID.

- Capabilities: text, json
- Typical latency: 170ms
- Max output: 1024 tokens
- Price: FREE

```bash
curl -sS https://api.clervo.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"clervo/fast","messages":[{"role":"user","content":"Hello"}],"max_completion_tokens":128}'
```

### Clervo Smart — clervo/smart

Balanced reasoning and instruction-following alias for general agent workloads.

- Capabilities: text, json, reasoning
- Typical latency: 475ms
- Max output: 1024 tokens
- Price: FREE

```bash
curl -sS https://api.clervo.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"clervo/smart","messages":[{"role":"user","content":"Hello"}],"max_completion_tokens":128}'
```

### Clervo Deep — clervo/deep

Deeper reasoning alias for tasks where quality matters more than latency.

- Capabilities: text, json, reasoning
- Typical latency: 988ms
- Max output: 1024 tokens
- Price: FREE

```bash
curl -sS https://api.clervo.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"clervo/deep","messages":[{"role":"user","content":"Hello"}],"max_completion_tokens":128}'
```

### Llama 3.1 8B Instant (Groq) — groq/llama-3.1-8b-instant

Ultra-fast open model via Groq. 170ms latency. Free during launch.

- Capabilities: text, json
- Typical latency: 170ms
- Max output: 1024 tokens
- Price: FREE

```bash
curl -sS https://api.clervo.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"groq/llama-3.1-8b-instant","messages":[{"role":"user","content":"Hello"}],"max_completion_tokens":128}'
```

### Llama 3.3 70B (Groq) — groq/llama-3.3-70b

Large open model via Groq. Fast inference, strong reasoning.

- Capabilities: text, json, reasoning
- Typical latency: 800ms
- Max output: 1024 tokens
- Price: FREE

```bash
curl -sS https://api.clervo.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"groq/llama-3.3-70b","messages":[{"role":"user","content":"Hello"}],"max_completion_tokens":128}'
```

### Llama 3.3 70B (SambaNova) — sambanova/llama-3.3-70b

Large open model via SambaNova. Free tier.

- Capabilities: text, json, reasoning
- Typical latency: 1500ms
- Max output: 1024 tokens
- Price: FREE

```bash
curl -sS https://api.clervo.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"sambanova/llama-3.3-70b","messages":[{"role":"user","content":"Hello"}],"max_completion_tokens":128}'
```

### Qwen 3.6 27B (Groq) — groq/qwen3.6-27b

Qwen 3.6 27B (Groq) — fast inference via Groq. Free during beta.

- Capabilities: text, json, reasoning
- Typical latency: 213ms
- Max output: 1024 tokens
- Price: FREE

```bash
curl -sS https://api.clervo.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"groq/qwen3.6-27b","messages":[{"role":"user","content":"Hello"}],"max_completion_tokens":128}'
```

### GPT-OSS 120B (Groq) — groq/gpt-oss-120b

GPT-OSS 120B (Groq) — fast inference via Groq. Free during beta.

- Capabilities: text, json, reasoning, code
- Typical latency: 419ms
- Max output: 1024 tokens
- Price: FREE

```bash
curl -sS https://api.clervo.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"groq/gpt-oss-120b","messages":[{"role":"user","content":"Hello"}],"max_completion_tokens":128}'
```

### GPT-OSS 20B (Groq) — groq/gpt-oss-20b

GPT-OSS 20B (Groq) — fast inference via Groq. Free during beta.

- Capabilities: text, json
- Typical latency: 181ms
- Max output: 1024 tokens
- Price: FREE

```bash
curl -sS https://api.clervo.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"groq/gpt-oss-20b","messages":[{"role":"user","content":"Hello"}],"max_completion_tokens":128}'
```

### Nemotron 3 Ultra 550B (Nvidia) — nvidia/nemotron-ultra-550b

Nemotron 3 Ultra 550B (Nvidia) — hosted on Nvidia NIM. Free during beta.

- Capabilities: text, json, reasoning, code
- Typical latency: 674ms
- Max output: 1024 tokens
- Price: FREE

```bash
curl -sS https://api.clervo.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"nvidia/nemotron-ultra-550b","messages":[{"role":"user","content":"Hello"}],"max_completion_tokens":128}'
```

### Nemotron 3 Super 120B (Nvidia) — nvidia/nemotron-super-120b

Nemotron 3 Super 120B (Nvidia) — hosted on Nvidia NIM. Free during beta.

- Capabilities: text, json, reasoning
- Typical latency: 766ms
- Max output: 1024 tokens
- Price: FREE

```bash
curl -sS https://api.clervo.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"nvidia/nemotron-super-120b","messages":[{"role":"user","content":"Hello"}],"max_completion_tokens":128}'
```

### Nemotron 3 Nano 30B (Nvidia) — nvidia/nemotron-nano-30b

Nemotron 3 Nano 30B (Nvidia) — hosted on Nvidia NIM. Free during beta.

- Capabilities: text, json, reasoning
- Typical latency: 1082ms
- Max output: 1024 tokens
- Price: FREE

```bash
curl -sS https://api.clervo.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"nvidia/nemotron-nano-30b","messages":[{"role":"user","content":"Hello"}],"max_completion_tokens":128}'
```

### DeepSeek V4 Flash (Nvidia) — nvidia/deepseek-v4-flash

DeepSeek V4 Flash (Nvidia) — hosted on Nvidia NIM. Free during beta.

- Capabilities: text, json, reasoning, code
- Typical latency: 13000ms
- Max output: 1024 tokens
- Price: FREE

```bash
curl -sS https://api.clervo.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"nvidia/deepseek-v4-flash","messages":[{"role":"user","content":"Hello"}],"max_completion_tokens":128}'
```

## Paid Models (x402 USDC on Base)

20% cheaper than BlockRun on comparable models. Request with `x-clervo-funding: paid` to get x402 challenge.

### Clervo Code — clervo/code

Code generation and software-engineering alias with replaceable provider routing.

- Capabilities: text, json, code
- Typical latency: 2600ms
- Price: $0.0150 per request
- Max input: 20000 characters
- Max output: 4096 tokens

```bash
curl -sS https://api.clervo.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  -H 'x-clervo-funding: paid' \
  -d '{"model":"clervo/code","messages":[{"role":"user","content":"Hello"}],"max_completion_tokens":128}'
```

### GPT 5.4 Mini (QuickAI label) — quickai/gpt-5.4-mini

Provider-reported model label observed in a bounded authenticated QuickAI test.

- Capabilities: text, json
- Typical latency: 3000ms
- Price: $0.0050 per request
- Max input: 20000 characters
- Max output: 1024 tokens

```bash
curl -sS https://api.clervo.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  -H 'x-clervo-funding: paid' \
  -d '{"model":"quickai/gpt-5.4-mini","messages":[{"role":"user","content":"Hello"}],"max_completion_tokens":128}'
```

### GPT 5.4 (QuickAI label) — quickai/gpt-5.4

Provider-reported model label observed in a bounded authenticated QuickAI test.

- Capabilities: text, json
- Typical latency: 3000ms
- Price: $0.0180 per request
- Max input: 20000 characters
- Max output: 1024 tokens

```bash
curl -sS https://api.clervo.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  -H 'x-clervo-funding: paid' \
  -d '{"model":"quickai/gpt-5.4","messages":[{"role":"user","content":"Hello"}],"max_completion_tokens":128}'
```

### GPT 5.5 (QuickAI label) — quickai/gpt-5.5

Provider-reported model label observed in a bounded authenticated QuickAI test.

- Capabilities: text, json
- Typical latency: 3000ms
- Price: $0.0350 per request
- Max input: 20000 characters
- Max output: 1024 tokens

```bash
curl -sS https://api.clervo.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  -H 'x-clervo-funding: paid' \
  -d '{"model":"quickai/gpt-5.5","messages":[{"role":"user","content":"Hello"}],"max_completion_tokens":128}'
```

### GPT 5.6 Luna (QuickAI label) — quickai/gpt-5.6-luna

Provider-reported model label observed in a bounded authenticated QuickAI test.

- Capabilities: text, json
- Typical latency: 3000ms
- Price: $0.0070 per request
- Max input: 20000 characters
- Max output: 1024 tokens

```bash
curl -sS https://api.clervo.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  -H 'x-clervo-funding: paid' \
  -d '{"model":"quickai/gpt-5.6-luna","messages":[{"role":"user","content":"Hello"}],"max_completion_tokens":128}'
```

### GPT 5.6 Terra (QuickAI label) — quickai/gpt-5.6-terra

Provider-reported model label observed in a bounded authenticated QuickAI test.

- Capabilities: text, json
- Typical latency: 3000ms
- Price: $0.0180 per request
- Max input: 20000 characters
- Max output: 1024 tokens

```bash
curl -sS https://api.clervo.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  -H 'x-clervo-funding: paid' \
  -d '{"model":"quickai/gpt-5.6-terra","messages":[{"role":"user","content":"Hello"}],"max_completion_tokens":128}'
```

### GPT 5.6 Sol (QuickAI label) — quickai/gpt-5.6-sol

Provider-reported model label observed in a bounded authenticated QuickAI test.

- Capabilities: text, json
- Typical latency: 3000ms
- Price: $0.0350 per request
- Max input: 20000 characters
- Max output: 1024 tokens

```bash
curl -sS https://api.clervo.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  -H 'x-clervo-funding: paid' \
  -d '{"model":"quickai/gpt-5.6-sol","messages":[{"role":"user","content":"Hello"}],"max_completion_tokens":128}'
```

### Claude Haiku 4.5 — tongkhokr/claude-haiku-4.5

Fast affordable Claude model. 10% below BlockRun pricing.

- Capabilities: text, json, fast
- Typical latency: 1017ms
- Price: $0.0020 per request
- Max input: 20000 characters
- Max output: 4096 tokens

```bash
curl -sS https://api.clervo.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  -H 'x-clervo-funding: paid' \
  -d '{"model":"tongkhokr/claude-haiku-4.5","messages":[{"role":"user","content":"Hello"}],"max_completion_tokens":128}'
```

### Claude Sonnet 5 — tongkhokr/claude-sonnet-5

Balanced Claude model. 10% below BlockRun pricing.

- Capabilities: text, json, reasoning, code
- Typical latency: 2600ms
- Price: $0.0150 per request
- Max input: 20000 characters
- Max output: 4096 tokens

```bash
curl -sS https://api.clervo.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  -H 'x-clervo-funding: paid' \
  -d '{"model":"tongkhokr/claude-sonnet-5","messages":[{"role":"user","content":"Hello"}],"max_completion_tokens":128}'
```

### Claude Opus 5 — tongkhokr/claude-opus-5

Most powerful Claude model. 10% below BlockRun pricing.

- Capabilities: text, json, reasoning, code
- Typical latency: 2700ms
- Price: $0.0840 per request
- Max input: 20000 characters
- Max output: 4096 tokens

```bash
curl -sS https://api.clervo.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  -H 'x-clervo-funding: paid' \
  -d '{"model":"tongkhokr/claude-opus-5","messages":[{"role":"user","content":"Hello"}],"max_completion_tokens":128}'
```

### Claude Sonnet 4.6 — tongkhokr/claude-sonnet-4.6

Balanced Claude model. Great for coding and reasoning.

- Capabilities: text, json, reasoning, code
- Typical latency: 2500ms
- Price: $0.0150 per request
- Max input: 20000 characters
- Max output: 4096 tokens

```bash
curl -sS https://api.clervo.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  -H 'x-clervo-funding: paid' \
  -d '{"model":"tongkhokr/claude-sonnet-4.6","messages":[{"role":"user","content":"Hello"}],"max_completion_tokens":128}'
```

### Claude Opus 4.7 — tongkhokr/claude-opus-4.7

Powerful Claude for complex reasoning. 1M context.

- Capabilities: text, json, reasoning, code
- Typical latency: 2800ms
- Price: $0.0840 per request
- Max input: 20000 characters
- Max output: 4096 tokens

```bash
curl -sS https://api.clervo.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  -H 'x-clervo-funding: paid' \
  -d '{"model":"tongkhokr/claude-opus-4.7","messages":[{"role":"user","content":"Hello"}],"max_completion_tokens":128}'
```

### Claude Opus 4.8 — tongkhokr/claude-opus-4.8

Anthropic Claude Opus 4.8 via TongKhokr gateway. 10% below BlockRun pricing.

- Capabilities: text, json, reasoning, code
- Typical latency: 2000ms
- Price: $0.0840 per request
- Max input: 20000 characters
- Max output: 4096 tokens

```bash
curl -sS https://api.clervo.dev/v1/chat/completions \
  -H 'content-type: application/json' \
  -H 'x-clervo-funding: paid' \
  -d '{"model":"tongkhokr/claude-opus-4.8","messages":[{"role":"user","content":"Hello"}],"max_completion_tokens":128}'
```

## Integrations

### MCP (Claude Code / Cursor)
```bash
npx @clervo/mcp
```

### TypeScript SDK
```typescript
import { Clervo } from '@clervo/sdk';
const ai = new Clervo();
const result = await ai.chat('groq/llama-3.1-8b-instant', 'Hello');
```

### OpenAI SDK (base URL swap)
```typescript
import OpenAI from 'openai';
const client = new OpenAI({ baseURL: 'https://api.clervo.dev/v1', apiKey: 'unused' });
const res = await client.chat.completions.create({ model: 'groq/llama-3.1-8b-instant', messages: [{ role: 'user', content: 'Hello' }] });
```

### Python (requests)
```python
import requests
r = requests.post("https://api.clervo.dev/v1/chat/completions", json={
    "model": "groq/llama-3.1-8b-instant",
    "messages": [{"role": "user", "content": "Hello"}]
})
print(r.json()["choices"][0]["message"]["content"])
```

## Pricing Comparison (vs BlockRun)

| Service | BlockRun | Clervo | Savings |
|---------|----------|--------|---------|
| Minimum paid call | $0.003 | $0.002 | 33% |
| Web search | $0.012 | FREE | 100% |
| Web scrape | N/A | FREE | ∞ |
| Claude Haiku 4.5 | ~$0.003 | $0.002 | 33% |
| GPT-5.4-mini | ~$0.010 | $0.005 | 50% |
| Llama 3.1 8B | ~$0.003 | FREE | 100% |

## x402 Payment Flow

1. Agent sends request with `x-clervo-funding: paid`
2. Clervo returns HTTP 402 with `PAYMENT-REQUIRED` header containing price and wallet
3. Agent signs USDC transfer on Base (Coinbase AgentKit, MetaMask, any EVM wallet)
4. Agent resends request with `PAYMENT-SIGNATURE` header
5. Clervo verifies payment via CDP facilitator
6. Clervo executes the AI call and returns the response
7. USDC settles to Clervo wallet (~2 seconds)

## Features

- OpenAI-compatible API format
- x402 v2 payment protocol
- Idempotency keys for safe retries
- Operation tracking and receipts
- No accounts, no API keys, no KYC
- Structured JSON error responses
- Request replay protection

## Links

- Website: https://clervo.dev
- API: https://api.clervo.dev
- MCP: https://www.npmjs.com/package/@clervo/mcp
- SDK: https://www.npmjs.com/package/@clervo/sdk
- Status: Live