Skip to main content

​
Wallet Record Schema

​
Overview

Represents a participant’s wallet, including reservation-aware balances and lifetime spend.

​
Required Fields

FieldTypeDescription
wallet_idstringUnique wallet identifier
owner_typestringbrand_agent, operator, or platform
currencystringISO 4217 currency code
available_balance_centsintegerFunds available for new auctions (in cents)
reserved_balance_centsintegerFunds reserved for active auctions (in cents)
lifetime_spend_centsintegerTotal spend charged from this wallet (in cents)
updated_atstringISO 8601 timestamp of last update

​
Optional Fields

FieldTypeDescription
extobjectVendor-namespaced extensions

​
Example

{
  "wallet_id": "wal_105",
  "owner_type": "brand_agent",
  "currency": "USD",
  "available_balance_cents": 250000,
  "reserved_balance_cents": 5000,
  "lifetime_spend_cents": 127500,
  "updated_at": "2025-11-12T02:00:00Z"
}

​
Validation Rules

  • Amount fields must be integers ≥ 0
  • owner_type must be brand_agent, operator, or platform
  • currency must match ^[A-Z]{3}$
  • updated_at must be ISO 8601 date-time