Wix

Add RoxyAPI to any Wix site or Wix Studio project and ship a natal chart tool, daily horoscope widget, tarot reading page, Life Path calculator, or full Vedic kundli explainer without running your own backend. One API key, 10 domains, 130+ endpoints, called from Wix Velo code with your key kept safe in the Secrets Manager. If you are building on Wix Studio and looking for a drop-in astrology, tarot, or numerology API, this is the page you need.

This guide covers Wix Velo (the JavaScript-based dev environment inside Wix Editor and Wix Studio). You do not need to leave Wix, host your own server, or use Vercel. Everything runs inside your Wix site using backend web modules and the standard wix-fetch client.

Before you start

• A RoxyAPI account and an API key. Grab one from the pricing page, or test endpoints first with the pre-filled test key on the interactive API reference.
• A Wix site with Dev Mode enabled. In the editor top bar click Dev Mode > Turn on Dev Mode (Wix Editor), or in Wix Studio the code side panel is already available.
• Ten minutes.

Architecture: why you want a backend web module

Wix Velo lets you call external APIs from both frontend (page code) and backend (server code). For RoxyAPI always use the backend path. Three reasons:

1. Your API key stays secret. Backend code never ships to the browser, so the key is never exposed in DevTools, page source, or network traces.
2. No CORS issues. Certain POST requests from browser code hit CORS restrictions. Backend calls bypass the browser entirely.
3. Wix Secrets Manager only works in backend code. Hardcoding the key in page code makes it trivial to steal.

The pattern is: put a wixFetch call inside a webMethod in a .web.js file under backend/, store the key in the Secrets Manager, call the web method from your page code. Wix handles the wire protocol for you.

Step 1: save your API key in the Secrets Manager

Your RoxyAPI key is a secret. Treat it like one.

1. In your Wix site dashboard, click Settings
2. Scroll to Developer Tools and open Secrets Manager
3. Click Add Secret
4. Name the secret ROXY_API_KEY (uppercase, underscore, no spaces)
5. Paste your RoxyAPI key from your account page as the value
6. Click Save

Wix encrypts the value and only gives your backend code access to it. You can rename or rotate the key later without touching any site code as long as the secret name stays the same.

Step 2: create a backend web module

Backend web modules are files with the .web.js extension under your site's Backend folder. Wix exposes every webMethod they export to your frontend page code.

1. In the Wix IDE (Wix Studio) or the Code panel (Wix Editor), find the Backend section in the sidebar
2. Click the + next to Backend and choose New .web.js file
3. Name the file roxy.web.js

Paste this into the file:

// backend/roxy.web.js
import { Permissions, webMethod } from "wix-web-module";
import wixFetch from "wix-fetch";
import wixSecretsBackend from "wix-secrets-backend";

const ROXY_BASE = "https://roxyapi.com/api/v2";

async function roxyGet(path) {
  const apiKey = await wixSecretsBackend.getSecret("ROXY_API_KEY");
  const response = await wixFetch(`${ROXY_BASE}${path}`, {
    method: "GET",
    headers: { "X-API-Key": apiKey },
  });
  if (!response.ok) {
    const body = await response.text();
    throw new Error(`RoxyAPI ${response.status}: ${body}`);
  }
  return response.json();
}

