# Use RoxyAPI with Bolt

> Ship a daily horoscope widget, a Life Path calculator, or a tarot reading page inside a [Bolt.new](https://bolt.new) app in under 20 minutes.

Bolt generates full-stack Next.js, Astro, Vite, and Remix apps from a chat prompt. RoxyAPI is the fastest way to give that app a spiritual-data backend without writing one yourself. This page is the Bolt-specific overlay on top of our Next.js patterns: which prompt to paste, where to put the API key, and the security traps Bolt falls into on the first try.

## What you can build on Bolt

- Daily horoscope page with 12 zodiac buttons and cached server rendering
- Birth chart generator that captures date, time, and place in a form
- Tarot card of the day with cover imagery pulled from the response
- Life Path calculator that takes a name and birth date and returns a full meaning block
- Vedic kundli page with nakshatra, Vimshottari Dasha, and panchang
- Dream symbol search box with an instant lookup against the dictionary

## What you need, 30 seconds

1. A Roxy API key. Get one on the [pricing page](/pricing).
2. A Bolt account. Sign up free at [bolt.new](https://bolt.new).
3. A browser. Bolt runs entirely on StackBlitz, no local setup required.

**Tip: Bolt almost always produces a Next.js app. If you want the underlying patterns before prompting, read the [Next.js integration page](/docs/integrations/nextjs) first. This page is the thin Bolt layer over that.**

## Step 1, connect your first endpoint

Bolt reads environment variables from a `.env` file at the project root. Create the file, paste the key, and Bolt hot-reloads.


### Ask Bolt in chat

Paste this into the Bolt chat:

```
Create a .env file at the project root with ROXY_API_KEY=your_roxyapi_key_here
```

Replace `your_roxyapi_key_here` with your actual key. Bolt creates the file and the next generated route can read `process.env.ROXY_API_KEY`.

### Edit the file directly

1. In the Bolt file tree, click **New File** at the project root.
2. Name it `.env`.
3. Paste:
   ```
   ROXY_API_KEY=your_roxyapi_key_here
   ```
4. Save. Bolt hot-reloads and the variable is live on the server.


**Warning: If you are screen-sharing or using a free Bolt workspace where chat history is retained, use the file-editor path. Bolt chat logs can be reviewed later.**

Once the key is in place, lead every Bolt prompt with this block so the generator knows exactly how to call Roxy:

```
Use the RoxyAPI for spiritual data (astrology, tarot, numerology, and more).
Base URL: https://roxyapi.com/api/v2
Auth: X-API-Key header, read from process.env.ROXY_API_KEY (server-side only).
Reference: https://roxyapi.com/llms.txt for the full endpoint list.
Never call RoxyAPI from a client component. Always proxy through a server component, server action, or route handler.
```

Then add the feature description after it:

```
Build a daily horoscope page that lets the user pick a zodiac sign and shows the overview, love, career, lucky number, and lucky color. Use GET /astrology/horoscope/{sign}/daily.
```

## Step 2, ship a useful feature

Here is the full flow for a daily horoscope page: a server component that fetches the sign, caches for an hour, and renders HTML. No client JavaScript needed.


### curl

Test the call first so you know the key works:

```bash
curl "https://roxyapi.com/api/v2/astrology/horoscope/aries/daily" \
  -H "X-API-Key: $ROXY_API_KEY"
```

### TypeScript SDK

Ask Bolt: *"Install @roxyapi/sdk and use it for all RoxyAPI calls."*

```typescript
import { createRoxy } from '@roxyapi/sdk';

const roxy = createRoxy(process.env.ROXY_API_KEY!);

const { data } = await roxy.astrology.getDailyHoroscope({
  path: { sign: 'aries' },
});

console.log(data.overview);
console.log(data.luckyNumber);
```

### Next.js server component

The pattern Bolt generates when you use the prompt above:

```tsx
// app/horoscope/[sign]/page.tsx
type Props = { params: Promise<{ sign: string }> };

async function getHoroscope(sign: string) {
  const res = await fetch(
    `https://roxyapi.com/api/v2/astrology/horoscope/${sign}/daily`,
    {
      headers: { 'X-API-Key': process.env.ROXY_API_KEY! },
      next: { revalidate: 3600 },
    },
  );
  if (!res.ok) throw new Error(`RoxyAPI ${res.status}`);
  return res.json();
}

