> For the complete documentation index, see [llms.txt](https://bubblegum-reality.gitbook.io/bubblegum-reality-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bubblegum-reality.gitbook.io/bubblegum-reality-docs/architecture/pricing.md).

# Pricing & Multipliers

## The three prices

```
underlying bid/ask          raw price of the underlying equity
        × currentMultiplier
        ▼
adjusted bid/ask            the token's reference value
        vs 0x price
        ▼
executable price            what liquidity will actually fill
```

Labels in the UI are explicit and never interchangeable: **"underlying reference"** vs **"multiplier-adjusted token reference"**. Conflating them is the single most common way a tokenized-equity interface misleads a user, because a token with a `0.1` multiplier looks 10× cheaper than its underlying.

## The multiplier

Robinhood market data returns the raw underlying price. A stock token represents a multiple (or fraction) of that underlying, expressed as `currentMultiplier`:

```ts
adjustedReference(rawPrice, multiplier) // rawPrice × multiplier
```

`adjustedReference` throws when the multiplier is not strictly positive — a zero or negative multiplier is corrupt data, not an edge case to degrade through.

### Pending multipliers

Corporate actions (splits, reverse splits, adjustments) change the multiplier at a future effective time. `pendingMultiplier` and `pendingEffectiveAt` are carried through the DTO and surfaced as a banner in the terminal, because a quote taken across an effective boundary prices against a multiplier that is about to stop being true.

## Decimal safety

Token amounts are **always** base-unit `bigint` or `Decimal` — never JavaScript floats. `src/lib/money.ts` sets `decimal.js` to 40-digit precision with `ROUND_DOWN`.

```ts
fromBaseUnits(value, decimals)  // bigint | string → Decimal
toBaseUnits(value, decimals)    // Decimal.Value  → bigint, truncating
```

Rules enforced by these helpers:

* `decimals` must be an integer in `[0, 36]`; anything else throws.
* Conversion to base units truncates excess precision downward — it never rounds a user's amount up into a balance they do not have.
* Negative amounts throw rather than silently flipping the trade direction.

## Freshness and halts

Prices carry both `generatedAt` (upstream generation) and `fetchedAt` (our fetch). The cache is 15 seconds. The UI shows quote age; staleness feeds the freshness component of the [Reality Score](/bubblegum-reality-docs/architecture/reality-score.md).

A `halted` asset is marked in the UI and trading is disabled. Halt state is never inferred from a missing price — a fetch failure is a fetch failure, not a halt.

## Spread

```ts
spreadBps(bid, ask) // (ask − bid) / mid × 10_000, or null
```

Returns `null` rather than `0`, `NaN`, or `Infinity` when either side is non-positive. `null` renders as `—`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://bubblegum-reality.gitbook.io/bubblegum-reality-docs/architecture/pricing.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.