We're excited to announce that Birdeye now supports Scaled UI Amounts across multiple API endpoints. Introduced with Solana’s Token-2022 Program, Scaled UI Amounts allow token issuers to define how their tokens are displayed without changing how they’re stored on-chain. Whether you're a developer, DeFi user, or data consumer, this update helps bring clarity and flexibility to how token amounts are viewed and used.
In this article, we’ll break it all down:
- What Scaled UI Amounts are and why they matter
- What changes in our API
- How
ui_amount_modeworks - Example responses in each mode
- What APIs are impacted
- Developer tips
📚 Terms & Definitions
| Term | Definition | Example |
|---|---|---|
| Raw Amount | The actual token amount stored on-chain, usually an integer. | 1000000 |
| Decimals | The token’s precision; how many digits after the decimal point. | 6 |
| UI Amount | The human-readable amount, calculated as raw / (10^decimals) (for classic tokens). |
1 |
| Multiplier | The multiplier used for Scaled UI Amounts (e.g., 9 or 1). | 1 |
| Token-2022 | An updated Solana token standard that introduces new optional extensions like transfer hooks, scaling, and more. | |
| Is Scaled UI Token | Boolean indicating whether the token uses the scaling feature. | |
| UI Amount Mode | API query parameter to specify how token amounts are returned: raw, scaled, or both. | |
| Balance | Total token holdings in a wallet, as a raw integer. Not divided by decimals. Not used directly in actions. | 1234567 |
| Amount | Raw token amount used in operations like swaps, transfers, etc. | 1234567 |
| UI Amount | Human-readable amount: amount / (10^decimals)
|
1 |
| Scaled UI Amount | A custom multiplier applied on top of the UI amount, defined via Token-2022 extension. |
1.234567 * 2.5 = 3.086417 (rounded to 6 decimals) |
Scaled UI Amount
Existing problem
In traditional SPL tokens (before Token-2022), the displayed token amount is calculated by dividing the raw on-chain amount by 10^decimals. Tokens must hard-code their display logic into every wallet, dApp, or price feed.
Example:
- Token has 6 decimals
- Raw amount = 1,000,000
- UI amount = 1,000,000 / 10^6 = 1.0
However, some tokens—especially in DeFi, stablecoins, or fractionalized assets—require more flexibility in how balances are presented to users, without changing how they are stored on-chain.
The solution
A Scaled UI Amount extension, specifically in the context of Solana tokens, allows token issuers to apply a dynamic multiplier to the user interface (UI) representation of a token balance. This means the displayed amount on the user's interface can differ from the actual underlying token balance, making it useful for representing real-world assets or implementing features like stock splits. Learn more in the official Solana documentation.
Example with Scaled UI:
- Raw amount = 1,000,000
- Scale multiplier = 9
- UI amount = 1,000,000 * 9 = 9.0
Why this matters
- This doesn’t mint new tokens or change balances. The feature is purely cosmetic and gives token issuers more control over the UI experience—without affecting the on-chain logic.
- The multiplier is stored in a token extension introduced in Token-2022.
- It’s perfect for things like stock splits or mapping tokens to real-world value.
- Scaled UI improves user clarity (e.g., displaying 1.0 instead of 0.000000001) and lets APIs serve both raw and user-friendly data
Introducing new API parameter ui_amount_mode
⚠️ Note: For EVM-based tokens, this logic remains unchanged. Continue using raw / (10^decimals) as before.
To help developers navigate this change, APIs now support a new query parameter: ui_amount_mode.
ui_amount_mode is set to raw by default. Users may choose an alternative mode if required.
GET /defi/price?address=<TOKEN_ADDRESS>&ui_amount_mode=<raw|scaled|both>
ui_amount_mode supported modes
| Mode | Description |
|---|---|
raw (default) |
Return original on-chain values only |
scaled |
Return values adjusted by the token’s scale multiplier |
both |
Return both raw and scaled fields (with scaled_ prefix) |
Field naming consistency by endpoint schema
| Endpoint schema format | New field naming rule | Existing field example | New field example |
|---|---|---|---|
snake_case |
New fields must also use snake_case naming |
unix_time |
is_scaled_ui_token |
camelCase |
New fields must also use camelCase naming |
updateHumanTime |
isScaledUiToken |
Example (camelCase schema): Endpoint/defi/price
1. Mode: ui_amount_mode=raw (Default)
{
"data": {
"isScaledUiToken": true,
"value": 180.0504978880241,
"updateUnixTime": 1751346601,
"updateHumanTime": "2025-07-01T05:10:01",
"priceChange24h": -3.9658703652924556,
"priceInNative": 1.180457322730266,
"liquidity": 603837.436523065
},
"success": true
}2. Mode: ui_amount_mode=scaled
{
"data": {
"isScaledUiToken": true,
"scaledValue": 180.0504978880241,
"multiplier": 1,
"scaledPriceInNative": 1.180411245366789,
"updateUnixTime": 1751346601,
"updateHumanTime": "2025-07-01T05:10:01",
"priceChange24h": -3.9658703652924556,
"liquidity": 603837.436523065
},
"success": true
}⚠️ If is_scaled_ui_token = false, the response won't return any scaled_ fields.
3. Mode: ui_amount_mode=both
{
"data": {
"isScaledUiToken": true,
"value": 180.17480127404215,
"updateUnixTime": 1751346653,
"updateHumanTime": "2025-07-01T05:10:53",
"priceChange24h": -3.8995702571177198,
"priceInNative": 1.1815711723488305,
"liquidity": 603837.436523065,
"scaledValue": 180.17480127404215,
"multiplier": 1,
"scaledPriceInNative": 1.1815711723488305
},
"success": true
}Example (snake_case schema): Endpoint/defi/ohlcv
1. Mode: ui_amount_mode=raw (Default)
{
"data": {
"items": [
{
"is_scaled_ui_token": true,
"address": "XsueG8BtpquVJX9LVLLEGuViXUungE6WmK5YZ3p3bd1",
"unix_time": 1751346600,
"o": 179.93442134373544,
"h": 180.20109090522845,
"l": 179.2424152862242,
"v": 17.78543803,
"c": 180.20109090522845,
"type": "5m",
"v_usd": 3201.6446976533302,
"currency": "usd"
}
]
},
"success": true
}2. Mode: ui_amount_mode=scaled
{
"data": {
"items": [
{
"is_scaled_ui_token": true,
"scaled_multiplier": 1,
"scaledui_h": 180.20109090522845,
"scaledui_l": 179.2424152862242,
"scaledui_c": 180.20109090522845,
"scaledui_o": 179.93442134373544,
"scaledui_v": 17.78543803,
"address": "XsueG8BtpquVJX9LVLLEGuViXUungE6WmK5YZ3p3bd1",
"unix_time": 1751346600,
"type": "5m",
"v_usd": 3201.6446976533302,
"currency": "usd"
}
]
},
"success": true
}3. Mode: ui_amount_mode=both
{
"data": {
"items": [
{
"is_scaled_ui_token": true,
"address": "XsueG8BtpquVJX9LVLLEGuViXUungE6WmK5YZ3p3bd1",
"unix_time": 1751346600,
"o": 179.93442134373544,
"h": 180.20109090522845,
"l": 179.2424152862242,
"v": 17.78543803,
"c": 180.20109090522845,
"type": "5m",
"v_usd": 3201.6446976533302,
"currency": "usd",
"scaled_multiplier": 1,
"scaledui_h": 180.20109090522845,
"scaledui_l": 179.2424152862242,
"scaledui_c": 180.20109090522845,
"scaledui_o": 179.93442134373544,
"scaledui_v": 17.78543803
}
]
},
"success": true
}Base/Quote OHLCV computation: raw, scaled, and both modes
1. scaledUiMode = raw
Just use raw values:
base_raw / quote_raw
2. scaledUiMode = scaled
If both tokens support scaled UI:
base_scaled / quote_scaled
If only one token supports scaled UI, apply the scaled multiplier only to the token that supports it:
base_raw / quote_scaled
OR
base_scaled / quote_raw
If neither token supports scaled UI:
Return null (invalid in scaled mode)
3. scaledUiMode = both
If both tokens support scaled UI:
Return BOTH:
- base_scaled / quote_scaled
- base_raw / quote_raw
If neither token supports scaled UI:
Return ONLY:
- base_raw / quote_raw
If only one supports scaled UI:
Return BOTH:
- base_raw / quote_raw
- base_scaled / quote_raw OR base_raw / quote_scaled
Token support check
We use two separate flags for clarity:
isScaledUiTokenBase
isScaledUiTokenQuote
How non-token2022 tokens is handled in scaled mode
Apply scaling only to the token that supports it.
base_scaled / quote_raw OR base_raw / quote_scaled
Final takeaway
- A pair is still valid if only one token supports scaled UI.
- Scaling depends only on the token with a multiplier.
- Always check and apply flags individually.
Summary of Behavior
| ui_amount_mode | is_scaled_ui_token | Raw Fields | Scaled Fields |
|---|---|---|---|
| raw (default) | true / false | ✅ | ❌ |
| scaled | true | ❌ | ✅ |
| scaled | false | ❌ | ❌ |
| both | true | ✅ | ✅ |
| both | false | ✅ | ❌ |
APIs Impacted by ui_amount_mode
This enhancement is being rolled out across multiple API endpoints:
| Name | Endpoint |
|---|---|
| Price | /defi/price |
| Price (Multiple) | GET /defi/multi_price |
| Price (Multiple) | POST /defi/multi_price |
| OHLCV | /defi/ohlcv |
| OHLCV (Base/Quote) | /defi/ohlcv/base_quote |
| OHLCV V3 | /defi/v3/ohlcv |
| Historical Price | /defi/history_price |
| Historical Price by UnixTime | /defi/historical_price_unix |
| Price Volume - Single | /defi/price_volume/single |
| Price Volume - Multiple | /defi/price_volume/multi |
| Price Stats - Single | /defi/v3/price/stats/single |
| Price Stats - Multiple | /defi/v3/price/stats/multiple |
raw mode will remain the default.Developer tips
-
Check
is_scaled_ui_tokenbefore formatting
Only apply scaling when this flag istrue. -
Use
ui_amount_mode=bothduring development
Useful for debugging and dashboards that need to show both scaled and raw values. -
Never assume scaled fields are present
Always check the flag before referencing scaled values to avoid runtime errors. -
Cache
scaled_multiplierper token
Reduce API overhead by caching multipliers (e.g., in Redis) and refreshing periodically.
📐 Best practices: Working with Scaled UI Amounts
Normalize at ingestion
Standardize all token values as they enter your backend or pipeline:
const normalizedAmount = is_scaled_ui_token
? rawAmount * scaled_multiplier
: rawAmount / Math.pow(10, decimals);
This ensures consistency across your system, regardless of token type.
Respect is_scaled_ui_token logic
Do not hardcode assumptions—always use the flag to determine:
- Whether to apply scaling
- How to display or store values
Improve UI clarity
When displaying token values:
- Label whether values are scaled
- Optionally allow users to toggle between scaled and raw views
Write token-agnostic calculations
To ensure compatibility across different tokens:
- Abstract your logic to work with both scaled and unscaled values
- Apply normalization at the comparison or aggregation layer
Comments
0 comments
Please sign in to leave a comment.