Birdeye Now Supports Scaled UI Amounts for Solana Token-2022

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_mode works
• Example responses in each mode
• What APIs are impacted
• Developer tips

📚 Terms & Definitions

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 

Field naming consistency by endpoint schema

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

APIs Impacted by ui_amount_mode

This enhancement is being rolled out across multiple API endpoints:

Developer tips

• Check is_scaled_ui_token before formatting
  Only apply scaling when this flag is true.
• Use ui_amount_mode=both during 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_multiplier per 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