Endpoints - Velobase

Velobase is an AI gateway first. Point your OpenAI or Anthropic SDK at https://api.velobase.io/v1 and bill every model call to an end-customer’s wallet by sending the X-Velobase-Customer: <user-id> header. It is also a billing ledger (freeze, consume, deduct) for work you price yourself. This page covers the REST surface for managing customers and their wallets, plus the billing primitives. It accepts JSON-encoded request bodies and returns JSON-encoded responses. For the model gateway itself (POST /v1/chat/completions, POST /v1/messages, GET /v1/models, GET /v1/usage), see the gateway reference. Base URL: https://api.velobase.io

All amounts in the API are integer credits. 1 credit = 1 micro-USD, so 1 USD = 1,000,000 credits. There is no cents unit anywhere in the API: fields like amount_usd, amount_cents, or amount_credits are rejected with an error. Send amount as a positive integer number of credits.

Model gateway

The gateway is OpenAI- and Anthropic-compatible. Set your SDK’s base URL to https://api.velobase.io/v1, authenticate with a project key, and name the end-customer to bill with the X-Velobase-Customer header. The call is relayed upstream and the real token cost is settled against that customer’s wallet.

Endpoint	Description
`POST /v1/chat/completions`	OpenAI-compatible chat completions. Supports streaming.
`POST /v1/messages`	Anthropic-compatible messages. Supports streaming.
`GET /v1/models`	List your project’s models. Authenticated, not billed.
`GET /v1/usage`	Per-call usage and cost records. Filter with `customer_id`, `model`, `transaction_id`, `trace_id`, `cursor`, `limit`.
`GET /v1/billing/receipts/:transaction_id`	The billing receipt for one gateway call.

Health check is unauthenticated at GET /health (no /v1 prefix). For a quick authenticated check, call GET /v1/models.

Authentication and routing

Two key types decide which customer is billed:

vb_live_ is a project key for server-side use. Pair it with X-Velobase-Customer: <user-id> to name the customer to bill.
vb_customer_ is a customer-scoped key that already carries its own customer binding, so no header is needed. It supports an allowedModels whitelist and expiresAt.

Billable endpoints require a resolvable customer (header or key binding) or return 400. Non-billable endpoints like GET /v1/models do not.

Request headers

Beyond Authorization and X-Velobase-Customer, gateway requests accept:

X-Velobase-Wallet: bill a specific wallet instead of the default credits wallet.
X-Velobase-Trace-Id: your own correlation id for this call. It is echoed back on the response and you can query it later with GET /v1/usage?trace_id=....
Idempotency-Key: a unique key per logical request. Replaying the same key returns 409 with a clear message instead of double-charging. Use a fresh key for each new request and reuse a key only when retrying the same request.

For streaming requests, the cost and usage arrive in the final standard frame of the stream (OpenAI: the last usage chunk; Anthropic: message_delta). Usage accounting works the same for streaming and non-streaming calls.

Per-call billing headers

Each billed response includes settlement details:

X-Velobase-Cost-Credits and X-Velobase-Cost-Usd: what this call cost.
X-Velobase-Balance-Credits and X-Velobase-Balance-Usd: the wallet balance after the call.
X-Velobase-Transaction-Id: the ledger transaction for this call.
X-Velobase-Trace-Id: the correlation id, echoed back if you sent one.

Models

Models are defined per project. In the dashboard you create a model with a public model id, your price, and the upstream provider key it routes to (bring your own key). There is no platform-wide model list: GET /v1/models returns exactly the models your project has configured. A model whose upstream provider key is missing returns 402 byok_key_required. Each entry from GET /v1/models includes: id, object, created, active, owned_by, display_name, description, context_window, max_output_tokens, and pricing fields input_price_per_million_credits / input_price_per_million_usd, output_price_per_million_credits / output_price_per_million_usd, cache_read_price_per_million_credits / cache_read_price_per_million_usd, cache_write_price_per_million_credits / cache_write_price_per_million_usd.

Example request

from openai import OpenAI

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

resp = client.chat.completions.create(
    model="your-model-id",  # one of your project's models, see GET /v1/models
    messages=[{"role": "user", "content": "Hello!"}],
    extra_headers={"X-Velobase-Customer": "user_987"},
)

