⌁ Guides

Claude Code

Gondola serves an Anthropic-compatible endpoint, so Claude Code and the Anthropic SDK work with a base URL change: same tools, same streaming, paid per request in USDC on Base.

Create an API key

Sign in with your Base wallet at /keys and mint a Gondola API key. Keys start with gnd_ and work in both the x-api-key header (what Claude Code sends) and as a Bearer token. Top up USDC on Base at /wallet.

Point Claude Code at Gondola

Set four environment variables and start Claude Code:

bash / zsh

export ANTHROPIC_BASE_URL=https://api.gondola-ai.com
export ANTHROPIC_API_KEY=gnd_xxxx
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-5-5
claude

PowerShell

$env:ANTHROPIC_BASE_URL = "https://api.gondola-ai.com"
$env:ANTHROPIC_API_KEY = "gnd_xxxx"
$env:ANTHROPIC_MODEL = "claude-sonnet-5"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "claude-haiku-5-5"
claude

This base URL is different

Use api.gondola-ai.com with no path at all. The Anthropic SDK appends /v1/messages itself. This is the one Gondola integration where you do not add /v1 yourself.

Set the background model

Claude Code uses a second, cheaper Haiku model for background tasks. The snippet pins it to claude-haiku-5-5, which needs Claude Code 2.1.293 or later. Older versions ask for an earlier Haiku that Gondola does not serve: update Claude Code, or set ANTHROPIC_SMALL_FAST_MODEL to another model from the catalog, such as z-ai-glm-5-3-flash. Otherwise background calls fail with model not found.

Pick your models

The catalog includes Claude models (for example claude-sonnet-5 and claude-opus-4-8) alongside open models, all priced by the marketplace. Ids must match exactly, so pull the live list:

shell

curl https://api.gondola-ai.com/v1/models

Anthropic-style dated ids like claude-sonnet-5-20260101 are accepted and resolve to the base id.

Prompt privacy

Gondola never stores prompts or completions: requests are metered, forwarded, and gone when the response finishes (the one exception, a video source clip over 18 MiB, is held privately for the length of its job; see /privacy), and Venice runs a no-logging model underneath. For zero retention on Venice-controlled infrastructure too, pick a model whose privacy field reads private on GET /v1/models. Details on /privacy.

Notes and troubleshooting

Interrupts bill fairly

Pressing Esc mid-answer aborts the upstream request. You are billed only for the tokens generated before the stop, not the full answer.

What is not supported

PDF document blocks, Anthropic server tools (their hosted web search and code execution), and extended thinking output are not available through Gondola. Regular client-side tools (file edits, shell commands, the full Claude Code toolset) work, including images in tool results on vision models.

Cap the price on unattended runs

Set ANTHROPIC_CUSTOM_HEADERS="x-gondola-max-factor: 0.6" (a value from 0 to 1) to refuse any request priced above that ceiling instead of silently paying more, useful for long agentic sessions with no one watching the meter. Omit it and a request with no cheaper capacity can fall through to Gondola's own backup key at Venice list price, flagged by an X-Gondola-House: true response header. For a hard dollar limit rather than a relative one, set ANTHROPIC_CUSTOM_HEADERS="x-gondola-max-charge-usd: 0.50" and any request whose estimated charge would exceed it is refused with a 402 (a billing_error on this surface) before anything is billed.

The endpoint also works with the Anthropic SDK directly:

TypeScript

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://api.gondola-ai.com",
  apiKey: "gnd_xxxx",
});

const msg = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello from Gondola" }],
});

If a request fails with a billing error, top up at /wallet. Model not found means the id is not in the live catalog: check /v1/models and remember the small, fast model override.

Loading page

import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic({ baseURL: "https://api.gondola-ai.com", apiKey: "gnd_xxxx", }); const msg = await client.messages.create({ model: "claude-sonnet-5", max_tokens: 1024, messages: [{ role: "user", content: "Hello from Gondola" }], });