async function roxyPost(path, payload) {
  const apiKey = await wixSecretsBackend.getSecret("ROXY_API_KEY");
  const response = await wixFetch(`${ROXY_BASE}${path}`, {
    method: "POST",
    headers: {
      "X-API-Key": apiKey,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(payload),
  });
  if (!response.ok) {
    const body = await response.text();
    throw new Error(`RoxyAPI ${response.status}: ${body}`);
  }
  return response.json();
}

export const getDailyHoroscope = webMethod(
  Permissions.Anyone,
  async (sign) => {
    return roxyGet(`/astrology/horoscope/${sign}/daily`);
  }
);

export const getNatalChart = webMethod(
  Permissions.Anyone,
  async (birthData) => {
    return roxyPost("/astrology/natal-chart", birthData);
  }
);

What this file does:

• wixFetch is the Velo wrapper around fetch() for backend code. On the backend it uses node-fetch under the hood.
• wixSecretsBackend.getSecret("ROXY_API_KEY") pulls your key out of the Secrets Manager at call time. Nothing is hardcoded.
• webMethod(Permissions.Anyone, ...) wraps each exported function and declares who may call it. Permissions.Anyone allows any site visitor. Use Permissions.SiteMember or Permissions.Admin to restrict.
• roxyGet and roxyPost are local helpers that are not exported. They are not web methods themselves, just shared logic.

Web method files must end in .web.js. The older .jsw format still works for legacy sites but is deprecated by Wix. Use .web.js for anything new.

Step 3: call the web method from a page

Open any page in your site and switch to the Page Code panel.

// In any page's code panel
import { getDailyHoroscope, getNatalChart } from "backend/roxy.web";

$w.onReady(async () => {
  try {
    const horoscope = await getDailyHoroscope("aries");
    $w("#horoscopeText").text = horoscope.overview;
    $w("#luckyNumber").text = String(horoscope.luckyNumber);
    $w("#luckyColor").text = horoscope.luckyColor;
  } catch (err) {
    console.error("RoxyAPI call failed", err);
    $w("#horoscopeText").text = "Could not load today's horoscope. Please try again later.";
  }
});

A few things to note:

• The import path is backend/roxy.web without the .js extension.
• $w("#horoscopeText") is how Velo references page elements. Replace the IDs with whatever you set on your text elements in the Wix editor.
• Every web method call is async. Wrap them in try/catch and show a fallback message if the call fails.

Save and preview your site. You should see a horoscope rendered on the page.

Example: natal chart from a form

This is the most common production use case on Wix: a form that captures birth data and renders a full natal chart with planet positions, houses, and aspects.

Frontend page code

// Page with a birth form and a result container
import { getNatalChart } from "backend/roxy.web";

$w.onReady(() => {
  $w("#submitButton").onClick(async () => {
    $w("#submitButton").disable();
    $w("#statusText").text = "Calculating your chart...";

    const payload = {
      datetime: `${$w("#birthDate").value}T${$w("#birthTime").value}:00`,
      latitude: Number($w("#latitude").value),
      longitude: Number($w("#longitude").value),
      timezone: $w("#timezone").value || "UTC",
    };

    try {
      const chart = await getNatalChart(payload);
      $w("#sunSign").text = chart.planets.sun.sign;
      $w("#moonSign").text = chart.planets.moon.sign;
      $w("#risingSign").text = chart.houses[0].sign;
      $w("#resultBox").show();
      $w("#statusText").text = "";
    } catch (err) {
      $w("#statusText").text = "Could not generate chart. Please check your inputs.";
      console.error(err);
    } finally {
      $w("#submitButton").enable();
    }
  });
});

What the form needs

Add these elements to your page in the Wix editor:

Example: daily horoscope widget

The simplest possible integration. One button, 12 signs, one backend call.

// Page with 12 zodiac buttons and a result panel
import { getDailyHoroscope } from "backend/roxy.web";

const SIGNS = [
  "aries", "taurus", "gemini", "cancer",
  "leo", "virgo", "libra", "scorpio",
  "sagittarius", "capricorn", "aquarius", "pisces",
];

$w.onReady(() => {
  SIGNS.forEach((sign) => {
    $w(`#btn_${sign}`).onClick(async () => {
      $w("#horoscopeText").text = "Loading...";
      try {
        const result = await getDailyHoroscope(sign);
        $w("#signHeading").text = sign.toUpperCase();
        $w("#horoscopeText").text = result.overview;
        $w("#luckyColor").text = `Lucky color: ${result.luckyColor}`;
        $w("#luckyNumber").text = `Lucky number: ${result.luckyNumber}`;
      } catch (err) {
        $w("#horoscopeText").text = "Horoscope unavailable. Try again in a moment.";
      }
    });
  });
});

Cache web method results

Every RoxyAPI daily horoscope is stable for 24 hours. Every dream symbol lookup is stable forever. There is no reason to hit the API on every page load. Wix web methods support built-in caching via the options argument.

export const getDailyHoroscope = webMethod(
  Permissions.Anyone,
  async (sign) => {
    return roxyGet(`/astrology/horoscope/${sign}/daily`);
  },
  {
    cache: {
      ttl: 3600,
      tags: ["roxy-horoscope"],
    },
  }
);

ttl is the cache lifetime in seconds (3600 = 1 hour, 86400 = 24 hours). tags is required for caching to take effect. Wix caches the return value per set of arguments, so each zodiac sign is cached independently.

Benefits:

• Your RoxyAPI quota drops dramatically for high-traffic pages
• Page loads feel instant because the second request is served from cache
• Same code, one extra options object

Troubleshooting

401 api_key_required

{
  "error": "API key is required. Provide via X-API-Key header or api_key query param",
  "code": "api_key_required"
}

Your backend code did not attach the header. Check:

1. The secret name in getSecret("ROXY_API_KEY") exactly matches the name you saved in the Secrets Manager, case-sensitive
2. The header key is X-API-Key with hyphens, not XAPIKey or ApiKey
3. You are calling the web method from the frontend, not calling wixFetch directly from page code (page code cannot read secrets)

401 invalid_api_key

The header reached RoxyAPI but the key value is wrong. Open the Secrets Manager, delete the secret, recreate it, and paste the key again with no leading or trailing spaces.

429 rate_limited

You hit your plan quota. Every response carries X-RateLimit-Remaining and X-RateLimit-Reset. Add caching to your web methods (see section above) or upgrade on the pricing page.

500 "Could not resolve wix-fetch" or "wixSecretsBackend is not defined"

You are calling backend-only modules from frontend page code. Move the call into a .web.js file and import the web method from your page code instead.

Chart returns but elements do not update

Velo element access ($w("#elementId")) only works inside $w.onReady or event handlers. If you call a web method before onReady fires, the element may not exist yet. Keep all API calls inside handlers or inside $w.onReady.

Extend your integration

You have one endpoint working in Wix Velo. Adding the next 130 is the same pattern: add another webMethod to your .web.js file, change the URL, change the JSON body, the auth and Secrets Manager setup stay exactly as you configured them. 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 with the pre-filled test key, see the exact request and response shape, then paste the same URL and body into a new Velo webMethod.
• Domain guides — short walkthroughs of which endpoints to call in what order for a given product:
  • 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
• One file, many methods. Keep adding webMethods to the same roxy.web.js file. The getSecret call at the top is shared, so every new method picks up the API key automatically. One Secrets Manager entry, every endpoint unlocked.

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

What to build first

• Natal chart generator. Form captures birth date, time, latitude, longitude. Backend webMethod calls /astrology/natal-chart and returns planet positions, houses, and aspects. Render with Velo text or a custom canvas element. This is what Wix customers ask for most.
• Daily horoscope on homepage. 12 buttons, one backend call per click, cached for 1 hour per sign. Looks alive, costs almost nothing in API quota.
• Tarot card reading page. Form captures the question, backend calls /tarot/spreads/three-card or /tarot/spreads/celtic-cross, page renders the cards in sequence. The full 78-card Rider-Waite deck works out of the box.
• Life Path calculator. Name + birth date form, backend calls /numerology/life-path, page displays the number and its meaning using Pythagorean numerology rules with master number detection.
• Vedic kundli page with nakshatra and Vimshottari Dasha. Form captures birth data, backend calls /vedic-astrology/birth-chart, page renders planets with nakshatra, Vimshottari Dasha periods, and panchang.
• Dream meaning lookup. Search input, backend calls GET /dreams/symbols, page renders matching symbols with psychological and spiritual interpretations.
• Transit report for any future date. Perfect companion to the natal chart page. Backend calls /astrology/transits, page highlights which planets are aspecting the user's natal positions today.

FAQ

Can I use RoxyAPI on a free Wix site?

Yes, if the free Wix plan allows Velo Dev Mode on your account. Wix has historically restricted Velo to paid plans in some regions, but most accounts have access. RoxyAPI does not care which Wix tier you are on, as long as Velo can make outbound HTTPS calls.

Does this work with Wix Studio and the older Wix Editor?

Yes, both. The Velo APIs (wix-fetch, wix-secrets-backend, wix-web-module) are identical across Wix Studio and Wix Editor. The IDE experience differs but the code is the same.

Do I need to set up a Node.js backend to use RoxyAPI on Wix?

No. Wix Velo runs backend code for you inside Wix. You write a .web.js file in your site's Backend folder, Wix hosts and executes it, and your page code imports from it. There is no server to deploy.

How do I handle errors gracefully on the page?

Wrap every web method call in try/catch. On error, show a friendly fallback message in a status text element and log the real error to the Wix Developer Console with console.error(). Users should never see raw API error JSON.

Can I cache API responses on Wix to reduce my RoxyAPI bill?

Yes. Pass a cache object to webMethod() with a ttl in seconds and a non-empty tags array. Wix caches the return value per argument set. For daily horoscopes set ttl: 3600 or higher. Do not cache user-specific responses.

How accurate are the astrology calculations for a production Wix site?

Every position and chart comes from Roxy Ephemeris, verified against NASA JPL Horizons. See the methodology page for accuracy details, including sub-arcsecond planet positions and standard Placidus house calculation. This is the same engine every other RoxyAPI integration uses.

What Wix element should I use to render a natal chart?

For text-only output, a $w("#text") element is enough. For a visual chart wheel, use a Wix HTML iframe component and render the chart with a lightweight SVG library inside the iframe. We are working on a hosted chart widget you can embed directly. Reply to your onboarding email if you want early access.

Can I make the API call from frontend page code instead of a backend web module?

Technically yes for GET endpoints, but you should not. Frontend calls expose your API key in the browser and hit CORS restrictions on some endpoints. Always route through a .web.js backend module with the key stored in the Secrets Manager.

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 ready-made Wix template for RoxyAPI?

Not yet as an official template, but our astrology guide and Vedic astrology guide have the endpoint flows you need. If you build a public Wix template for astrology, tarot, or numerology on RoxyAPI and want it featured on our starters page, reply to your onboarding email with the site URL. The first community Wix template gets a free month on us.