curl https://api.velobase.io/v1/chat/completions \
  -H "Authorization: Bearer vb_live_1234567890abcdef" \
  -H "X-Velobase-Customer: user_987" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-id",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Billing receipts

Every billed gateway call writes one receipt, addressable by its transaction id (from the X-Velobase-Transaction-Id response header or a GET /v1/usage row). GET /v1/billing/receipts/:transaction_id

curl https://api.velobase.io/v1/billing/receipts/txn_abc123 \
  -H "Authorization: Bearer vb_live_1234567890abcdef"

SDKs

The Velobase JavaScript SDK wraps the customer and wallet endpoints below, plus usage.list and receipts.get. The gateway itself works with any OpenAI or Anthropic SDK.

JavaScript

npm i @velobaseai/billing@^1.2.0

From Python, call the REST endpoints directly (see the cURL examples on this page) and use the OpenAI SDK for gateway calls. You can manage models, customers, keys, and usage in the dashboard under Overview, Models, Customers, Keys, Usage, and Settings.

Customers

Get a customer

Retrieve a customer’s profile and their wallets. Each wallet reports total, used, frozen, and available, plus a per-source breakdown. GET /v1/customers/:customer_id

Path parameters

string

required

The unique identifier for this customer in your system.

Response fields

string

The customer identifier.

string

The customer’s display name.

string

The customer’s email address.

object

Arbitrary key-value metadata you attached to this customer.

object

A map of wallet name to wallet balance. Each wallet reports its aggregate totals and a per-source breakdown.

Show wallet properties

number

Total credits in this wallet.

number

Consumed credits in this wallet.

number

Credits currently reserved for an in-progress task.

number

Credits immediately available to spend.

array

Per-source breakdown of this wallet. Each source is one deposit grant with its own validity window.

Show source properties

string

The source label for this grant.

number

Total credits from this source.

number

Consumed credits from this source.

number

Frozen credits from this source.

number

Available credits from this source.

string | null

ISO 8601 datetime. Credits are inactive before this date, or null if not set.

string | null

ISO 8601 datetime. Credits expire after this date, or null if not set.

string

ISO 8601 datetime when this customer record was created.

Example request

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

Example response

{
  "id": "user_987",
  "name": "Alice",
  "email": "alice@example.com",
  "metadata": {},
  "wallets": {
    "credits": {
      "total": 1500000000,
      "used": 0,
      "frozen": 0,
      "available": 1500000000,
      "sources": [
        {
          "source": "credits",
          "total": 1500000000,
          "used": 0,
          "frozen": 0,
          "available": 1500000000,
          "starts_at": null,
          "expires_at": null
        }
      ]
    }
  },
  "created_at": "2026-04-07T12:00:00.000Z"
}

Wallet balances are reported in credits. The example above shows 1,500,000,000 credits, which is $1,500.00 (1 USD = 1,000,000 credits).

Get a balance summary

Returns an object-shaped summary of the customer’s balance, without the full per-source breakdown. GET /v1/customers/:customer_id/balance

curl https://api.velobase.io/v1/customers/user_987/balance \
  -H "Authorization: Bearer vb_live_1234567890abcdef"

Get the ledger

Returns the customer’s transaction history: deposits, freezes, consumes, deducts, unfreezes, and gateway settlements. Uses cursor pagination. GET /v1/customers/:customer_id/ledger

Query parameters

string

Pagination cursor from a previous page’s next_cursor.

number

Maximum number of entries to return per page.

string

Filter by operation type (for example DEPOSIT, FREEZE, CONSUME, DEDUCT, UNFREEZE).

string

Filter to the entries belonging to one transaction.

curl "https://api.velobase.io/v1/customers/user_987/ledger?limit=20" \
  -H "Authorization: Bearer vb_live_1234567890abcdef"

Customer wallets

These endpoints fund and settle a customer’s wallet directly. Use them for work you price yourself, such as a fixed credit grant or a one-shot charge. Model calls made through the gateway settle automatically against the wallet, so you do not need these for per-token billing.

Deposit to a wallet

Add integer credits to a customer’s wallet. If the customer does not exist yet, Velobase automatically creates them using the name and email fields you provide. POST /v1/customers/deposit

Request parameters

string

required

The unique identifier for this customer in your system.

number

required

