# Interpret token amounts, timestamps and data quality correctly

Handle MadeOnSol token precision, timestamps, null values and module quality without confusing missing information with zero.

Access: All plans; fields and availability vary by route

[Compare plans and subscribe](https://madeonsol.com/pricing#pricing)

Author: MadeOnSol

Updated: 2026-11-17

## Integration choice

Preserve the meaning of each response before formatting it. Keep raw amounts, decimal scale, source timestamps and quality metadata distinct. Use the endpoint contract for units and availability; do not infer one universal shape from a different route or chain.

## Before you start

- The reference contract for each route and channel you consume.
- Fixtures that include missing and partial values, not only a happy-path response.

## Implementation steps

1. Build a small adapter for each response type. Validate required fields and preserve documented status, reason, as_of and provenance fields when present.
2. Keep integer amounts as strings or BigInt until display. Use the documented decimals for that token and field, not a fixed assumption across all tokens.
3. Record event or source time separately from local receipt time. Convert timestamps according to the documented field unit; do not guess by string length.
4. Represent unavailable, empty and zero as separate application states. Retain an older valid value according to your freshness policy instead of manufacturing a new zero.
5. Merge state using documented identity and ordering rules. Merge candles by chain, token and bucket start, replacing revisions in the existing bucket.

## Keep precision until the display boundary

JavaScript Number cannot exactly represent every large integer. When a contract returns a raw integer string, preserve it and apply its decimal scale with integer arithmetic or a decimal library. The example formats a raw amount without a floating-point conversion.

Do not apply token decimals to an already normalized decimal amount. Prices, token quantities, fiat values and percentages have different units. The example is for raw non-negative integers only; it is not a universal parser for every MadeOnSol numeric field.

## Separate availability from freshness

The intelligence helper preserves per-module status, reason, as_of and provenance rather than treating every module as equally current. A response can contain useful data in one module and incomplete information in another. Handle each module according to its contract.

Robinhood Chain price state includes quality and quality_reason. A recent network receipt does not turn a stale or unreliable source price into a fresh one. Similarly, a holder count of null for an unindexed token is not evidence that the token has zero holders.

## Use the right timestamp and identity

Keep chain in every token and event key. Do not lowercase Solana addresses; Robinhood Chain hexadecimal addresses can be normalized according to their contract. Preserve the original event identity alongside any display-friendly fields.

A candle’s bucket time describes the interval it aggregates, not necessarily the time your application received it. Replace a closed or revised bucket by its identity rather than appending duplicate rows. Repainting a current state and reconstructing historical events remain different operations.

![MadeOnSol one-minute candle chart showing USD price, volume and the live candle legend for DEET.](https://madeonsol.com/guides/one-minute-candles.jpg)

Existing chart capture: price, volume and candle time represent different quantities. Preserve those units when formatting data, and update a revised candle in its existing time bucket. Values in this screenshot are illustrative historical observations, not current quotes.

## Format a raw token amount (standalone JavaScript)

~~~javascript
// For a documented RAW non-negative integer amount only.
// Already normalized decimal fields must not be scaled again.
function formatRawAmount(raw, decimals) {
  if (typeof raw !== "string" || !/^\d+$/.test(raw)) throw new Error("Expected an integer string");
  if (!Number.isInteger(decimals) || decimals < 0 || decimals > 255) throw new Error("Invalid decimals");
  const digits = BigInt(raw).toString();
  if (decimals === 0) return digits;
  const padded = digits.padStart(decimals + 1, "0");
  return padded.slice(0, -decimals) + "." + padded.slice(-decimals);
}
console.log(formatRawAmount("9007199254740993123", 9)); // 9007199254.740993123
console.log(formatRawAmount("0", 6)); // 0.000000
~~~

## Common mistakes and fixes

- Render null as 0 everywhere. Fix: Use an explicit unavailable state; zero is a measured value.

- Convert a raw amount to Number before scaling. Fix: Keep the integer exact until formatting.

- Use receipt time as source freshness. Fix: Store both times and apply the route’s quality metadata.

## Verify your integration

Use fixtures with a genuine zero, null, an empty list, a large integer amount, differing token decimals, an older source timestamp and a revised candle. Confirm these remain distinguishable and that formatting never changes the original stored value.

## Production checklist

- Raw payloads mapped by endpoint-specific adapters.
- Large amounts retain exact digits.
- Unknown, empty and zero covered by fixtures.
- Source freshness preserved through caching and rendering.

## Frequently asked questions

### Is a recently fetched response necessarily fresh market data?

No. Request time and source time measure different things. Inspect the source timestamp and quality fields where the contract supplies them.

### Can I assume every token uses nine decimals?

No. Use the token and field’s documented scale. Some fields are already normalized and must not be scaled again.

## Continue building

- [Merge live candles with historical OHLCV](https://madeonsol.com/docs/candles)
- [Reduce REST polling in a trading terminal](https://madeonsol.com/docs/terminal)
- [Reduce MadeOnSol API calls with safe backend caching](https://madeonsol.com/docs/caching)

## Match your plan to your workload

Compare capacity, channel access and display rights before launching.

[Compare plans and subscribe](https://madeonsol.com/pricing#pricing)

## Related reference

- [Terminal helper reference](https://madeonsol.com/api-docs#terminal-helper)
- [Robinhood Chain reference](https://madeonsol.com/api-docs#rhc)
- [Stream subscription builder](https://madeonsol.com/api-docs#stream-config)

[Canonical guide](https://madeonsol.com/docs/data-semantics)
