Lots | Phoenix Wallet

Lots are the fundamental unit of balance storage in Phoenix Wallet. A lot represents a discrete portion of funds within a wallet, with its own policy, expiry date, and attributes. This design enables sophisticated balance management like FIFO depletion, promotional credits with restrictions, and time-limited bonuses.

Lot Structure

Field	Type	Description
`id`	`string`	Unique identifier (UUID)
`wallet_id`	`string`	Parent wallet identifier
`asset_code`	`string`	Asset type for this lot
`policy_id`	`string`	Policy governing this lot
`amount`	`string`	Original credited amount
`available`	`string`	Current available balance
`reserved`	`string`	Amount held by reservations
`expires_at`	`timestamp`	Expiration date (optional)
`attributes`	`object`	Custom key-value pairs
`created_at`	`timestamp`	Creation timestamp

How Lots Work

When funds are credited to a wallet, they're placed into a lot. When funds are debited, the system selects lots based on policy rules and depletion order:

Wallet: user_123
Asset: USD

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│  LOT #1 (Welcome Bonus)         LOT #2 (Deposit)           │
│  ┌─────────────────────┐        ┌─────────────────────┐    │
│  │ Amount:    $25.00   │        │ Amount:    $100.00  │    │
│  │ Available: $25.00   │        │ Available: $100.00  │    │
│  │ Reserved:  $0.00    │        │ Reserved:  $0.00    │    │
│  │ Policy:    promo    │        │ Policy:    standard │    │
│  │ Expires:   7 days   │        │ Expires:   never    │    │
│  │ Attributes:         │        │ Attributes:         │    │
│  │   source: signup    │        │   source: deposit   │    │
│  │   withdrawable: no  │        │   withdrawable: yes │    │
│  └─────────────────────┘        └─────────────────────┘    │
│                                                             │
│  Total Available: $125.00                                   │
└─────────────────────────────────────────────────────────────┘

Lot Expiry

Lots can have an optional expiration date. When a lot expires:

The available balance becomes inaccessible
Expired funds are not included in wallet balance calculations
A lot.expired event is emitted
The lot remains in the system for audit purposes

{
  "id": "lot_01HV8X9Y2KPQRS3T4UV5WX6YZ7",
  "wallet_id": "wal_01HV8X9Y2KPQRS3T4UV5WX6YZ7",
  "asset_code": "POINTS",
  "amount": "1000",
  "available": "1000",
  "expires_at": "2024-02-15T00:00:00Z",
  "attributes": {
    "campaign": "winter_promo",
    "reason": "holiday_bonus"
  }
}

Expiration is processed automatically by the system. You can configure your policies to prioritize expiring lots first (FEFO - First Expiring, First Out) to maximize utilization.

Lot Attributes

Attributes are flexible key-value pairs that let you attach business context to lots:

Use Case	Example Attributes
Promotional credits	`source: "campaign_abc"`, `withdrawable: false`
Referral bonuses	`referred_by: "user_456"`, `program: "referral_v2"`
Cashback	`order_id: "ord_789"`, `cashback_rate: "0.05"`
Gaming rewards	`achievement: "level_up"`, `rarity: "legendary"`

Attributes can be used for:

Filtering and querying lots
Policy evaluation (restrict spending based on attributes)
Reporting and analytics
Audit trails

Creating a Lot (Credit Operation)

Lots are created implicitly when you credit a wallet:

curl -X POST https://api.phoenixwallet.io/v1/wallets/wal_01HV8X.../credit \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_code": "USD",
    "amount": "2500",
    "policy_id": "pol_promo",
    "expires_at": "2024-03-01T00:00:00Z",
    "attributes": {
      "source": "signup_bonus",
      "campaign": "march_madness",
      "withdrawable": "false"
    },
    "idempotency_key": "credit_user123_signup_bonus"
  }'

Response:

{
  "lot": {
    "id": "lot_01HV8X9Y2KPQRS3T4UV5WX6YZ7",
    "wallet_id": "wal_01HV8X9Y2KPQRS3T4UV5WX6YZ7",
    "asset_code": "USD",
    "policy_id": "pol_promo",
    "amount": "2500",
    "available": "2500",
    "reserved": "0",
    "expires_at": "2024-03-01T00:00:00Z",
    "attributes": {
      "source": "signup_bonus",
      "campaign": "march_madness",
      "withdrawable": "false"
    },
    "created_at": "2024-01-15T10:30:00Z"
  },
  "ledger_entry_id": "led_01HV8X9Y2KPQRS3T4UV5WX6YZ7"
}

Lot Selection and Depletion

When debiting a wallet, the system selects lots based on:

Policy compatibility - Only lots whose policy allows the operation
Depletion order - Configured order (FIFO, FEFO, or custom)
Attribute matching - Optional filters on lot attributes

Depletion Order Examples

FIFO (First In, First Out):

Debit $30 from wallet with lots:
  Lot #1: $20 (created Jan 1)  → Fully depleted
  Lot #2: $50 (created Jan 5)  → $10 depleted, $40 remains

FEFO (First Expiring, First Out):

Debit $30 from wallet with lots:
  Lot #1: $50 (expires Feb 28) → $30 depleted, $20 remains
  Lot #2: $20 (expires Jan 31) → Fully depleted first (expires sooner)

Querying Lots

List Lots for a Wallet

curl "https://api.phoenixwallet.io/v1/wallets/wal_01HV8X.../lots" \
  -H "Authorization: Bearer $API_KEY"

Filter by Attributes

curl "https://api.phoenixwallet.io/v1/wallets/wal_01HV8X.../lots?attributes.source=signup_bonus" \
  -H "Authorization: Bearer $API_KEY"

Get Non-Expired Lots Only

curl "https://api.phoenixwallet.io/v1/wallets/wal_01HV8X.../lots?expired=false" \
  -H "Authorization: Bearer $API_KEY"

Wallets - Parent container for lots
Policies - Rules that govern lot behavior
Assets - Types of value stored in lots
Ledger - Transaction history for lot changes