Positive integer credits to deposit. 1 USD = 1,000,000 credits. Fields like amount_usd, amount_cents, or amount_credits are rejected.

string

Unique identifier for this deposit to prevent double processing. Optional, but strongly recommended (use your payment event id).

string

default:"credits"

The wallet to deposit into. Defaults to "credits". (credit_type is a deprecated alias for this field.)

string

ISO 8601 datetime. Credits are ignored before this date.

string

ISO 8601 datetime. Credits are ignored after this date.

string

Customer’s display name. Used only when creating a new customer.

string

Customer’s email address. Used only when creating a new customer.

string

Optional note for the ledger.

Response fields

string

The customer identifier.

string

The wallet (account) that received the credits.

string

The wallet name.

number

Total credits in this wallet after the deposit.

number

Credits added in this operation. 1 USD = 1,000,000 credits.

string | null

ISO 8601 credit activation date, if set.

string | null

ISO 8601 credit expiry date, if set.

string

The unique ledger record ID.

boolean

true if this was a duplicate request that returned the original result.

Example request

curl -X POST https://api.velobase.io/v1/customers/deposit \
  -H "Authorization: Bearer vb_live_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "user_987",
    "amount": 10000000,
    "idempotency_key": "dep_unique_001"
  }'

This deposits 10,000,000 credits, which is $10.00.

Example response

{
  "customer_id": "user_987",
  "account_id": "acc_abc123",
  "wallet": "credits",
  "total_amount": 10000000,
  "added_amount": 10000000,
  "starts_at": null,
  "expires_at": null,
  "record_id": "rec_xyz789",
  "is_idempotent_replay": false
}

Billing primitives

The freeze, consume, deduct, and unfreeze primitives let you reserve and settle a customer’s wallet for work you price yourself, keyed by your own transaction_id. Model calls made through the gateway settle automatically and do not need these. All amounts are positive integer credits.

Direct deduct

Atomically deduct from a customer’s available balance in a single step. Use this for immediate, one-shot charges where you do not need to reserve funds first. POST /v1/billing/deduct

Request parameters

string

required

The unique identifier for this customer in your system.

number

required

Positive integer credits to deduct. 1 USD = 1,000,000 credits.

string

required

Unique identifier for this task or job.

string

Optional. Restrict the deduction to a single wallet by name.

string

Transaction category for reporting. Examples: TASK, ORDER, TOKEN_USAGE.

string

Optional note for the ledger.

Response fields

string

Echo of the request identifier.

number

Total credits deducted.

array

Breakdown by wallet. Each item contains account_id, credit_type, and amount.

string

ISO 8601 timestamp of the deduction.

boolean

true if this was a duplicate request.

Example request

curl -X POST https://api.velobase.io/v1/billing/deduct \
  -H "Authorization: Bearer vb_live_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "user_987",
    "amount": 2000000,
    "transaction_id": "task_001"
  }'

This deducts 2,000,000 credits, which is $2.00.

Example response

{
  "transaction_id": "task_001",
  "deducted_amount": 2000000,
  "deduct_details": [
    {
      "account_id": "acc_abc123",
      "credit_type": "credits",
      "amount": 2000000
    }
  ],
  "deducted_at": "2026-04-08T10:30:00.000Z",
  "is_idempotent_replay": false
}

Freeze credits

Reserve a specific amount for an ongoing task. Frozen credits are held exclusively for that task and cannot be spent by any other operation until they are consumed or unfrozen. POST /v1/billing/freeze

Request parameters

string

required

The unique identifier for this customer in your system.

number

required

Positive integer credits to freeze. 1 USD = 1,000,000 credits.

string

required

Unique identifier for this task or job. Also the idempotency key for the freeze / consume / unfreeze sequence.

string

Optional. Restrict the freeze to a single wallet by name.

string

Transaction category for reporting. Examples: TASK, ORDER, TOKEN_USAGE.

number

Optional TTL. If the transaction is never settled, the frozen credits are automatically released back to the wallet after this many seconds.

number

Optional TTL. If the transaction is never settled, the frozen credits are automatically consumed after this many seconds.

string

Optional note for the ledger.

Response fields

string

Echo of the request identifier.

number

Total credits frozen.

array

Breakdown by wallet. Each item contains account_id, credit_type, and amount.

boolean

true if this was a duplicate request.

Example request

