Quickstart

Call an AI model in one request. No signup, no keys.

1. Call a free model

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

2. Response

{
  "id": "chatcmpl-abc123",
  "model": "clervo/fast",
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "x402 is an HTTP-native payment protocol..."
    },
    "finish_reason": "stop"
  }]
}

3. Add idempotency

For safe retries, add an idempotency key:

curl https://api.clervo.dev/v1/chat/completions \
  -H "content-type: application/json" \
  -H "idempotency-key: my-unique-id-001" \
  -d '{"model":"clervo/smart","messages":[{"role":"user","content":"Summarize."}]}'

Replaying the same key + body returns the cached response. Header x-idempotent-replay: true confirms replay.

Free Models

12 models, no payment. Just call.

Free models use the same endpoint. No headers beyond content-type.

Available: clervo/fast, clervo/smart, clervo/deep, groq/llama-3.1-8b-instant, groq/llama-3.3-70b, sambanova/deepseek-v3.2, sambanova/llama-3.3-70b, hcn/qwen3.6-35b, hcn/step-3.7-flash, hcn/deepseek-v4-pro, hcn/auto, clervo/search

Paid Models (x402)

Pay per request in USDC on Solana. No accounts.

1. Request with funding header

curl -D - 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"}]}'

2. Receive 402 with payment details

Response includes PAYMENT-REQUIRED header with amount, address, and token info.

3. Sign and pay

Your wallet signs the USDC transfer. Replay with the signature:

curl https://api.clervo.dev/v1/chat/completions \
  -H "content-type: application/json" \
  -H "x-clervo-funding: paid" \
  -H "payment-signature: <base64-signed-payload>" \
  -d '{"model":"tongkhokr/claude-haiku-4.5","messages":[{"role":"user","content":"Hello"}]}'

4. Receive response

Payment verified, model called, completion returned.

Payment details: Chain: Solana mainnet. Token: USDC. Facilitator: Coinbase CDP. Scheme: exact.

Endpoints

Base URL: https://api.clervo.dev

POST/v1/chat/completions

Chat completions

GET/v1/models

List models

GET/v1/catalog

Detailed catalog

GET/v1/operations/{id}

Operation status

POST/v1/search

Web search

GET/healthz

Health check

Request Format

OpenAI-compatible chat completions.

{
  "model": "clervo/fast",
  "messages": [
    {"role": "user", "content": "Hello"}
  ],
  "max_completion_tokens": 256,
  "temperature": 0.7
}

Headers

Header	Required	Description
`content-type`	Yes	application/json
`idempotency-key`	Recommended	Unique key for safe retries
`x-clervo-funding`	Paid only	Set to "paid" for x402 flow
`payment-signature`	Paid only	Signed payment payload

Response Format

Response headers

Header	Description
`x-clervo-operation-id`	Durable operation ID
`x-idempotent-replay`	true if cached replay
`x-clervo-model`	Actual model used
`x-clervo-latency-ms`	Provider call time

Idempotency

Every call supports safe retries.

Include idempotency-key header with a unique string
Replay same key + body returns cached response
No duplicate charges for paid calls
Same key with different body returns 409 Conflict

Errors

Status	Meaning
200	Success
400	Invalid request
402	Payment required (x402 challenge)
404	Model not found
409	Idempotency key conflict
429	Rate limited
502	Upstream provider error

Discovery

Agents find Clervo automatically.

# x402 discovery
curl https://api.clervo.dev/.well-known/x402.json

# Agent manifest
curl https://api.clervo.dev/agent.json

# LLM-readable description
curl https://api.clervo.dev/llms.txt

# OpenAPI spec
curl https://api.clervo.dev/openapi.json