@clervo/sdk

@clervo/sdk

TypeScript/JavaScript SDK for the Clervo x402 Gateway.

23 AI models. 8 free. Pay per call in USDC on Solana. No API keys.

Install

npm install @clervo/sdk

Quick start

import { Clervo } from '@clervo/sdk';

const clervo = new Clervo();

// Free call — no wallet needed
const response = await clervo.chat('groq/llama-3.1-8b-instant', 'Explain recursion in 2 sentences');
console.log(response);

// List all models
const models = await clervo.models();
const free = models.filter(m => m.lifecycle === 'free_beta');
console.log(`${free.length} free models available`);

Free models

No payment, no wallet, no signup:

Model	Speed	Best for
groq/llama-3.1-8b-instant	170ms	Fast responses
groq/llama-3.3-70b	~800ms	Strong general
sambanova/deepseek-v3.2	1.6s	Reasoning
sambanova/llama-3.3-70b	1.5s	General
hcn/qwen3.6-35b	0.9s	Fast small
hcn/step-3.7-flash	3s	Reasoning
hcn/deepseek-v4-pro	9s	Deep reasoning
hcn/auto	3s	Auto-routed

Paid models (10-20% cheaper than BlockRun)

Fund a Solana wallet with USDC. x402 protocol handles payment automatically.

Model	Price/req
tongkhokr/claude-haiku-4.5	$0.002
tongkhokr/claude-sonnet-5	$0.015
tongkhokr/claude-opus-5	$0.084
quickai/gpt-5.4-mini	$0.005
quickai/gpt-5.5	$0.035

API

new Clervo(options?)

Option	Default	Description
apiUrl	https://api.clervo.dev	API base URL

clervo.chat(model, message, options?)

Simple chat. Returns the text response.

const text = await clervo.chat('groq/llama-3.1-8b-instant', 'Hello!');

clervo.chatCompletion(model, messages, options?)

Full OpenAI-compatible chat completion.

const result = await clervo.chatCompletion('sambanova/deepseek-v3.2', [
  { role: 'system', content: 'You are helpful.' },
  { role: 'user', content: 'What is 2+2?' }
]);
console.log(result.choices[0].message.content);
console.log(result.usage);

clervo.models()

List all available models.

clervo.freeModels()

List only free models.

clervo.operation(operationId)

Look up an operation by ID (from _operationId on completion results).

OpenAI drop-in replacement

Since Clervo is OpenAI-compatible, you can also use the OpenAI SDK:

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.clervo.dev/v1',
  apiKey: 'unused', // no key needed for free models
});

const response = await client.chat.completions.create({
  model: 'groq/llama-3.1-8b-instant',
  messages: [{ role: 'user', content: 'Hello!' }],
});

Links

• API: https://api.clervo.dev
• Models: https://api.clervo.dev/v1/models
• Quickstart: https://api.clervo.dev/quickstart.md
• OpenAPI: https://api.clervo.dev/openapi.json