Documentation

# 1. Register and get your API key
curl -X POST https://api.clusterprotocol.ai/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com", "password": "securepassword"}'

# Response:
# { "userId": "abc123", "email": "dev@example.com",
#   "apiKey": "sk-cluster-...", "balance": "0.00" }

# 2. Run your first inference
curl https://api.clusterprotocol.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-cluster-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.1-70b",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

POST /api/auth/register
Content-Type: application/json

{
  "email": "dev@example.com",
  "password": "securepassword"
}

curl https://api.clusterprotocol.ai/api/auth/me \
  -H "Authorization: Bearer sk-cluster-YOUR_KEY"

# No auth header → triggers 402
curl -i -X POST https://api.clusterprotocol.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "llama-3.3-70b-instruct", "messages": [{"role": "user", "content": "Hello"}]}'

# HTTP/2 402
# payment-required: <base64-encoded JSON>

import { fetchWithPayment } from "@x402/fetch";
import { CdpWallet } from "@coinbase/cdp-sdk";

// Create a wallet on Base mainnet
const wallet = await CdpWallet.create({ networkId: "base-mainnet" });

// fetchWithPayment handles 402 → sign → resubmit automatically
const response = await fetchWithPayment(
  "https://api.clusterprotocol.ai/v1/chat/completions",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      model: "llama-3.3-70b-instruct",
      provider: "venice",  // optional: route through Venice
      messages: [{ role: "user", content: "Hello!" }]
    })
  },
  wallet  // signs USDC payment on Base
);

console.log(await response.json());

import { fetchWithPayment } from "@x402/fetch";
import { ethers } from "ethers";

// Any EVM wallet works (MetaMask, Coinbase, etc.)
const wallet = new ethers.Wallet("YOUR_PRIVATE_KEY");

// Venice private inference via x402 — no API key needed
const response = await fetchWithPayment(
  "https://api.clusterprotocol.ai/v1/chat/completions",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      model: "llama-3.3-70b-instruct",
      provider: "venice",  // ← routes to Venice (E2EE, no logs)
      messages: [
        { role: "user", content: "Explain ERC-7710 delegation" }
      ],
      max_tokens: 512
    })
  },
  wallet  // signs $0.003 USDC on Base automatically
);

const data = await response.json();
console.log(data.choices[0].message.content);

npm install @x402/fetch ethers
# or with Coinbase CDP:
npm install @x402/fetch @coinbase/cdp-sdk

Your Agent/App            Cluster Protocol            Base Chain (L2)
      │                           │                          │
      ├── POST /v1/chat ────────►│                          │
      │   (no auth header)        │                          │
      │                           │                          │
      │◄── HTTP 402 ─────────────┤                          │
      │    payment-required:      │                          │
      │    {amount: 3000,         │                          │
      │     network: eip155:8453, │                          │
      │     payTo: 0x6839...}     │                          │
      │                           │                          │
      ├── Sign EIP-3009 ─────────────────────────────────► │
      │   (USDC transferWithAuth) │                          │
      │                           │                          │
      ├── POST /v1/chat ────────►│                          │
      │   X-PAYMENT: <signed>     │── verify on-chain ─────►│
      │                           │                          │
      │◄── HTTP 200 ─────────────┤                          │
      │    {choices: [...]}       │                          │
      │    (Venice E2EE response) │                          │

curl -X POST https://api.clusterprotocol.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-cluster-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.3-70b-instruct",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Explain quantum computing in 2 sentences."}
    ],
    "temperature": 0.7,
    "max_tokens": 256
  }'

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1714000000,
  "model": "llama-3.1-70b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Quantum computing uses qubits that can exist in superposition..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 42,
    "total_tokens": 70
  }
}

curl -X POST https://api.clusterprotocol.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-cluster-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.1-70b",
    "messages": [{"role": "user", "content": "Write a haiku about AI"}],
    "stream": true
  }'

