Bolt

Build an astrology, tarot, numerology, dream, or full spiritual app with Bolt.new and connect it to RoxyAPI in five minutes. Bolt is an AI-powered full-stack app builder that runs entirely in your browser on StackBlitz. You describe what you want, Bolt generates a working Next.js (or Astro, Vite, Remix) app. This page covers the parts Bolt's AI gets wrong on the first try and how to make sure your RoxyAPI key never leaks to the browser.

If you have already used Bolt, you have probably noticed that the generated code sometimes puts API keys in client components, calls third-party APIs from the browser, or hardcodes secrets. This page exists to keep you out of those traps.

Before you start

• A RoxyAPI account and an API key. Grab one from the pricing page, or test endpoints first with the pre-filled key on the interactive API reference.
• A Bolt account. Sign up free at bolt.new. Free tier works for prototyping; the paid tier gives you more credits per day.
• Five minutes.

Step 1: store your API key as an environment variable

Bolt projects use a .env file in the project root for environment variables, exactly like a normal Next.js project. There are two ways to add your RoxyAPI key.

Option A: ask Bolt directly (easiest)

In the Bolt chat, type:

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 will create the file for you. Confirm it appears in the file tree on the left.

Option B: edit the .env file directly

1. In the Bolt file tree, click New File at the project root
2. Name it .env
3. Paste this single line:

   ROXY_API_KEY=your_roxyapi_key_here

4. Save the file

After either option, give Bolt a moment to pick up the new variable. If your app does not see the env var after editing .env, ask Bolt in chat: "restart the dev server so the new env var loads". Bolt usually hot-reloads .env changes, but a manual restart guarantees it.

Step 2: prompt Bolt to use RoxyAPI correctly

The prompts in /docs/prompts are the ready-to-paste templates for Bolt. The short version: lead every Bolt prompt with the four lines below. They tell Bolt exactly how to call RoxyAPI without leaking the key.

Use the RoxyAPI for spiritual data (astrology, tarot, numerology, etc.).
Base URL: https://roxyapi.com/api/v2
Auth: X-API-Key header, read from process.env.ROXY_API_KEY (server-side only).
Reference: read 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 actual feature description after that block:

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

Bolt now has everything it needs: the auth method, the env var name, the endpoint, the response shape, and the security rule.

The 5 AI mistakes Bolt makes (and how to fix them in chat)

Bolt's AI is fast, but it makes the same handful of security mistakes every vibe-coder AI tool makes. Watch for these, and tell Bolt to fix them in plain English. Bolt will rewrite the affected file in seconds.

Mistake 1: putting NEXT_PUBLIC_ROXY_API_KEY in .env

Bolt sometimes prefixes the env var with NEXT_PUBLIC_ to "make it accessible to the frontend". This is wrong. NEXT_PUBLIC_* variables are inlined into the client bundle by the Next.js compiler at build time. Anyone with DevTools can read them.

Fix in chat:

Rename NEXT_PUBLIC_ROXY_API_KEY to ROXY_API_KEY everywhere in the project, including .env, all imports, and all references. The RoxyAPI key must never reach the client bundle.

Mistake 2: calling RoxyAPI from a 'use client' component

Bolt sometimes drops fetch("https://roxyapi.com/...") into a client component with 'use client' at the top. This sends the call from the user's browser, which leaks the API key (if the env var is also exposed) and hits CORS issues.

Fix in chat:

Move the RoxyAPI fetch out of the client component. Put it in a server component (no 'use client') or a route handler under app/api/. The client component should call our own API route, not roxyapi.com directly.

Mistake 3: hardcoding the API key in source files

Sometimes Bolt copies your key from the prompt into a .ts or .tsx file as a string literal. This commits your key to the project history and exposes it the moment you share or fork the project.

Fix in chat:

Search the entire 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: forgetting fetch caching

Next.js 15 and 16 made fetch() uncached by default. On a daily horoscope page, every page render hits RoxyAPI. Bolt does not always add caching headers automatically.

Fix in chat:

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

Mistake 5: not handling 401 / 429 / 404 errors

Bolt usually generates a happy-path fetch with no error handling. When the key is wrong or the quota is hit, the page just shows a broken state.

Fix in chat:

Wrap every RoxyAPI fetch in error handling. If the response status is not 200, render a fallback message instead of crashing the page. Show a clear error if the status is 401 (key issue) or 429 (quota).

Test your API key outside Bolt first

Before you trust Bolt's generated code, confirm your key works on its own. Open a terminal and run:

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

If that prints JSON, the key is good and any error in Bolt's output is a code issue, not a RoxyAPI issue. If it returns 401, the key is wrong. Check at your account page.

Deploy from Bolt

