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

# Environment & Secrets

Bubblegum Reality keeps a hard line between server-only secrets and publishable client config. Nothing in the first table may ever appear in browser code.

## Server-only secrets

Read exclusively inside `.handler()` bodies of server functions via `process.env`.

| Variable                                   | Required                      | Purpose                                                                  |
| ------------------------------------------ | ----------------------------- | ------------------------------------------------------------------------ |
| `ZEROX_API_KEY`                            | Yes, for quoting/execution    | Authenticates `api.0x.org` calls (`0x-api-key` header, `0x-version: v2`) |
| `ROBINHOOD_RPC_URL`                        | Recommended                   | Private RPC for chain `4663` reads; falls back to the public RPC         |
| `RESTRICTED_REGIONS`                       | Optional                      | Comma-separated ISO codes overriding the default restricted list         |
| `LOVABLE_API_KEY`                          | Yes, for Reality Check        | Authenticates the AI gateway call                                        |
| `SUPABASE_URL`, `SUPABASE_PUBLISHABLE_KEY` | Yes, with the backend enabled | Server-side database access as the signed-in user                        |
| `SUPABASE_SERVICE_ROLE_KEY`                | Privileged writes only        | AI insight cache; bypasses RLS, so handler-scoped imports only           |

## Publishable client config

Exposed to the browser through `import.meta.env`. Safe by design.

| Variable                                             | Purpose                                   |
| ---------------------------------------------------- | ----------------------------------------- |
| `VITE_WALLETCONNECT_PROJECT_ID`                      | WalletConnect v2 project ID (publishable) |
| `VITE_SUPABASE_URL`, `VITE_SUPABASE_PUBLISHABLE_KEY` | Browser database client (RLS applies)     |

## Rules

* **Read secrets inside handlers, not at module scope.** Environment injection happens at call time; module-scope reads yield `undefined`.
* **Never prefix a secret with `VITE_`.** That prefix is a publish instruction.
* **Server-only files use the `.server.ts` suffix** (`zerox.server.ts`, `rpc.server.ts`, `robinhood.server.ts`, `eligibility.server.ts`, `portfolio.server.ts`, `reality-check.server.ts`, `ai-gateway.server.ts`). Import protection blocks these from client bundles by filename.
* **Components import `*.functions.ts`, never `*.server.ts`.** A single direct import pulls the server module into the client graph and breaks the build.
* **No arbitrary proxying.** The RPC helper only talks to chain `4663`; the 0x helper only accepts allowlisted canonical token addresses. Neither accepts a caller-supplied endpoint.

## Verifying no secret ships

After a production build, grep the client bundle:

```bash
bun run build
grep -rl "ZEROX_API_KEY\|ROBINHOOD_RPC_URL" dist/client || echo "clean: no server secrets in client bundle"
```

This grep is part of the release checklist in [Security](/bubblegum-reality-docs/operations/security.md).

## Local `.env`

```env
# server-only — never commit real values
ZEROX_API_KEY=
ROBINHOOD_RPC_URL=
RESTRICTED_REGIONS=US,CU,IR,KP,SY,RU,BY,VE,MM,OTHER

# publishable
VITE_WALLETCONNECT_PROJECT_ID=
```

`.env` is gitignored. Configure secrets through your hosting platform's secrets manager rather than a committed file.


---

# 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/environment.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.