# Response (SSE):
# data: {"id":"chatcmpl-abc","choices":[{"delta":{"content":"Silicon"}}]}
# data: {"id":"chatcmpl-abc","choices":[{"delta":{"content":" dreams"}}]}
# data: {"id":"chatcmpl-abc","choices":[{"delta":{"content":" awaken"}}]}
# ...
# data: [DONE]

curl -X POST https://api.clusterprotocol.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-cluster-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.3-70b-instruct",
    "provider": "venice",
    "messages": [
      {"role": "user", "content": "Explain zero-knowledge proofs simply."}
    ],
    "temperature": 0.7,
    "max_tokens": 256
  }'

curl -X POST https://api.clusterprotocol.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.3-70b-instruct",
    "provider": "venice",
    "messages": [
      {"role": "user", "content": "Analyze this financial data privately..."}
    ],
    "temperature": 0.7,
    "max_tokens": 1024
  }'

import { fetchWithPayment } from "@x402/fetch";
import { ethers } from "ethers";

const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!);

// Private Venice inference — no API key, no account, wallet pays $0.003
const response = await fetchWithPayment(
  "https://api.clusterprotocol.ai/v1/chat/completions",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      model: "llama-3.3-70b-instruct",
      provider: "venice",
      messages: [{ role: "user", content: "What are ERC-7710 delegations?" }],
      max_tokens: 512
    })
  },
  wallet
);

const data = await response.json();
console.log(data.choices[0].message.content);

{
  "id": "chatcmpl-RUpKyiqi14G6MrwbPrOk7iJs",
  "object": "chat.completion",
  "model": "llama-3.3-70b",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "..." },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 1507, "completion_tokens": 42, "total_tokens": 1549 },
  "venice_parameters": {
    "enable_e2ee": true,
    "include_venice_system_prompt": true,
    "strip_thinking_response": false
  }
}

curl -X POST https://api.clusterprotocol.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.3-70b-instruct",
    "provider": "phala",
    "messages": [
      {"role": "user", "content": "Process this sensitive medical record..."}
    ],
    "max_tokens": 1024
  }'

import { fetchWithPayment } from "@x402/fetch";
import { ethers } from "ethers";

const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!);

// Hardware-private inference via x402 — no API key needed
const response = await fetchWithPayment(
  "https://api.clusterprotocol.ai/v1/chat/completions",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      model: "llama-3.3-70b-instruct",
      provider: "phala",
      messages: [{ role: "user", content: "Analyze this contract..." }],
      max_tokens: 1024
    })
  },
  wallet
);

const data = await response.json();
console.log(data.choices[0].message.content);

curl https://api.clusterprotocol.ai/api/models/public

curl -X POST https://api.clusterprotocol.ai/api/models/upload \
  -H "Authorization: Bearer sk-cluster-YOUR_KEY" \
  -F "file=@my-model.safetensors" \
  -F "name=my-custom-model" \
  -F "category=chat" \
  -F "description=A fine-tuned model for customer support"

curl -X POST https://api.clusterprotocol.ai/api/finetune/jobs \
  -H "Authorization: Bearer sk-cluster-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "baseModel": "llama-3.1-8b",
    "trainingFile": "https://example.com/data.jsonl",
    "suffix": "customer-support-v1",
    "epochs": 3,
    "learningRate": 2e-5,
    "loraRank": 16,
    "loraAlpha": 32
  }'

curl https://api.clusterprotocol.ai/api/user/stats \
  -H "Authorization: Bearer sk-cluster-YOUR_KEY"

const ws = new WebSocket("wss://api.clusterprotocol.ai/ws/admin");

ws.onopen = () => {
  console.log("Connected to cluster events");
  // Authenticate
  ws.send(JSON.stringify({
    type: "auth",
    token: "sk-cluster-YOUR_KEY"
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log("Event:", data.type, data);
};

ws.onclose = () => console.log("Disconnected");

from cluster_sdk import ClusterClient

client = ClusterClient(api_key="sk-cluster-YOUR_KEY")

# List models
models = client.models.list()
for m in models:
    print(f"{m.id}: {m.name}")

# Chat completion
response = client.chat.completions.create(
    model="llama-3.1-70b",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)