Bolt's default one-click deploy is the Publish button in the top-right corner, which ships to Bolt Cloud hosting (powered by Netlify under the hood). For Bolt Cloud deploys, environment variables are managed inside Bolt itself — your .env file is picked up automatically.

If you want to publish to your own Netlify or Vercel account instead:

1. Open Project settings → Applications
2. Click Connect in the Netlify (or Vercel) section and authorize Bolt
3. Open Project settings → Domains & Hosting and switch the provider dropdown to your chosen host
4. Click Publish
5. After deploy, go to your host's dashboard and add ROXY_API_KEY as an environment variable:
   • Netlify: Site configuration → Environment variables
   • Vercel: Settings → Environment Variables
6. Trigger a redeploy so the host bakes in the env var

Extend your integration

You have one endpoint working in your Bolt app. Adding the next 130 is the same pattern: paste the URL into your prompt, Bolt generates the route handler, you make sure the env var pattern stays the same. Three places to find the next endpoint to wire up:

• Interactive API reference — Scalar-powered live docs for every endpoint across all 10 domains. Try a call in the browser, copy the curl example, paste it into Bolt with "add a route handler that does this" and Bolt builds it.
• Domain guides — short walkthroughs of which endpoints to call in what order:
  • Western Astrology guide — natal charts, horoscopes, synastry, transits
  • Vedic Astrology guide — kundli, Gun Milan, Vimshottari Dasha, panchang, KP
  • Tarot guide — daily card, three-card, Celtic Cross, custom spreads
  • Numerology guide — Life Path, Expression, Soul Urge, personal year
• AI prompt recipes — full ready-to-paste prompts for tarot, numerology, Vedic astrology, dreams, and more. Each is a tested system prompt that produces a working app on the first try in Bolt.

The pattern is the same every time: horoscope today, compatibility tomorrow, kundli next week. One env var, every endpoint unlocked.

What to build first

• Daily horoscope page. One server component that fetches GET /astrology/horoscope/{sign}/daily and renders it. Cached for an hour. Bolt builds this in under a minute with the right prompt.
• Tarot card of the day page. Server component fetching POST /tarot/daily. Display card name, image (use the URL from the response), and meaning.
• Life Path calculator. Form with name and birth date → server action calls POST /numerology/life-path → display the number with its meaning.
• Zodiac compatibility checker. Two zodiac sign dropdowns → server action calls POST /astrology/compatibility-score → display the score with category breakdowns.
• Birth chart generator. Form with date, time, latitude, longitude, timezone → server action calls POST /astrology/natal-chart → render the planets, houses, and aspects.
• Dream symbol search. Search input → server action calls GET /dreams/symbols with a query → render matching symbols.

Want a complete reference app to clone instead of generating from scratch? See our free starter apps — most are Next.js and you can fork them on StackBlitz directly.

FAQ

How do I connect Bolt to RoxyAPI?

Add a .env file with ROXY_API_KEY=your_key, lead your Bolt prompt with the four-line auth context block from Step 2, and tell Bolt to put RoxyAPI fetches in server components or route handlers (never in client components). The full pattern is in the Step 2 section.

Does Bolt support backend code or only frontend?

Bolt generates full-stack apps. For Next.js projects (the default), it generates server components, server actions, and API route handlers — exactly the right places to call RoxyAPI from. It also supports Astro, Vite, and Remix templates with similar server-side primitives.

How do I keep my API key out of Bolt's chat history?

Use the Option B path in Step 1: edit the .env file directly in the file tree instead of asking Bolt to create it via chat. The chat history may be retained by Bolt for free-tier users; the file system is not exposed.

My Bolt app calls RoxyAPI from the client and the key is leaked. How do I fix it?

Tell Bolt in chat: "Move every fetch to roxyapi.com out of client components. Put each one in either a server component, a server action, or a route handler under app/api/. Never call roxyapi.com from a 'use client' file." Bolt will rewrite the affected files in seconds.

How accurate are the astrology calculations under a Bolt-generated app?

Every position comes from Roxy Ephemeris, verified against NASA JPL Horizons. See the methodology page for accuracy details. Same engine for every endpoint, regardless of which integration calls it.

Can I use the TypeScript SDK in Bolt?

Yes. Tell Bolt: "Install @roxyapi/sdk and use it instead of raw fetch for all RoxyAPI calls." The SDK gives you full type safety, autocomplete on every endpoint, and exact response types. See the SDK reference for the full API.

Where do I get a RoxyAPI key?

Visit the pricing page for paid plans, or try the interactive API reference with a pre-filled test key first. Plans start at 5,000 requests per month.

Is there a Bolt template for RoxyAPI?

Not yet. If you build a public Bolt template for astrology, tarot, or numerology on RoxyAPI and want it featured on our starters page, reply to your onboarding email with the template URL. The first community Bolt template gets a free month on us.