Buyer Endpoints

All require authentication (API key or session cookie).

Keys

Everything you can do to a key in the dashboard, you can do here over the API. Create, list, read, rename, revoke, and configure per-key routing preferences, with no browser. This is the same API the dashboard itself calls. Authenticate with any active buyer key (inf_…) or a session cookie; the tenant is resolved from your auth, never sent in the body.

POST/v1/buyer/keys

Create a key (up to 25 active per wallet). Requires an Idempotency-Key header. The inf_… secret is returned in the key field once. Store it immediately; afterwards only its id and key_prefix are recoverable.

GET/v1/buyer/keys

List keys, redacted (id, key_prefix, label, created_at, plus last_used_at / revoked_at when set). Add ?workspace_id= to narrow a team org's keys to one workspace.

GET/v1/buyer/keys/{id}

Read one key's metadata (never the secret).

PATCH/v1/buyer/keys/{id}

Rename a key's label.

DELETE/v1/buyer/keys/{id}

Revoke a key. Irreversible; returns 204.

Keys
bash
POST /v1/buyer/keys
Idempotency-Key: 9f8c1e2b-...     # required
{ "label": "Cursor" }
# → {
#     "id": "01JQ8G7YV3M4N5P6Q7R8S9T0AB",
#     "key": "inf_9f8c1e2b3a4d5e6f7a8b9c0d1e2f3a4b",   # shown once
#     "key_prefix": "inf_9f8c1e2b",
#     "label": "Cursor",
#     "created_at": 1713312000000
#   }
bash
GET /v1/buyer/keys
# → { "items": [ {
#     "id": "01JQ8G7YV3M4N5P6Q7R8S9T0AB", "key_prefix": "inf_9f8c1e2b",
#     "label": "Cursor", "created_at": 1713312000000, "last_used_at": 1713398400000
#   } ] }
bash
GET /v1/buyer/keys/{id}
bash
PATCH /v1/buyer/keys/{id}
{ "label": "Cursor (prod)" }
bash
DELETE /v1/buyer/keys/{id}

Per-key routing preferences

GET/v1/buyer/keys/{id}/preferences

Read a key's resolved routing preferences and limits.

PUT/v1/buyer/keys/{id}/preferences

Configure a key. preferences.allow_untrusted (boolean, nullable) is the routing control: true lets this key route to providers outside the trusted-domain allowlist; null or omitted inherits the account default (trusted-only). limits is reserved for future spend caps; send {}. preferences is replaced wholesale, and the response echoes the resolved values. Set that account-wide default with GET / PUT /v1/buyer/preferences (same { preferences, limits } body); any key without its own override inherits it.

Preferences
bash
GET /v1/buyer/keys/{id}/preferences
# → { "preferences": { "allow_untrusted": true }, "limits": {} }
bash
PUT /v1/buyer/keys/{id}/preferences
{
  "preferences": { "allow_untrusted": true },
  "limits": {}
}

Profile

GET/v1/buyer/me

Balance, allowance, usage stats, per-model breakdown.

GET/v1/buyer/savings

Savings vs direct provider pricing (all-time). Add ?period=daily or ?period=weekly for savings bucketed by day or week.

GET/v1/buyer/approve-status

USDC approval status for SettlementV2/API-key usage.

Profile
bash
GET /v1/buyer/me
bash
GET /v1/buyer/savings
bash
GET /v1/buyer/savings?period=daily
GET /v1/buyer/savings?period=weekly
bash
GET /v1/buyer/approve-status

Usage Export

GET/v1/buyer/usage/export

CSV export of all usage records.

Columns: request_id, created_at, model, input_tokens, output_tokens, buyer_cost_usd, direct_cost_usd, settlement_status, tx_hash. Up to 50,000 rows.

Usage export
bash
GET /v1/buyer/usage/export?format=csv&from=2026-01-01&to=2026-04-13

Providers (BYOK)

Register your own provider keys as buyer-owned providers. A provider scoped to a specific model is tried first for that model (priority — the marketplace is overflow only). A provider with model: null is a catch-all fallback used for any model when all marketplace sellers fail.

POST/v1/buyer/providers

Register a priority provider for a specific model, or a catch-all fallback (used when all marketplace sellers fail).

GET/v1/buyer/providers

List providers.

GET/v1/buyer/providers/{id}

Read one provider (health, active, masked key hint).

PATCH/v1/buyer/providers/{id}

Update a provider: rotate its api_key, change base_url or label, or enable/disable it with active.

DELETE/v1/buyer/providers/{id}

Remove a provider.

Routing order: model-scoped priority provider → marketplace sellers → catch-all (model: null) provider → universal fallback.

Providers (BYOK)
bash
POST /v1/buyer/providers
{ "model": "claude-opus-4.6", "api_key": "sk-...", "base_url": "https://api.venice.ai/api/v1" }
bash
POST /v1/buyer/providers
{ "model": null, "api_key": "sk-...", "base_url": "https://api.venice.ai/api/v1" }
bash
GET /v1/buyer/providers
bash
PATCH /v1/buyer/providers/{id}
{ "active": false }
bash
DELETE /v1/buyer/providers/{id}

Next

Seller Endpoints