> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velobase.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Copy for AI

> One prompt that teaches your AI assistant the whole Velobase API. Paste it into Cursor or Claude Code and ask it to wire up the integration.

Paste the block below into your AI coding assistant (Cursor, Claude Code, etc.),
then tell it what to build. It covers the full surface: the model gateway, the
customer wallets, and the billing primitives, with every endpoint, its purpose,
and the units, so the assistant can write a correct integration in one shot.

<Note>
  Replace `vb_live_...` with a real project key from **Dashboard → Keys**, and use
  your own stable user id wherever you see `user_123`.
</Note>

```text theme={null}
You are integrating Velobase into my app. Velobase is an OpenAI/Anthropic-compatible
AI gateway that bills every model call to one of MY end-customers' wallets, plus a
billing ledger for work I price myself. Use the reference below; wire up the parts I ask for.

# Setup
- Base URL: https://api.velobase.io/v1   (the OpenAI SDK base_url needs the /v1 suffix)
- Auth header: Authorization: Bearer <key>
  - vb_live_...      project key (server-side). Pick who to bill with header X-Velobase-Customer: <your-user-id>.
  - vb_customer_...  customer-scoped key (carries its own customer; no header needed).
- Amount units: amount_usd / amount_cents / amount_credits. 1 USD = 100 cents = 1,000,000 credits.
- Idempotency: pass idempotency_key (or the Idempotency-Key header) on writes; safe to retry, never double-applies.
- Errors are JSON: { "error": { "type", "message", "request_id" } }.

# Gateway: model calls, billed to the customer's wallet
- POST /v1/chat/completions   OpenAI-compatible chat completions. Send X-Velobase-Customer.
- POST /v1/messages           Anthropic-style endpoint (today returns OpenAI-shaped bodies for OpenAI-route models).
- GET  /v1/models             List the models your project can route.
- GET  /v1/usage              Per-call usage rows: cost_cents, upstream_cost_cents, tokens, model, customer_id, transaction_id, status. Supports ?customer_id= and ?limit=.
- Per-call billing comes back on response headers:
    x-velobase-cost-cents, x-velobase-cost-credits, x-velobase-balance-credits, x-velobase-transaction-id
- Streaming: OpenAI-route models (e.g. deepseek/deepseek-v4-pro) support it. Claude models route via Bedrock and do NOT support streaming yet (use stream:false for Claude).
- Available models: deepseek/deepseek-v4-pro (streaming);
    anthropic/claude-opus-4.5, claude-opus-4.6, claude-opus-4.7, claude-opus-4.8,
    claude-sonnet-4.6, claude-haiku-4.5 (non-streaming).
- Example (Python, official OpenAI SDK):
    from openai import OpenAI
    client = OpenAI(api_key="vb_live_...", base_url="https://api.velobase.io/v1",
                    default_headers={"X-Velobase-Customer": "user_123"})
    r = client.chat.completions.with_raw_response.create(
        model="deepseek/deepseek-v4-pro",
        messages=[{"role":"user","content":"Hello"}], max_tokens=256)
    print(r.parse().choices[0].message.content, r.headers.get("x-velobase-cost-cents"))

# Customers and wallets (control-plane)
- POST /v1/customers/deposit              body { customer_id, amount_usd }  fund a customer wallet (created on first deposit).
    also accepts POST /v1/customers/{id}/deposit
- GET  /v1/customers/{id}                 -> { id, name, email, metadata,
    wallets: { "<wallet>": { total, used, frozen, available,
      sources: [ { source, total, used, frozen, available, starts_at, expires_at } ] } },
    created_at }
- GET  /v1/customers/{id}/balance         -> { object:"customer.balance", balance: { totalSummary:{total,used,frozen,available}, accounts:[...] } }
- GET  /v1/customers/{id}/ledger          -> { items:[ { id, operation_type, amount, wallet, source, transaction_id, business_type, status, created_at } ], has_more, next_cursor }

# Billing primitives: for work YOU price (model calls bill automatically, you do NOT call these for them)
- POST /v1/billing/deduct     body { customer_id, transaction_id, amount }   charge a known cost now.
- POST /v1/billing/freeze     body { customer_id, transaction_id, amount }   reserve a budget before a task.
- POST /v1/billing/consume    body { transaction_id, actual_amount }         settle the actual cost; the remainder is released.
- POST /v1/billing/unfreeze   body { transaction_id }                        cancel a freeze; release everything.

# SDKs (control-plane only: deposits, balances, freeze/consume). Model calls go through the OpenAI/Anthropic SDK above.
- Python: pip install "velobase-billing>=0.2.1"
    from velobase_billing import Velobase
    vb = Velobase(api_key="vb_live_...")
    vb.customers.deposit(customer_id="user_123", amount_usd=5)
    vb.customers.get("user_123").wallets["default"].available
    vb.customers.ledger("user_123")
    vb.billing.freeze(customer_id="user_123", transaction_id="job_1", amount=50)
    vb.billing.consume(transaction_id="job_1", actual_amount=32)
- JavaScript: npm i @velobaseai/billing@^1.1.1
    import { Velobase } from "@velobaseai/billing";
    const vb = new Velobase({ apiKey: "vb_live_..." });
    await vb.customers.deposit({ customerId: "user_123", amountUsd: 5 });

# Two wallets (how the money works)
- Customer wallet: your own pricing units, what you charge your end-user. Funded by deposit.
- Project wallet: real money you prepaid Velobase via Stripe. Official models debit it for platform cost.
- A model call needs BOTH funded: 402 insufficient_funds = customer wallet empty; 402 project_balance_insufficient = top up the project wallet.

Now build what I ask for next. Default to the OpenAI SDK + X-Velobase-Customer for model calls,
and the velobase-billing SDK (or POST /v1/customers/deposit) for funding customers.
```

## What to do with it

Tell the assistant the specific task, for example:

* "Route my existing OpenAI calls through Velobase and bill each one to the signed-in user."
* "In my Stripe webhook, top up the paying customer's Velobase wallet with the amount they paid."
* "Show each user their remaining balance and a usage history in my dashboard."

For deeper reference see the [OpenAI-compatible gateway](/integration/openai-compatible),
the [Python](/integration/sdk-python) and [JavaScript](/integration/sdk-javascript) SDKs,
and [depositing credits](/integration/depositing-credits).