> 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/getting-started/quickstart.md).

# Quickstart

## Prerequisites

* **Node.js 20+** (or [Bun](https://bun.sh) 1.1+)
* An EIP-1193 wallet — MetaMask or Robinhood Wallet — for anything beyond read-only browsing
* A 0x API key and an RPC endpoint for Robinhood Chain (see [Environment & Secrets](/bubblegum-reality-docs/getting-started/environment.md))

## Install and run

```bash
git clone <this-repository-url>
cd bubblegum-reality
bun install          # or: npm install
bun run dev          # or: npm run dev
```

The dev server starts on <http://localhost:8080>.

## Scripts

| Command             | Purpose                                          |
| ------------------- | ------------------------------------------------ |
| `bun run dev`       | Vite dev server with HMR                         |
| `bun run build`     | Production build                                 |
| `bun run build:dev` | Development-mode build (used for preview parity) |
| `bun run preview`   | Serve the production build locally               |
| `bun run test`      | Vitest suite (single run)                        |
| `bun run lint`      | ESLint across the repo                           |
| `bun run format`    | Prettier write                                   |

## First run, in order

1. **Land on `/`.** The hero plays a two-clip looped film. Video audio is permanently muted; the soundtrack is a separate, opt-in audio track behind the sound toggle. The boot sequence is skippable with `Esc`, `Enter`, click, or tap, and the skip is remembered in `localStorage`.
2. **Check the status strip.** Chain ID, RPC latency, asset count, USDG route state, US market session, and data timestamp. Any cell whose request did not succeed renders as unknown or degraded — never as a placeholder value.
3. **Connect a wallet** from the header. If the wallet is not on chain `4663`, a banner offers `wallet_switchEthereumChain`, falling back to `wallet_addEthereumChain`. Success is only asserted after the wallet itself reports `4663`.
4. **Open `/markets`.** The canonical stock-token registry with multipliers, tradability, halt state, and extended-hours flags.
5. **Open `/terminal`.** Pick a side and an amount. You get an indicative price, then the [Reality Score](/bubblegum-reality-docs/architecture/reality-score.md) breakdown.
6. **Clear the** [**eligibility gate**](/bubblegum-reality-docs/compliance/eligibility.md)**.** Region, restricted-person confirmation, risk acknowledgement, tokenized-debt acknowledgement. Enforced both client-side and server-side, and it fails closed.
7. **Execute.** Exact-amount approval to the 0x allowance spender, then a firm quote, then a wallet-signed transaction with a Blockscout link.

## What happens without secrets

The app still builds and runs. Live surfaces degrade honestly:

* No `ZEROX_API_KEY` → routing reports "not configured"; quoting and execution are disabled with that exact reason.
* No `ROBINHOOD_RPC_URL` → chain reads fall back to the rate-limited public RPC and the status strip labels the source as `public`.

No mock data is ever substituted for a failed request.


---

# 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/getting-started/quickstart.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.