> 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/reality-score.md).

# The Reality Score

A deterministic 0–100 measure of **execution quality at the size you actually chose**. Same inputs always produce the same score. Every input is displayed alongside the result.

> The Reality Score is not a recommendation, a price target, or investment advice. It says how well a specific trade would execute right now — nothing about whether the asset is worth owning.

## Components

| Weight  | Component       | What it measures                                              |
| ------- | --------------- | ------------------------------------------------------------- |
| 25      | Quote available | Real executable liquidity was returned for this pair and size |
| 25      | Execution cost  | Effective cost in bps vs the multiplier-adjusted reference    |
| 20      | Depth at size   | Whether the chosen size degrades the fill                     |
| 15      | Route diversity | Number of distinct liquidity sources in the route             |
| 10      | Freshness       | Age of the reference price and the quote                      |
| 5       | Clean state     | Not halted, active, no pending corporate action               |
| **100** |                 |                                                               |

## Hard floors

* **No route → low score, always.** Missing liquidity cannot be compensated by a tight reference spread. If the 25-point availability component is zero, the score is forced low rather than allowed to look mid-range.
* **Halted asset → marked, and trading disabled.** The score is informational only in that state.
* **Incomplete simulation → cannot score as clean.** 0x reporting an incomplete simulation is treated as an execution risk, not a formatting detail.

## Execution cost

Directional, computed in `src/lib/money.ts`:

```ts
executionCostBps({ side, usdgAmount, tokenAmount, referencePrice })
```

| Side   | Comparison                                    | Positive cost means              |
| ------ | --------------------------------------------- | -------------------------------- |
| `buy`  | USDG sold vs `tokens received × adjusted ask` | You paid more than reference     |
| `sell` | `tokens sold × adjusted bid` vs USDG received | You received less than reference |

Positive is always worse. Returns `null` when any input is non-positive, and `null` propagates as `—` rather than as a zero-cost claim.

## Reading a score

Scores are banded for legibility, but the band is a summary of the breakdown — not a substitute for it. The score panel lists each component's earned points and the raw input that produced them, so a 62 caused by a thin route reads differently from a 62 caused by a stale price.

## Worked shape

```
Reality Score  74 / 100

  Quote available      25 / 25   liquidity returned, 3 sources
  Execution cost       17 / 25   +48.3 bps vs adjusted reference
  Depth at size        14 / 20   fill degrades above ~2.5k USDG
  Route diversity      12 / 15   3 sources
  Freshness             6 / 10   reference 11s old, quote 4s old
  Clean state           0 /  5   pending multiplier effective in 2 days

  Adjusted ask   $214.87   ( underlying $21.487 × 10 )
  Spread         18.4 bps
```

## Tests

`src/lib/__tests__/reality-score.test.ts` covers every component weight independently, the missing-route floor, halted handling, banding boundaries, and stale-input behaviour.


---

# 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/reality-score.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.