# Gondola

> Gondola is a DIEM yield marketplace built on Venice AI. DIEM holders ("lenders") deposit a Venice inference API key, set a per-token price, and earn USDC on what would otherwise be idle daily allowance. Buyers hit an OpenAI-compatible gateway and pay per request in USDC on Base. A broker routes each request to the cheapest available lender key, meters usage, and settles off-chain.

Site: https://gondola-ai.com

## Key concepts

- **DIEM**: Venice's staked-compute allowance. 1 staked DIEM is roughly $1 per day of inference. Once staked it produces a daily allowance that resets at midnight UTC.
- **Lender**: a Base wallet that deposits a Venice INFERENCE API key and sets a single price factor against Venice's list price. Gondola routes paid inference to the key and credits USDC for every request served.
- **Buyer**: a Base wallet that tops up a USDC balance and calls the OpenAI-compatible gateway. Each request debits the actual metered cost of the model used.
- **Broker**: Gondola itself. It selects the cheapest healthy lender for each request, meters token usage, and settles balances off-chain. Top-ups and payouts happen on-chain in USDC on Base.
- **Fees**: symmetric and small. Buyers pay the posted price plus a platform fee of up to 2 percent; lenders receive the posted price minus a platform fee of up to 2 percent. The broker keeps the spread. No subscriptions. Payouts have a small minimum to avoid gas-draining tiny withdrawals.

## API

OpenAI-compatible. Base URL: https://api.gondola-ai.com/v1

Anthropic-compatible too: POST /v1/messages implements the Anthropic Messages API (streaming, tool use, count_tokens), so Claude Code and the Anthropic SDK work with ANTHROPIC_BASE_URL=https://api.gondola-ai.com (no /v1 suffix; the SDK adds the path).

Authenticate with a Gondola key (`gnd_live_...`) in the `Authorization: Bearer` header, exactly as you would with OpenAI. The Anthropic surface also accepts the key in `x-api-key`.

Balance visibility: successful responses and insufficient-balance 402s on the paid endpoints carry an `x-gondola-balance` header, your remaining Gondola balance in USD as a plain decimal string, plus `x-gondola-balance-warning: low` when it is running low. The value is the spendable wallet-level Gondola balance at the moment the response was built. During streamed responses the in-flight request's hold may still be excluded, so treat it as a lower bound. It is not a per-key spend limit, and a missing header means the balance was unknown for that response, never that it is zero. For polling, use `GET /v1/balance`.

## Accountless / agent access (x402)

No account, no API key: pay per request with USDC on Base via the x402 protocol (HTTP 402). Call `POST /v1/chat/completions`, `POST /v1/images/generations`, or `POST /v1/messages` with no Authorization header and the response is a `402` whose body carries x402 `accepts` payment requirements priced for that exact request. Retry with a signed `X-PAYMENT` authorization (any x402 client, e.g. x402-fetch) and the request is served; the receipt rides back in the `X-PAYMENT-RESPONSE` header. Payments settle to Gondola and credit the paying wallet's balance first, so any amount above the metered cost is not lost: it stays as spendable credit for that wallet's next paid request, and signing in at https://gondola-ai.com with the same wallet shows and spends the same balance. `POST /api/buyer/x402-topup` (site host, not the api host) accepts an x402 payment as a plain balance top-up (optional JSON body `{"amount": 20}`). Video endpoints are Bearer-only for now.

Live endpoints:

- `POST /v1/chat/completions` - text chat (streaming and non-streaming)
- `POST /v1/images/generations` - image generation
- `POST /v1/images/edits` - image editing (inpaint models)
- `POST /v1/images/upscale` - image upscaling (base64 image in, raw upscaled bytes out; scale 2 or 4, fixed price per scale)
- `POST /v1/video/quote` - price a video generation before queuing (video pricing is dynamic per model, duration, and resolution; upscale models quote from a video_url plus upscale_factor)
- `POST /v1/video/queue` - submit an async video generation; returns a job id. Modes by model: text-to-video, image-to-video (image_url), transition (image_url + end_image_url), reference-to-video (reference_image_urls, up to 9), video-to-video and video upscale (video_url, https only)
- `POST /v1/video/retrieve` - poll a video job by id (JSON status while processing, raw mp4 bytes when done; the clip stays retrievable until the client acknowledges delivery or is cleaned up within about a day)
- `GET /v1/models` - public, no auth required. Returns every callable model with its modality, target endpoint, capability fields, and a fee-inclusive "from" price for the cheapest active offer where one exists. Video models are quote-priced: get the exact price from `POST /v1/video/quote`.
- `GET /v1/balance` - your current Gondola balance as JSON (`balance_usd`, `low_balance`), for polling and automated top-ups. Bearer or `x-api-key` auth.