export default async function HoroscopePage({ params }: Props) {
  const { sign } = await params;
  const data = await getHoroscope(sign);
  return (
    <main>
      <h1>{data.sign} daily</h1>
      <p>{data.overview}</p>
      <small>Lucky {data.luckyNumber}, color {data.luckyColor}</small>
    </main>
  );
}
```


The response includes `overview`, `love`, `career`, `health`, `finance`, `advice`, `luckyNumber`, `luckyColor`, `compatibleSigns`, `activeTransits`, `moonSign`, `moonPhase`, and `energyRating`. Bind any field to any element.

## Step 3, scale to the full surface

You have one endpoint live. The next 130 are the same pattern: paste the URL into your prompt, Bolt generates the route handler, the env var stays where it is. Start here:

- **[API reference](/api-reference)** has a live pre-filled test key. Try a call in the browser, copy the curl, paste into Bolt with *"add a route handler that does this"*.
- **Domain guides** for which endpoints to call in what order:
  - [Western Astrology](/docs/guides/astrology), [Vedic Astrology](/docs/guides/vedic-astrology), [Tarot](/docs/guides/tarot), [Numerology](/docs/guides/numerology), [I Ching](/docs/guides/iching), [Dreams](/docs/guides/dreams)
- **[AI prompt recipes](/docs/prompts)** are tested system prompts that produce working Bolt apps on the first try.

## The 5 AI mistakes Bolt makes

Watch for these, and tell Bolt to fix them in plain English.

### Mistake 1: NEXT_PUBLIC_ROXY_API_KEY in .env

Bolt sometimes prefixes the env var with `NEXT_PUBLIC_` to "make it accessible to the frontend". That inlines the value into the client bundle at build time. Anyone with DevTools can copy the key.

Fix in chat: *"Rename NEXT_PUBLIC_ROXY_API_KEY to ROXY_API_KEY everywhere. The RoxyAPI key must never reach the client bundle."*

### Mistake 2: fetch in a 'use client' component

Bolt sometimes drops the fetch straight into a client component. That sends the call from the user browser and leaks the key if the env is also exposed.

Fix in chat: *"Move the RoxyAPI fetch out of the client component. Put it in a server component or a route handler under app/api/."*

### Mistake 3: hardcoded key in source

Bolt occasionally copies your key from the prompt into a `.ts` or `.tsx` file as a string literal.

Fix in chat: *"Search the project for the literal API key string and replace every occurrence with process.env.ROXY_API_KEY. The key must only live in .env."*

### Mistake 4: no fetch caching

Next.js 15 and 16 made `fetch` uncached by default. Without `next: { revalidate: N }`, every page render hits RoxyAPI.

Fix in chat: *"Add next: { revalidate: 3600 } to every fetch to roxyapi.com. Daily horoscopes and tarot cards do not need to refresh more than once per hour."*

### Mistake 5: no error handling

Bolt usually generates a happy-path fetch. When the key is wrong or the quota is hit, the page just breaks.

Fix in chat: *"Wrap every RoxyAPI fetch in error handling. Show a clear fallback for 401 (key issue) and 429 (quota)."*

## Deploy from Bolt

Bolt Cloud is the default one-click target. Your `.env` is picked up automatically.

For your own Netlify or Vercel account:

1. Open **Project settings, Applications**, connect Netlify or Vercel.
2. Open **Project settings, Domains and Hosting**, switch the provider.
3. Click **Publish**.
4. In the host dashboard, add `ROXY_API_KEY` as an environment variable, then redeploy.

## Gotchas

- **Backend-only key.** Never put `ROXY_API_KEY` in a `'use client'` file or prefix it with `NEXT_PUBLIC_`. Bolt makes this mistake once per project; catch it before you deploy.
- **Timezone.** Prefer IANA strings (`"America/New_York"`). Decimal offsets like `-5` are accepted but do not handle daylight saving time. The Roxy server resolves IANA to the DST-correct offset for the request date.
- **Rate limits.** Every plan has daily and monthly caps. Bolt apps with no caching and an autofetch hook can burn a month of quota in an hour. Always cache daily content for at least an hour.
- **.gitignore.** If you sync Bolt to GitHub, confirm `.env` is in `.gitignore` before the first push. Ask Bolt: *"Add .env to .gitignore so my API key does not get committed."*
- **Chat history.** Paid Bolt accounts have higher retention controls. Do not paste production keys into chat on free tier.

## What to build next

- The [Next.js integration](/docs/integrations/nextjs) has the full App Router reference behind every Bolt-generated app.
- The [AI chatbot tutorial](/docs/tutorials/ai-chatbot) wires multiple Roxy domains into a conversational app.
- The [SDK guide](/docs/sdk) covers every typed method for cleaner Bolt prompts.
- Browse the [API reference](/api-reference) for every endpoint across 12 domains.