Wallet

Each platform has a single wallet with a USD balance. The wallet is debited after each successful LLM request based on actual token usage and provider pricing. If the wallet balance is insufficient, inference requests return 402 Payment Required with code wallet_insufficient.

GET/v1/platforms/{platformId}/wallet

Retrieves the platform wallet balance and the 5 most recent transactions.

Auth: Platform key.

ℹMicrodollar precision

balance is stored as numeric(12,6). A chat completion of 20 tokens on a cheap model can move the balance by as little as 0.000002, so a UI that rounds to 2 decimals will appear stuck. Display at least 4-6 decimal places, or aggregate before rounding.

bash

curl https://api.assistiv.ai/v1/platforms/{platformId}/wallet \
  -H "Authorization: Bearer sk-plat_your_key"

json

{
  "id": "wallet-uuid",
  "platform_id": "platform-uuid",
  "balance": 24.850000,
  "currency": "usd",
  "low_balance_threshold": 1.00,
  "is_active": true,
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-04-09T14:22:00Z",
  "recent_transactions": [
    {
      "id": "txn-uuid",
      "type": "llm_usage",
      "amount": 0.000005,
      "balance_after": 24.850000,
      "description": "Inference: 19 tokens (gpt-4o-mini)",
      "created_at": "2026-04-09T14:22:00Z"}
  ]
}

Transaction Types

top_up

Manual or Stripe-checkout top-up

llm_usage

Chat completion / Responses API inference

mcp_usage

Paid MCP tool call (after free tier)

agent_usage

LangGraph agent execution

refund

Credit returned to wallet

adjustment

Admin or system adjustment

POST/v1/platforms/{platformId}/wallet/topup

Adds funds to the platform wallet. Use for dev/test; production platforms typically top up via Stripe checkout.

Auth: Platform key.

Request Body

Name	Type	Required	Description
amount	number	Required	Amount in USD to add. Must be positive.
description	string	Optional	Description for the transaction record.

bash

curl -X POST https://api.assistiv.ai/v1/platforms/{platformId}/wallet/topup \
  -H "Authorization: Bearer sk-plat_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "description": "Monthly top-up"
  }'

POST/v1/platforms/{platformId}/wallet/checkout

Creates a Stripe Checkout Session for wallet top-up.

Auth: Platform key.

Request Body

Name	Type	Required	Description
amount	number	Required	Amount in USD. Range: $5 - $10,000.

The checkout URL is valid for 24 hours. The wallet credit lands on checkout.session.completed webhook arrival (usually < 1s after payment).

bash

curl -X POST https://api.assistiv.ai/v1/platforms/{platformId}/wallet/checkout \
  -H "Authorization: Bearer sk-plat_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 50.00 }'

json

{
  "url": "https://checkout.stripe.com/c/pay/...",
  "session_id": "cs_test_..."}

How Wallet Debits Work

Pre-flight check: Before an LLM call, the inference service estimates the cost and checks the wallet balance.

LLM call: The request is sent to the provider. Actual token usage is measured from the response.

Atomic debit: A Postgres function uses SELECT ... FOR UPDATE row locking to debit the wallet. The cost is calculated from the provider's per-token pricing plus your platform markup percentage.

Transaction log: Every debit is recorded in wallet_transactions for audit.

ℹCombined debit

If the end user has a budget, the wallet debit and budget debit happen in a single atomic transaction via the combined_debit Postgres RPC with row lock. If either fails, both roll back. See Budgets for details.