Assets | Phoenix Wallet

Assets represent the types of value that can be stored in wallets. An asset could be a real currency (USD, EUR), a virtual currency, loyalty points, or any other unit of value your application needs to track.

Asset Structure

Field	Type	Description
`code`	`string`	Unique identifier (e.g., `USD`, `POINTS`)
`tenant_id`	`string`	Parent tenant identifier
`name`	`string`	Human-readable name
`scale`	`integer`	Number of decimal places (0-18)
`status`	`enum`	`ACTIVE` or `INACTIVE`
`metadata`	`object`	Custom key-value pairs
`created_at`	`timestamp`	Creation timestamp

Asset Codes

Asset codes are unique identifiers within a tenant. We recommend following these conventions:

Type	Convention	Examples
ISO Currencies	ISO 4217 codes	`USD`, `EUR`, `GBP`, `JPY`
Crypto	Common symbols	`BTC`, `ETH`, `USDC`
Points/Rewards	Descriptive uppercase	`POINTS`, `REWARDS`, `CREDITS`
Custom	App-specific	`GOLD_COINS`, `GEMS`, `XP`

Asset codes are case-sensitive and must be unique within a tenant. Once created, an asset code cannot be changed.

Decimal Scale

The scale field defines how many decimal places the asset supports. All amounts are stored as integers, and the scale determines their interpretation:

Asset	Scale	Stored Value	Actual Value
USD	2	`15099`	$150.99
JPY	0	`15099`	15,099
BTC	8	`100000000`	1.00000000 BTC
POINTS	0	`500`	500 points
GOLD	4	`123456`	12.3456 gold

Choose your scale carefully. Once an asset is created and has transactions, changing the scale would require migrating all historical data. We recommend:

Scale 2 for most fiat currencies
Scale 0 for points and whole-number systems
Scale 8 for crypto assets

Creating an Asset

curl -X POST https://api.phoenixwallet.io/v1/assets \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "POINTS",
    "name": "Loyalty Points",
    "scale": 0,
    "metadata": {
      "conversion_rate": "100_points_per_dollar",
      "category": "loyalty"
    }
  }'

Response:

{
  "code": "POINTS",
  "tenant_id": "ten_01HV8X9Y2KPQRS3T4UV5WX6YZ7",
  "name": "Loyalty Points",
  "scale": 0,
  "status": "ACTIVE",
  "metadata": {
    "conversion_rate": "100_points_per_dollar",
    "category": "loyalty"
  },
  "created_at": "2024-01-15T10:30:00Z"
}

Common Asset Configurations

Fiat Currency (USD)

{
  "code": "USD",
  "name": "US Dollar",
  "scale": 2,
  "metadata": {
    "symbol": "$",
    "type": "fiat"
  }
}

Loyalty Points

{
  "code": "POINTS",
  "name": "Reward Points",
  "scale": 0,
  "metadata": {
    "earn_rate": "1_per_dollar",
    "redemption_rate": "100_points_per_dollar"
  }
}

In-Game Currency

{
  "code": "GEMS",
  "name": "Game Gems",
  "scale": 0,
  "metadata": {
    "type": "premium_currency",
    "purchasable": true
  }
}

Promotional Credits

{
  "code": "PROMO_USD",
  "name": "Promotional Credits",
  "scale": 2,
  "metadata": {
    "type": "promotional",
    "restrictions": "non_withdrawable"
  }
}

Asset Operations

List Assets

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

Get Asset Details

curl https://api.phoenixwallet.io/v1/assets/POINTS \
  -H "Authorization: Bearer $API_KEY"

Deactivate an Asset

Deactivating an asset prevents new lots from being created with it, but existing balances remain accessible:

curl -X POST https://api.phoenixwallet.io/v1/assets/POINTS/deactivate \
  -H "Authorization: Bearer $API_KEY"

Multi-Asset Wallets

A single wallet can hold multiple assets simultaneously. Each asset's balance is tracked independently:

{
  "wallet_id": "wal_01HV8X9Y2KPQRS3T4UV5WX6YZ7",
  "balances": [
    {
      "asset_code": "USD",
      "available": "15000",
      "scale": 2
    },
    {
      "asset_code": "POINTS",
      "available": "2500",
      "scale": 0
    },
    {
      "asset_code": "PROMO_USD",
      "available": "1000",
      "scale": 2
    }
  ]
}

Wallets - Containers that hold asset balances
Lots - How assets are organized into balance tranches
Policies - Rules that can be applied per asset