Quickstart - Velobase

Velobase is an AI gateway first: point your existing OpenAI or Anthropic SDK at it, and every model call is billed to one of your end-customers’ wallets. It is also a billing ledger (freeze, consume, deduct) for work you price yourself. This quickstart covers the gateway path first, then the billing ledger primitives.

Get your API key

Sign in to the Velobase Dashboard.
Create a project if you haven’t already.
Go to Keys and generate a new key.

You can create two kinds of keys:

vb_live_ is a project key. Use it server-side and tell Velobase who to bill with the X-Velobase-Customer: <user-id> header.
vb_customer_ is a customer-scoped key. It carries its own customer binding, so no header is needed.

Fund a customer wallet

Add funds to a customer’s wallet. If the customer does not exist yet, Velobase creates them automatically.Amounts use explicit unit fields: amount_usd, amount_cents, or amount_credits, where 1 USD = 100 cents = 1,000,000 credits. Prefer amount_usd.

curl -X POST https://api.velobase.io/v1/customers/deposit \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "user_123",
    "amount_usd": 1.00
  }'

Make a model call

Point your OpenAI or Anthropic SDK at https://api.velobase.io/v1 and pass X-Velobase-Customer to say which wallet to bill. Velobase is model-agnostic: live models include deepseek/deepseek-v4-pro (supports streaming) and the anthropic/claude-* family such as anthropic/claude-opus-4.8, anthropic/claude-sonnet-4.6, and anthropic/claude-haiku-4.5 (served on Bedrock, non-streaming). More are available via upstreams.

curl -X POST https://api.velobase.io/v1/chat/completions \
  -H "Authorization: Bearer your_api_key_here" \
  -H "X-Velobase-Customer: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek/deepseek-v4-pro",
    "messages": [{ "role": "user", "content": "Hello!" }]
  }'

from openai import OpenAI

client = OpenAI(
    base_url="https://api.velobase.io/v1",
    api_key="your_api_key_here",
)

resp = client.chat.completions.create(
    model="deepseek/deepseek-v4-pro",
    messages=[{"role": "user", "content": "Hello!"}],
    extra_headers={"X-Velobase-Customer": "user_123"},
)
print(resp.choices[0].message.content)

Velobase forwards the request upstream, settles the real token cost against the customer’s wallet, and returns per-call billing details in the response headers:

x-velobase-cost-cents and x-velobase-cost-credits: what this call cost.
x-velobase-balance-credits: the wallet balance after the call.
x-velobase-transaction-id: the ledger transaction for this call.

You can list available models with GET /v1/models and review aggregated spend with GET /v1/usage.

Bill work you price yourself (optional)

For work that is not a model call (for example image generation or a fixed-price feature), use the billing ledger primitives directly. Charge a customer in two ways:

Use direct deduction when the cost is known upfront.
Use staged deduction when the final cost is only known after execution.

Option A: Direct deduction
Option B: Staged deduction

Use this for fixed-price operations such as image generation or a known API call cost.

curl -X POST https://api.velobase.io/v1/billing/deduct \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "user_123",
    "transaction_id": "img_gen_001",
    "amount_usd": 0.20
  }'

This deducts $0.20 immediately.

Use this when you only know the maximum budget before the task starts.Freeze first

curl -X POST https://api.velobase.io/v1/billing/freeze \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "user_123",
    "transaction_id": "llm_task_001",
    "amount_usd": 0.20
  }'

This reserves $0.20 before the task starts.Consume the actual cost

curl -X POST https://api.velobase.io/v1/billing/consume \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "llm_task_001",
    "actual_amount_usd": 0.12
  }'

Velobase consumes

0.12 and automatically returns the remaining

0.08.If the task is cancelled, call unfreeze instead of consume.

Check the wallet

curl https://api.velobase.io/v1/customers/user_123 \
  -H "Authorization: Bearer your_api_key_here"

Response:

{
  "id": "user_123",
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "metadata": {},
  "wallets": {
    "default": {
      "total": 1000000,
      "used": 120000,
      "frozen": 0,
      "available": 880000,
      "sources": [
        {
          "source": "deposit",
          "total": 1000000,
          "used": 120000,
          "frozen": 0,
          "available": 880000,
          "starts_at": null,
          "expires_at": null
        }
      ]
    }
  },
  "created_at": "2026-06-17T00:00:00Z"
}

Wallet amounts are reported in credits (1,000,000 credits = 1 USD).

SDKs

Prefer a typed client? Install the Velobase billing SDK and pin the version:

pip install "velobase-billing>=0.2.1"

npm i @velobaseai/billing@^1.1.1

Next steps

Funding wallets

Wallet categories, validity periods, and balance breakdown.

Direct deduction

Charge immediately when cost is known.

Staged deduction

Freeze first, then settle the actual cost.

API reference

Complete endpoint reference.

​SDKs

​Next steps

Funding wallets

Direct deduction

Staged deduction

API reference

SDKs

Next steps