Wallets API

Keeptrusts exposes wallet APIs for prepaid credit management, model-pricing lookup, per-agent usage constraints, and the gateway-only reserve/settle flow.

Use this page when

• You need the exact command, config, API, or integration details for Wallets API.
• You are wiring automation or AI retrieval and need canonical names, examples, and constraints.
• If you want a guided rollout instead of a reference page, use the linked workflow pages in Next steps.

Browser clients SHOULD keep using the server-side BFF routes in console/ and chat/. The /v1/* routes documented here are the control-plane contracts that those BFF routes forward to.

Primary audience

• Primary: AI Agents, Technical Engineers
• Secondary: Technical Leaders

Auth and scope

Org member or org billing admin

• GET /v1/wallets
• GET /v1/wallets/balance
• GET /v1/wallets/{id}/transactions

Requires org:billing

• POST /v1/wallets/credit
• POST /v1/wallets/allocate
• POST /v1/wallets/reclaim
• GET /v1/payments/history
• GET /v1/payments/settings
• PUT /v1/payments/settings

Agent usage constraints

• GET /v1/agents/{id}/usage-constraints
• POST /v1/agents/{id}/usage-constraints
• PUT /v1/agents/{id}/usage-constraints/{cid}
• DELETE /v1/agents/{id}/usage-constraints/{cid}

These require the existing agent permissions for the target agent (agents:read for list, agents:write for mutations).

Platform-admin only

• GET /v1/admin/model-pricing
• POST /v1/admin/model-pricing
• PUT /v1/admin/model-pricing/{id}
• DELETE /v1/admin/model-pricing/{id}
• GET /v1/admin/exchange-rates
• PUT /v1/admin/exchange-rates
• GET /v1/admin/wallets
• GET /v1/admin/wallets/{id}/transactions
• POST /v1/admin/wallets/credit
• PUT /v1/admin/organizations/{id}/wallet-settings

Gateway service token only

• POST /v1/gateway/wallets/reserve
• POST /v1/gateway/wallets/settle
• POST /v1/gateway/wallets/redeem-ticket
• GET /v1/gateway/agents/{id}/usage-check
• POST /v1/gateway/agents/{id}/usage-increment

These machine routes require a gateway service token with control_plane scope. They are not browser-facing APIs.

Core wallet routes

List wallets

GET /v1/wallets

Returns wallets visible to the caller in the current org. Org billing admins can inspect organization, team, and user scopes.

Typical response:

{
  "wallets": [
    {
      "wallet_id": "wallet_org_123",
      "owner_type": "organization",
      "owner_org_id": "org_123",
      "owner_name": "Acme Corp",
      "balance": 2500.0,
      "currency": "USD"
    }
  ]
}

Read effective balance

GET /v1/wallets/balance

For chat and self-service flows, this returns the effective cascade summary across user, team, and org wallets.

Typical response:

{
  "user_balance": 25,
  "team_balance": 80,
  "org_balance": 2500,
  "effective_available_balance": 80,
  "effective_wallet_owner_type": "team",
  "reserve_buffer_pct": 20,
  "currency": "USD"
}

Read wallet transactions

GET /v1/wallets/{id}/transactions

Returns paginated ledger entries such as credit, reservation, settlement, allocation_in, allocation_out, payment_credit, and payment_refund.

Typical response:

{
  "transactions": [
    {
      "id": "txn_123",
      "type": "reservation",
      "amount": -1.24,
      "balance_after": 78.76,
      "provider": "openai",
      "model": "gpt-4.1-mini",
      "created_at": "2026-05-01T12:00:00Z"
    }
  ],
  "has_more": false,
  "total": 1
}

Credit, allocate, and reclaim

POST /v1/wallets/credit

{
  "target_wallet_owner_type": "organization",
  "amount": 500,
  "description": "Quarterly budget top-up"
}

POST /v1/wallets/allocate

{
  "team_id": "team_123",
  "amount": 125
}

POST /v1/wallets/reclaim

{
  "team_id": "team_123",
  "amount": 25
}

Model pricing and exchange rates

Public pricing lookup for runtime and UI

GET /v1/model-pricing

Returns the active pricing catalog used for reserve and settle calculations.

Platform-admin management

• GET /v1/admin/model-pricing
• POST /v1/admin/model-pricing
• PUT /v1/admin/model-pricing/{id}
• DELETE /v1/admin/model-pricing/{id}

Exchange rates

• GET /v1/admin/exchange-rates
• PUT /v1/admin/exchange-rates

Use exchange rates when an organization wallet currency is not USD.

Agent usage constraints

Agent usage constraints cap cost or response volume for a specific agent.

List constraints

GET /v1/agents/{id}/usage-constraints

Create a constraint

POST /v1/agents/{id}/usage-constraints

{
  "constraint_type": "cost",
  "provider": "openai",
  "model_pattern": "gpt-4.1*",
  "max_value": 25,
  "interval": "day",
  "enforcement_mode": "reject"
}

Update or delete a constraint

• PUT /v1/agents/{id}/usage-constraints/{cid}
• DELETE /v1/agents/{id}/usage-constraints/{cid}

Gateway reserve and settle flow

The gateway performs a two-phase reserve and settle cycle for every priced request:

1. POST /v1/gateway/wallets/reserve
2. upstream request executes
3. POST /v1/gateway/wallets/settle

If reserve fails because the wallet cascade has insufficient balance, the API returns 402 with a cost ticket. After a top-up, the gateway can retry by calling POST /v1/gateway/wallets/redeem-ticket.

Reserve request example:

{
  "org_id": "org_123",
  "user_id": "user_123",
  "team_id": "team_123",
  "agent_id": "agent_123",
  "provider": "openai",
  "model": "gpt-4.1-mini",
  "estimated_prompt_tokens": 1200,
  "max_completion_tokens": 800,
  "request_body_hash": "sha256:..."
}

Insufficient-balance response example:

{
  "cost_ticket": {
    "id": "ticket_123",
    "estimated_cost": 2.5,
    "balance": 1.0,
    "shortfall": 1.5,
    "provider": "openai",
    "model": "gpt-4.1-mini",
    "expires_at": "2026-05-02T12:00:00Z"
  }
}

For AI systems

• Canonical terms: Keeptrusts Wallets API, wallet balance, reserve/settle, cost ticket, agent usage constraints, model pricing, wallet cascade.
• Endpoints: GET /v1/wallets, GET /v1/wallets/balance, GET /v1/wallets/{id}/transactions, POST /v1/wallets/credit, POST /v1/wallets/allocate, POST /v1/wallets/reclaim, GET /v1/model-pricing, GET /v1/agents/{id}/usage-constraints, POST /v1/agents/{id}/usage-constraints, POST /v1/gateway/wallets/reserve, POST /v1/gateway/wallets/settle, POST /v1/gateway/wallets/redeem-ticket.
• Wallet scope cascade: user → team → organization.
• Transaction types: credit, reservation, settlement, allocation_in, allocation_out, payment_credit, payment_refund.
• Usage constraint fields: constraint_type (cost | responses), provider, model_pattern, max_value, interval (hour | day | week | month), enforcement_mode (reject | warn).
• Gateway flow: reserve (estimated cost) → upstream request → settle (actual cost). 402 with cost_ticket on insufficient balance.
• Best next pages: Payments API, Billing and Plans.

For engineers

• Prerequisites: platform-admin must seed model pricing via POST /v1/admin/model-pricing before reserve/settle can calculate costs.
• Browser clients should use BFF routes in console/chat, not direct /v1/wallets/* or /v1/gateway/* endpoints.
• Gateway service token with control_plane scope is required for /v1/gateway/* machine routes.
• Reserve returns 402 with a cost ticket when the wallet cascade has insufficient balance; the gateway holds the request until the ticket is redeemed or denied.
• Agent usage constraints cap cost or volume per agent per interval — use enforcement_mode: reject for hard limits.
• Test: allocate credits to a test team with POST /v1/wallets/allocate, then verify the team balance reflects the allocation.

For leaders

• Spend control: the reserve/settle pattern prevents overspend by pre-authorizing estimated cost before any upstream call is made.
• Budget delegation: POST /v1/wallets/allocate distributes org budget to teams without granting full billing access.
• Agent guardrails: per-agent usage constraints prevent runaway agents from exceeding per-day or per-month cost ceilings.
• Visibility: wallet transactions provide a full ledger trail of credits, reservations, settlements, and refunds for financial reconciliation.
• Cost ticket workflow: when balance is insufficient, the system queues the request instead of failing silently, allowing top-ups to resolve the backlog.

Next steps

• Wallets & Credits
• Billing and Plans
• Payments API