curl -X POST https://api.velobase.io/v1/billing/freeze \
  -H "Authorization: Bearer vb_live_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "user_987",
    "amount": 1000000,
    "transaction_id": "task_002"
  }'

This freezes 1,000,000 credits, which is $1.00.

Example response

{
  "transaction_id": "task_002",
  "frozen_amount": 1000000,
  "freeze_details": [
    {
      "account_id": "acc_abc123",
      "credit_type": "credits",
      "amount": 1000000
    }
  ],
  "is_idempotent_replay": false
}

Consume frozen credits

Permanently deduct from a previously frozen transaction. You supply the actual amount used, which may be less than what was originally frozen, and Velobase returns any remainder to the customer’s available balance. POST /v1/billing/consume

Request parameters

string

required

The transaction_id used in the original freeze call.

number

Credits to actually deduct. Must be less than or equal to the originally frozen amount. Optional: if omitted, the full frozen amount is consumed.

Response fields

string

Echo of the request identifier.

number

Credits permanently deducted from the frozen amount.

number

Unused credits returned to the available balance (frozen - consumed).

array

Breakdown by wallet. Each item contains account_id, credit_type, and amount.

string

ISO 8601 timestamp of the consumption.

boolean

true if this was a duplicate request.

Example request

curl -X POST https://api.velobase.io/v1/billing/consume \
  -H "Authorization: Bearer vb_live_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "task_002",
    "actual_amount": 730000
  }'

This consumes 730,000 credits (

0.73) out of the 1,000,000 frozen, returning the remaining 270,000 credits (

0.27).

Example response

{
  "transaction_id": "task_002",
  "consumed_amount": 730000,
  "returned_amount": 270000,
  "consume_details": [
    {
      "account_id": "acc_abc123",
      "credit_type": "credits",
      "amount": 730000
    }
  ],
  "consumed_at": "2026-04-08T10:35:00.000Z",
  "is_idempotent_replay": false
}

Unfreeze credits

Release all unused frozen credits back to the customer’s available balance. Use this when a task is canceled or fails and you want to return the reserved credits without consuming any. POST /v1/billing/unfreeze

Request parameters

string

required

The transaction_id used in the original freeze call.

Response fields

string

Echo of the request identifier.

number

Total credits released back to the available balance.

array

Breakdown by wallet. Each item contains account_id, credit_type, and amount.

string

ISO 8601 timestamp of the unfreeze.

boolean

true if this was a duplicate request.

Example request

curl -X POST https://api.velobase.io/v1/billing/unfreeze \
  -H "Authorization: Bearer vb_live_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "task_002"
  }'

Example response

{
  "transaction_id": "task_002",
  "unfrozen_amount": 1000000,
  "unfreeze_details": [
    {
      "account_id": "acc_abc123",
      "credit_type": "credits",
      "amount": 1000000
    }
  ],
  "unfrozen_at": "2026-04-08T10:40:00.000Z",
  "is_idempotent_replay": false
}

​Model gateway

​Authentication and routing

​Request headers

​Per-call billing headers

​Models

​Example request

​Billing receipts

​SDKs

​Customers

​Get a customer

​Path parameters

​Response fields

​Example request

​Example response

​Get a balance summary

​Get the ledger

​Query parameters

​Customer wallets

​Deposit to a wallet

​Request parameters

​Response fields

​Example request

​Example response

​Billing primitives

​Direct deduct

​Request parameters

​Response fields

​Example request

​Example response

​Freeze credits

​Request parameters

​Response fields

​Example request

​Example response

​Consume frozen credits

​Request parameters

​Response fields

​Example request

​Example response

​Unfreeze credits

​Request parameters

​Response fields

​Example request

​Example response

Model gateway

Authentication and routing

Request headers

Per-call billing headers

Models

Example request

Billing receipts

SDKs

Customers

Get a customer

Path parameters

Response fields

Example request

Example response

Get a balance summary

Get the ledger

Query parameters

Customer wallets

Deposit to a wallet

Request parameters

Response fields

Example request

Example response

Billing primitives

Direct deduct

Request parameters

Response fields

Example request

Example response

Freeze credits

Request parameters

Response fields

Example request

Example response

Consume frozen credits

Request parameters

Response fields

Example request

Example response

Unfreeze credits

Request parameters

Response fields

Example request

Example response