Use RoxyAPI with Bolt

Ship a daily horoscope widget, a Life Path calculator, or a tarot reading page inside a 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.
2. A Bolt account. Sign up free at bolt.new.
3. A browser. Bolt runs entirely on StackBlitz, no local setup required.

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.

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

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 "https://roxyapi.com/api/v2/astrology/horoscope/aries/daily" \
  -H "X-API-Key: $ROXY_API_KEY"

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);

// 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 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, Vedic Astrology, Tarot, Numerology, I Ching, Dreams
• AI prompt recipes 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 has the full App Router reference behind every Bolt-generated app.
• The AI chatbot tutorial wires multiple Roxy domains into a conversational app.
• The SDK guide covers every typed method for cleaner Bolt prompts.
• Browse the API reference for every endpoint across 12 domains.