# Clervo x402 Gateway — Claude Code Skill

> Use this skill to call AI models and web services through Clervo's x402 payment gateway.

## What is Clervo?

Clervo is an OpenAI-compatible AI gateway on Base mainnet. One wallet, many models.
Free models need no payment. Paid models use x402 (USDC on Base, auto-settled).

## Available Actions

### 1. Chat Completion (free models — no payment needed)

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

Free models: `clervo/fast`, `clervo/smart`, `clervo/deep`, `groq/llama-3.1-8b-instant`, `groq/llama-3.3-70b`, `groq/qwen3.6-27b`, `groq/gpt-oss-120b`, `groq/gpt-oss-20b`, `sambanova/llama-3.3-70b`, `nvidia/nemotron-ultra-550b`, `nvidia/nemotron-super-120b`, `nvidia/nemotron-nano-30b`, `nvidia/deepseek-v4-flash`

### 2. Web Search (free)

```bash
curl -sS https://api.clervo.dev/v1/search \
  -H 'content-type: application/json' \
  -d '{"query":"x402 protocol specification"}'
```

### 3. Web Scrape (free)

```bash
curl -sS https://api.clervo.dev/v1/scrape \
  -H 'content-type: application/json' \
  -d '{"url":"https://example.com"}'
```

### 4. Audio Transcription / Speech-to-Text (free)

```bash
curl -sS https://api.clervo.dev/v1/audio/transcriptions \
  -F file=@audio.mp3 \
  -F model=whisper-large-v3
```

Supports: mp3, mp4, wav, ogg, flac, webm. Max 25MB. Returns `{"text": "transcribed text"}`.

### 4. Chat Completion (paid models — x402 payment)

Paid models: `clervo/code`, `quickai/gpt-5.4-mini`, `quickai/gpt-5.4`, `quickai/gpt-5.5`, `quickai/gpt-5.6-luna`, `quickai/gpt-5.6-terra`, `quickai/gpt-5.6-sol`, `tongkhokr/claude-haiku-4.5`, `tongkhokr/claude-sonnet-5`, `tongkhokr/claude-opus-5`

To use paid models, send the request and handle the 402 response:
1. POST request → receive 402 with payment details
2. Sign USDC payment on Base (eip155:8453)
3. Resend with payment proof → receive completion

Use `@clervo/sdk` for automatic payment handling:
```javascript
import { ClervoClient } from '@clervo/sdk';
const client = new ClervoClient({ walletPrivateKey: process.env.WALLET_KEY });
const result = await client.chat({ model: 'clervo/code', messages: [{role: 'user', content: 'Hello'}] });
```

## Model Aliases

| Alias | Routes To | Speed | Use For |
|-------|-----------|-------|---------|
| `clervo/fast` | groq/llama-3.1-8b-instant | 170ms | Simple tasks, classification, extraction |
| `clervo/smart` | groq/llama-3.3-70b | 475ms | General reasoning, instruction following |
| `clervo/code` | tongkhokr/claude-sonnet-5 | 2.6s | Code generation (paid, $0.015/call) |
| `clervo/deep` | nvidia/nemotron-ultra-550b | ~1s | Deep reasoning, complex analysis |

## Key Facts

- Base URL: `https://api.clervo.dev`
- Payment network: Base mainnet (eip155:8453)
- Payment token: USDC
- Protocol: x402 v2
- No API keys needed for free models
- OpenAI-compatible request/response format
- 13 free models, 13 paid models
- 5 services: chat, search, scrape, transcription, paid chat

## Discovery

- Models: https://api.clervo.dev/v1/models
- OpenAPI: https://api.clervo.dev/openapi.json
- Agent discovery: https://api.clervo.dev/agent.json
- x402 info: https://api.clervo.dev/.well-known/x402.json