Planned (not yet implemented): `/v1/embeddings`, `/v1/audio/speech`, `/v1/audio/transcriptions`.

## Market data

Public, no auth, aggregate-only read endpoints for research and analytics (CORS-enabled, JSON, ~60s cached). All amounts are USD unless the field name says otherwise; all timestamps are ISO-8601 UTC; every response echoes an `as_of` marker and the resolved `window`. Numbers cover paid traffic only. No wallet, buyer, or lender identity is ever exposed: results are day/model buckets, sums, and distinct counts.

- `GET /v1/market/realization?since=YYYY-MM-DD&until=YYYY-MM-DD&model=<id>` - per (day, model) settled aggregate: `lender_received_usd` (USDC the lender actually received), `diem_consumed` (Venice list face in DIEM units; 1 DIEM ~= $1/day of capacity), and `requests`. Realization vs Venice list = `lender_received_usd / diem_consumed`. Top-level `diem_spot_usd` gives the DIEM token price for a token-value view. `day` is the request-start UTC day. `since`/`until` are optional (default last 30 days, max 90-day span); `model` filters to one id.
- `GET /v1/market/daily?since=YYYY-MM-DD&until=YYYY-MM-DD` - marketplace-wide daily totals: `volume_usd` (fee-inclusive buyer charge), `requests`, `fees_usd` (broker spread), `lender_received_usd`, `diem_consumed`, `active_lenders`, `active_buyers`.
- `GET /v1/market/models?window=24h|7d` - per-model activity: `volume_usd` and `requests` over the window, the cheapest fee-inclusive offer price (`best_input_usd_per_1m_tokens` / `best_output_usd_per_1m_tokens`), and the Venice list price (`venice_list_input_usd_per_1m_tokens` / `venice_list_output_usd_per_1m_tokens`). Price fields are null for non-token models (image, video); each row carries `modality` and `price_unit`.

Example:

```python
from openai import OpenAI

client = OpenAI(base_url="https://api.gondola-ai.com/v1", api_key="gnd_live_...")
resp = client.chat.completions.create(
    model="llama-3.3-70b",
    messages=[{"role": "user", "content": "Ciao"}],
)
print(resp.choices[0].message.content)
```

## Links

- Home: https://gondola-ai.com
- Chat playground: https://gondola-ai.com/chat
- Marketplace (public board of lender offers and prices): https://gondola-ai.com/marketplace
- Lend (deposit a Venice key and earn): https://gondola-ai.com/lend
- API keys (Wallet, API keys tab): https://gondola-ai.com/wallet?tab=keys
- Characters: https://gondola-ai.com/characters
- Setup guides (connect any OpenAI-compatible tool to Gondola): https://gondola-ai.com/guides
- Guide, Claude Code: https://gondola-ai.com/guides/claude-code
- Guide, Cursor: https://gondola-ai.com/guides/cursor
- Guide, Cline: https://gondola-ai.com/guides/cline
- Guide, Aider: https://gondola-ai.com/guides/aider
- Guide, OpenCode: https://gondola-ai.com/guides/opencode
- Guide, Continue: https://gondola-ai.com/guides/continue
- Guide, SillyTavern: https://gondola-ai.com/guides/sillytavern
- Guide, OpenClaw: https://gondola-ai.com/guides/openclaw
- X (updates and announcements): https://x.com/gondolamarket
- Privacy: https://gondola-ai.com/privacy
- Terms: https://gondola-ai.com/terms
- Built on Venice AI: https://venice.ai