DEV Community: Nick

I Built an AI Astrology Companion With Memory. Here Is the $1M ARR Napkin Math

Nick — Sat, 01 Aug 2026 11:15:11 +0000

Right, so. Picture me at 3am, eleven browser tabs deep, cross-checking a planetary longitude against three different websites that all disagreed with each other by a couple of arcminutes, eating cereal out of a mug because every actual bowl I own was in the sink.

That was my "astrology app" in month two. Not the app. Just the part where I try to work out where Saturn was.

I want to be really clear about how bad this was, because I think a lot of devs walk into this exact wall. I was not building a product. I was doing unpaid astronomy homework. And the worst part is you cannot even tell when you get it wrong. A birth chart that is subtly broken looks completely fine. It renders. It has planets in it. Your test users go "ooh, so accurate". Meanwhile the one actual astrologer who signs up takes about nine seconds to go "your ascendant is a whole sign off, mate" and never comes back.

It is like shooting blind in a dark room and everyone in the room politely telling you that you are hitting the target.

So here is the writeup I wish I had found on day one: the stack, the memory layer, the grounding rule that stops the LLM inventing charts, and the load math that decides whether this thing is a business or an API bill with a UI on top.

TL;DR

Do not compute ephemeris yourself. Ground the LLM on a verified insight API and let the model do voice, not math.

Stack: Next.js App Router, Supabase (Postgres, auth, RLS, pgvector), Vercel AI SDK, and the typed @roxyapi/sdk for the calculations.

Memory is yours, calculation is stateless. Store the natal chart once. It is immutable. This one decision is the entire cost model.

Users switch domains mid-conversation (transits, then tarot, then human design, then I Ching, then numerology). One key covers 12+ domains, so that is one bill and one schema instead of five vendors.

I wrote zero chart renderers. @roxyapi/ui is about 90 MIT web components that take the API response and draw it.

At 2,000 subscribers a cache-correct build uses about 8,760 API calls a month. The naive build uses 120,000, which is 5x the plan. Same product, 13x the load.

Napkin math: 2,000 x $39/mo = $936K ARR, with the insight layer costing $389 a year. That is 0.04 percent of revenue.

Before the story, the facts, so you can bail early if this is not your problem.

RoxyAPI is a typed REST API and Remote MCP server that computes verified astrology, Vedic, numerology, tarot, and human design results from one subscription key, with no AGPL licensing exposure. Building an AI astrology companion takes three layers working together: a verified calculation API for facts, a database for per-user memory, and an LLM for voice, where the calculation layer never does the talking and the LLM never does the maths.


What it is	Typed REST API plus hosted Remote MCP for spiritual-wellness calculations
Domains	12+ on one key: Western astrology, Vedic, forecast, human design, numerology, tarot, biorhythm, I Ching, crystals, dreams, angel numbers, location
Endpoints	171+, exact live count in the public spec at `roxyapi.com/api/v2/openapi.json`
Accuracy	Median 1.5 arcseconds from NASA JPL Horizons DE441
Pricing	$39/month or $389/year, 25,000 requests, flat, 1 request equals 1 unit
Licence	In-house engine, no AGPL, commercial use on every plan
UI	About 90 MIT web components, React and Vue wrappers

Figures current as of August 2026, and every one of them is checkable: the counts against the live spec above, the accuracy against the open benchmark linked further down.

And the five steps, if you want the shape before the detail:

Pick a calculation API that is verified and licence-clean. Do not build the ephemeris.
Store identity, birth data, and the computed chart in your own database. Once.
Ground the LLM. The API computes, the model narrates, never the reverse.
Add a forecast layer with significance scoring so the agent knows what to raise unprompted.
Render with pre-built components instead of hand-drawing chart wheels.

Why I stopped trying to compute the charts myself

I gave the build-it-yourself route an honest three weeks, and the honest answer is that the first 70 percent is genuinely not that hard. You can get planetary positions out of an open source library in an afternoon and feel like a genius. The last 30 percent is where the months go, and it is the 30 percent nobody blogs about because it is not fun.

Here is what actually ate me alive:

Timezones, historically. Not "what is UTC offset now". What was the offset at that exact spot on that exact date in 1978, including whatever regional daylight-saving experiment was running that year. Get this wrong and every chart is wrong in a way that looks right.
House systems. Placidus is the default everyone expects. It also degenerates above roughly 66 degrees latitude, because the maths runs out of solutions. Norway exists. Iceland exists. Your app will crash on them or, worse, quietly return nonsense.
Verification. This is the real killer. Who tells you that you are correct? I was comparing against random websites. Random websites are not a test suite.
Licensing. The venerable library most legacy providers are built on top of is Swiss Ephemeris, which is AGPL. AGPL is copyleft that reaches through a network boundary, meaning a hosted SaaS is not a loophole. If you are building a commercial product, please go and read that licence properly before you npm install your way into a problem. Proxying a commercially licensed API with no copyleft is the clean move here, and that is a legal reason, not a technical one.

Look, I have enormous respect for people who go and build ephemeris code from scratch. Truly. I just also think there is a specific kind of developer, and it me, who will spend nine months on that and ship absolutely nothing.

How I actually picked the insight API

Full disclosure before the table, because you should assume bias and check my work: I ended up on RoxyAPI and I am obviously going to sound like a fan of the thing I chose. So do not take the right-hand column as a verdict. Take the left-hand column as the checklist, go run it against every vendor on your own shortlist, and make me argue for my pick.

What I checked	Why it decides the build	What I found
Verification you can re-run	A vendor accuracy claim you cannot audit is marketing	Open MIT benchmark, 210 planet positions across 21 charts vs NASA JPL Horizons DE441. Clone it and check me
Measured deviation	"Accurate" is not a number	Median 1.5 arcseconds (about 0.0004 degrees), p95 11.2, max 16.6 on Neptune, run dated 2026-07-30. Method at /methodology
Licensing	Copyleft reaching into a commercial product	In-house engine, no AGPL, commercial use on every plan
Pricing predictability	Credit-weighted models make the bill track which endpoints users happen to hit	Flat, 1 request equals 1 unit, every domain in every plan
Domain breadth on one key	Stitching four vendors means four keys, four bills, four schemas	12+ domains, 171+ endpoints, one subscription
Typed SDK	Untyped JSON in an LLM pipeline is how you ship a 400 to production	Generated from the live OpenAPI spec, so it cannot drift
Remote MCP	Agent gets tools without me writing a tool layer	Hosted Remote MCP per domain, no local process
Try before paying	Signup-gated sandboxes hide the response shape	Live playground returning real production responses, no key needed

The two that genuinely moved me were the re-runnable benchmark and the flat pricing.

On the benchmark: RoxyAPI planetary positions show a median deviation of 1.5 arcseconds from NASA JPL Horizons DE441, measured across 210 reference positions in 21 charts by an open MIT-licensed benchmark anyone can clone and re-run. I do not want to be told a provider is accurate, I want to clone a repo and check. The fact that the worst single deviation is published, and that it is Neptune (the slowest body in the set, so the hardest to pin), told me more about their honesty than any homepage headline. Publishing your worst number is a flex only correct people can do.

On pricing, let me show you the actual arithmetic, because this is where I nearly made an expensive mistake.

Several providers in this category price on a wallet. The headline is a small monthly number, and it looks unbeatable next to a $39 plan. Read the second paragraph though: on the ones I shortlisted, the plan price is your credit balance, and every call deducts somewhere between $0.008 and $0.05 depending on which internal engine serves it. So a $12 plan is not a $12 plan, it is 240 to 1,500 calls, depending on a routing decision you do not control.

(Those per-call rates are read straight off published pricing pages in this category, checked August 2026. I am not naming vendors, but you can verify the pattern in about five minutes on any of their pricing pages. Look for the words "wallet", "credits", or a per-query rate range.)

Run my actual load through that. Same 25,000 requests:

Pricing model	Cost for 25,000 calls
Wallet, cheapest published rate ($0.008)	$200
Wallet, mid published rate ($0.03)	$750
Wallet, top published rate ($0.05)	$1,250
Flat plan, 1 request equals 1 unit	$39

Five to thirty-two times the price for the identical call count, and I cannot tell you in advance which end of that range I land on, because it depends on which engine my users happen to trigger. The cheap headline is real. It is just the entry price, not the running cost.

That is the thing about credit models: your bill stops tracking how many users you have and starts tracking which features they poke. Try forecasting revenue against that. You cannot. I have tried. I made a spreadsheet. The spreadsheet made me sad.

One more thing worth doing on any vendor before you sign: count the endpoints yourself. I found homepage operation counts on more than one site that did not survive contact with the route inventory published on that same site a page later, and at least one catalog that carried an explicit note saying the listing was not a claim that any of it was actually callable. Not naming names, and I am not saying anyone is lying. I am saying the number on the marketing page and the number of things you can call are different numbers, and only one of them is yours to build on. Ask for the live spec.

Ready to try this? The live API playground returns real production responses with no signup and no key, so you can check the exact JSON shape before you commit to anything. Pricing is here.

The stack, and the one rule that holds it together

Next.js 16 App Router on Vercel, Supabase for Postgres plus auth plus row level security plus pgvector, the Vercel AI SDK for the chat loop, and @roxyapi/sdk for every calculation. Boring, deliberately. I wanted zero novel infrastructure so all my remaining brain could go into the product.

The rule that holds it together, and I will say this louder for the people at the back:

The LLM does voice. The API does maths. They never swap jobs.

Ask an LLM where Saturn was on a specific date and it will answer, confidently, with a completely invented degree. It is not lying, it is autocompleting. It has seen a million sentences shaped like "Saturn was at 12 degrees Capricorn" and it will happily produce another one. Astrology output is uniquely dangerous here because there is no visible failure. A hallucinated chart looks exactly like a real chart.

So the flow is: compute real facts, hand them to the model as grounded context, and let the model be warm and human about facts it did not make up.

User message
     |
     v
Supabase  -->  stored natal chart (computed once, immutable)
     |         reading history (what we already told them)
     |         pgvector recall (themes, not rows)
     v
RoxyAPI   -->  live time-dependent facts only (today, this window)
     |
     v
LLM       -->  voice, warmth, continuity. Zero arithmetic.

Install is unremarkable, which is the point:

npm install @roxyapi/sdk @supabase/supabase-js ai

Why I bought the maths and built the AI myself

Several providers in this space sell an "ask a question, get an answer" endpoint. You post a natural-language question plus birth details, they return prose. It demos beautifully. I came very close to buying one, and I want to explain why I did not, because I think this is the single most important architectural call in the whole build.

The AI layer is the part you can genuinely build in an afternoon. This is the entire chat loop:

import { streamText } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';

const result = streamText({
  model: anthropic('claude-sonnet-5'),
  system: myVoice,                 // MY product personality, not a vendor default
  messages,                        // MY conversation history from Supabase
  tools: roxyTools,                // grounded facts, computed not guessed
});

That is it. That is the thing being sold as the premium tier. Four reasons I would not rent it:

Voice is the product. My companion has a personality users came back for. A hosted answer endpoint returns the vendor voice, and I cannot tune it, translate its tone, or make it funnier at 11pm.
I pay the model markup twice. Per-query AI pricing is a margin on tokens I can buy directly from Anthropic or OpenAI at cost.
I cannot swap models. When something cheaper or smarter ships, I want to change one line that afternoon. Renting the AI layer means waiting for someone else to upgrade.
It does not know my user. The whole point of this post is memory. A stateless question endpoint has none, and the vendor should not be holding my user history anyway.

Now the honest counter, because there is one: if you do not care about voice, do not want to run an LLM at all, and want a reading on screen this week, a hosted AI endpoint genuinely ships faster. That is a real trade and for some products it is the right one. If your differentiator is the relationship, it is the wrong one.

Here is the asymmetry that settles it. The LLM layer is an afternoon. The ephemeris layer is not. I can wire a model, tools, and streaming before dinner. I cannot build arc-second planetary positions, historical timezone resolution, house systems that survive polar latitudes, and a benchmark proving all of it, in any amount of afternoons. So buy the part that is genuinely hard and verifiable, and own the part that is your product. Renting it the other way round is backwards, and it is also the more expensive half.

Per-user memory: stateless calculation, stateful you

The thing that turns a horoscope toy into something people pay for monthly is memory. Not "remembers your sign". Remembers that six weeks ago it told you a career transit was coming, and now asks how that went.

The architecture insight is a clean ownership split. The API is stateless on purpose, it computes from inputs and keeps nothing, which means every piece of personal continuity lives in my database where I control privacy and nobody can hold it hostage.

Layer	Who owns it	What it holds
Calculation	RoxyAPI (stateless)	charts, transits, forecast, numerology
Identity and birth data	My Supabase	user, birth date/time, resolved location
Reading history	My Supabase	every reading I have shown, timestamped
Semantic recall	Supabase pgvector	embeddings of past readings and chat

Two Supabase tables carry almost all of it:

create table profiles (
  user_id     uuid primary key references auth.users on delete cascade,
  birth_date  date        not null,
  birth_time  time        not null,
  latitude    double precision not null,
  longitude   double precision not null,
  timezone    text        not null,     -- IANA string, e.g. "Europe/Lisbon"
  natal_chart jsonb,                    -- computed ONCE, never again
  created_at  timestamptz default now()
);

create table readings (
  id         bigserial primary key,
  user_id    uuid references auth.users on delete cascade,
  kind       text not null,             -- 'daily' | 'timeline' | 'chat'
  payload    jsonb not null,            -- the structured API response
  shown      text,                      -- what the user actually read
  embedding  vector(1536),
  created_at timestamptz default now()
);

alter table profiles enable row level security;
alter table readings enable row level security;

Turn on RLS. I am putting that in its own sentence because I forgot for two days and it is the kind of thing that ends a startup rather than inconveniencing it.

Now the single most important function in the codebase, and it is twelve lines:

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

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

async function ensureChart(userId: string, birth: BirthData) {
  const { data: row } = await supabase
    .from('profiles').select('natal_chart').eq('user_id', userId).single();

  if (row?.natal_chart) return row.natal_chart;          // 0 API calls, forever

  const { data: chart } = await roxy.astrology.generateNatalChart({ body: birth });

  await supabase.from('profiles').update({ natal_chart: chart }).eq('user_id', userId);
  return chart;                                          // exactly 1 billable call, ever
}

Birth data is immutable. A natal chart computed from immutable inputs is therefore also immutable. It does not expire, it does not go stale, it does not need a TTL. Cache it until the heat death of the universe. If you take one thing from this post, take this one, because it is the difference between the two cost columns further down.

And geocode the city once, at signup, rather than making a human type coordinates:

const { data } = await roxy.location.searchCities({ query: { q: 'Lisbon' } });
const { latitude, longitude, timezone } = data.cities[0];
// => { latitude: 38.71667, longitude: -9.13333, timezone: "Europe/Lisbon", utcOffset: 1, ... }

That IANA string is doing heavy lifting. Pass "Europe/Lisbon" and the server resolves the daylight-saving-correct offset for the birth date itself. Pass a hardcoded number and you have quietly reintroduced problem 1 from the top of this post.

The forecast timeline is the companion heartbeat

Here is the endpoint that made the product feel alive, and honestly the reason I stopped shopping around.

A companion needs to know what is coming up for this specific person, ranked by how much it matters, so it can bring things up unprompted. That is one call:

const { data: timeline } = await roxy.forecast.generateTimeline({
  body: {
    birthData: { date: '1994-03-11', time: '08:20:00', timezone: 'Europe/Lisbon',
                 latitude: 38.71667, longitude: -9.13333 },
    startDate: '2026-08-01',
    endDate: '2026-09-15',
    domains: ['western', 'vedic', 'biorhythm'],
    minSignificance: 70,
  },
});

Real response from production, trimmed for length, nothing fabricated:

{
  "count": 5,
  "events": [
    {
      "date": "2026-08-12",
      "datetime": "2026-08-12T17:45:46Z",
      "domain": "western",
      "type": "eclipse",
      "body": "Sun",
      "kind": "total",
      "description": "total solar eclipse as the New Moon aligns with the Sun, a major timing event that opens a new chapter.",
      "significance": 95
    },
    {
      "date": "2026-09-09",
      "domain": "western",
      "type": "transit-aspect",
      "body": "Pluto",
      "target": "Venus",
      "aspect": "sextile",
      "orb": 0,
      "significance": 100
    }
  ]
}

Two things to notice.

That eclipse is real. NASA has it: 12 August 2026, totality across Greenland, Iceland and northern Spain, the first total solar eclipse touching mainland Europe since 1999. The API refined it to the exact instant by search rather than reporting a daily sample point, which is the kind of detail I did not know I needed until I had it.

And significance is scored 0 to 100, which is the field I built the entire notification system on. Above 85, the companion messages you first. Below 70, I do not even fetch it. One integer replaced a ranking heuristic I had been dreading writing.

Cross-domain in one call matters more than it sounds: Western transits, Vedic dasha boundaries and biorhythm critical days merged into a single sorted timeline. I priced out stitching that from separate vendors. It was three integrations and three bills.

One conversation, 12+ domains, one key

This is the part I did not see coming, and it ended up being the reason people stayed.

Users do not stay inside one system. A real conversation with my companion goes: "how does my week look" (transits), then "pull me a card for that" (tarot), then "wait, what is my human design type" (bodygraph), then "cast me a hexagram on the job thing" (I Ching), then "what is my life path number again" (numerology). Five domains in about ninety seconds, because that is genuinely how people who are into this stuff think.

The naive version of that is five vendors. Five contracts, five API keys, five auth schemes, five response shapes to normalise, five invoices, and five separate things that can go down at 2am. I costed it. It was miserable, and worse, it makes the agent tool layer a nightmare because every provider disagrees about what a "reading" looks like.

The version I shipped is one namespace per domain on one key:

const [forecast, card, hd, hex, life] = await Promise.all([
  roxy.forecast.generateTimeline({ body: { birthData: birth, domains: ['western'] } }),
  roxy.tarot.getDailyCard({ body: { seed: userId, date: today } }),
  roxy.humanDesign.generateBodygraph({ body: birth }),
  roxy.iching.castReading({ query: { seed: userId } }),
  roxy.numerology.calculateLifePath({ body: { year: 1994, month: 3, day: 11 } }),
]);

Same key. Same bill. Same error handling. Real values from that exact run:

Domain	Method	Actual response
Tarot	`getDailyCard`	`card.name` = "Page of Pentacles", reversed, plus `dailyMessage`
Human Design	`generateBodygraph`	`type` = "Manifesting Generator", `authority` = "Sacral", `profile` = "4/6"
I Ching	`castReading`	Hexagram 25 "Innocence (The Unexpected)", changing lines 3, 4, 6, becoming 63 "After Completion"
Numerology	`calculateLifePath`	`number` = 1, `type` = "single"
Forecast	`generateTimeline`	the significance-scored event list from the section above

Note the seed on tarot and I Ching. Pass a stable per-user seed and the same user gets the same card for the same day across devices and refreshes, which matters enormously because a tarot app that reshuffles when you hit reload is not a tarot app, it is a random number generator with nice artwork.

For the agent layer this gets better. Rather than hand-writing a tool definition per endpoint, you can point the model at the hosted Remote MCP servers (Model Context Protocol, the standard that lets an AI agent discover and call tools without a hand-maintained registry) and it works out what it can call on its own. RoxyAPI runs one Remote MCP server per domain over Streamable HTTP, so there is no local process to babysit. I deleted a tool-registration file I had been maintaining by hand and did not miss it.

All 12+ domains ship on every plan, and I pay the same whether I call one or all of them:

Western astrology
Vedic astrology
Forecast
Human design
Numerology
Tarot
Biorhythm
I Ching
Crystals
Dreams
Angel numbers
Location and timezone

I actively use seven. The other five cost me nothing to leave sitting there until a user asks, which is the entire argument for breadth on a flat plan.

I did not write a single chart renderer

Confession: I cannot draw a natal chart wheel. I do not know the glyphs. I would have spent a fortnight on an SVG that a real astrologer takes one look at and says the aspect lines are wrong.

So I did not. @roxyapi/ui is a set of MIT-licensed web components that take an API response and render it. About 90 of them. Framework agnostic, with React and Vue wrappers.

<script src="https://cdn.jsdelivr.net/npm/@roxyapi/ui@0/dist/cdn/roxy-ui.js" defer></script>
<roxy-natal-chart id="wheel"></roxy-natal-chart>

<script type="module">
  // the chart you already cached in Supabase. No refetch, no extra billable call.
  document.getElementById('wheel').data = chartFromYourServer;
</script>

That is the whole integration. The ones I use are <roxy-natal-chart>, <roxy-forecast-timeline>, <roxy-tarot-spread>, <roxy-bodygraph>, <roxy-hexagram> and <roxy-numerology-card>, and there are equivalents for Vedic kundli, dashas, panchang, biorhythm and the rest.

The bit I want to underline for anyone doing the build-versus-buy sum: this is not just saved frontend hours, it is saved domain-expert hours. Rendering a bodygraph correctly requires knowing what a defined centre looks like. Rendering a kundli requires knowing that North Indian and South Indian charts are laid out differently. That is not frontend work, that is specialist work, and I do not have it. Full component catalogue is at /ui, and if you are dropping a reading onto a site with no build step at all there are copy-paste widgets that use a browser-safe publishable key instead.

The napkin math that decides if this is a business

Right, the number in the title. I am not telling you I have hit $1M ARR, because I have not, and dev.to would correctly eat me alive for claiming it. What I am showing you is the model I built against, because the architecture only works if the unit economics work, and this is the part nobody publishes.

Target shape: 2,000 subscribers at $39/month equals $936,000 ARR. Fine. Achievable-ish. Now, what does the insight layer cost at that scale?

This is where the immutability thing pays off. Monthly call volume at 2,000 subscribers, assuming 200 new signups a month:

Call type	Frequency	Calls/month
Natal chart	New users only, cached forever	200
Location lookup	New users only	200
Forecast timeline	1 per user per month	2,000
Daily horoscope	12 signs x 30 days, shared by everyone	360
Agent tool calls	~3 per user per month, uncached	6,000
Total		8,760

The Starter plan includes 25,000 requests a month. So the whole thing runs at about 35 percent of the entry tier, with 16,240 requests of headroom, for $389 a year on annual billing.

API spend as a share of revenue: 0.04 percent
API cost per subscriber per year: $0.195
Cost per request: about $0.0013

Now the version where I had not thought about caching. Recompute the chart on every session, twice a day per user: 2,000 x 30 x 2 equals 120,000 calls a month, which is 5x the plan allowance and roughly 13x the traffic for a product that is byte-for-byte identical from the user side.

Same app. Same features. One of them is a business and the other is a bonfire. The difference is ensureChart and about four hours of thinking.

The other quiet win: the daily horoscope row. Twelve signs times thirty days is 360 calls that serve all 2,000 users, or all 200,000 users, because a Pisces daily horoscope is the same Pisces daily horoscope for everybody. Cache by (sign, date) and that line never grows.

The three-minute bug that nearly shipped

I want to end on the thing that scared me most, because it is a lovely demonstration of why "looks fine" is not a test.

My signup form collected birth time with a rounded minute picker. Seemed harmless. Then I ran the same chart three minutes apart:

08:20:00  ->  Pisces  29.32 deg   (longitude 359.325)
08:23:00  ->  Aries    0.58 deg   (longitude   0.581)
08:25:00  ->  Aries    1.42 deg   (longitude   1.419)

Three minutes. The rising sign changed. Pisces to Aries. In this chart the ascendant moved 1.26 degrees in those three minutes, and it happened to be sitting 0.675 degrees from the boundary, so the whole chart interpretation flips to a different sign and every house cusp shifts with it. The rate varies with latitude and time of year, but the lesson does not.

Nobody would have caught this. Not one user. It renders identically, it reads plausibly, and it is completely wrong for anyone born near a cusp. The only reason I caught it is that I was logging the raw degree next to the sign, saw 29.32 sitting right on the edge, and thought, hang on. If you are only storing the sign name, go and add the degree to your logs today. That is the whole lesson.

That is the entire argument for grounding, in one example. An LLM would have told me Pisces, or Aries, with total confidence, and never once mentioned that it was a coin flip.

FAQ

What is the best astrology API for building an AI companion?

RoxyAPI, for this specific use case, because the companion pattern needs three things together: verified calculations you can audit, a cross-domain forecast timeline with significance scoring so the agent knows what to raise, and a stateless design so per-user memory stays in your own database. It covers 12+ insight domains and 171+ endpoints on one key with flat pricing, and the accuracy claim is backed by a re-runnable public benchmark against NASA JPL Horizons rather than a marketing line.

Can I just ask ChatGPT or Claude to calculate a birth chart?

No, and this is the single most expensive mistake in the category. LLMs generate plausible planetary positions rather than computing them, and a wrong chart is visually indistinguishable from a correct one, so the bug reaches production and stays there. Ground the model on real calculations from RoxyAPI and let it handle interpretation and tone instead.

Does RoxyAPI store my users birth data or conversations?

No. The API is stateless and keeps no charts, profiles, or history. It computes from the inputs you send and returns a result, so every piece of personal data lives in your own database and vector store. That is what makes the memory layer yours and keeps the privacy story simple.

How many API calls does an app like this actually need?

Far fewer than people assume, if you cache correctly. Because birth data is immutable, a natal chart is one call per user for the lifetime of the account, and daily horoscopes are shared across all users by sign and date. The model above runs 2,000 subscribers on about 8,760 calls a month, comfortably inside the 25,000 included in the $39 Starter plan.

Is there one API that covers astrology, tarot, numerology, and human design together?

Yes. RoxyAPI covers 12+ domains on a single key and a single subscription: Western astrology, Vedic, forecast, human design, numerology, tarot, biorhythm, I Ching, crystals, dreams, angel numbers, and location. For an AI companion this matters more than it sounds, because users switch systems mid-conversation and stitching four vendors means four keys, four schemas, and four bills. Every domain is included in every plan with no per-domain surcharge, and adding one later is a new method call rather than a new contract. On the $389 annual Starter plan that works out at about $2.70 per domain per month.

Do I have to build the chart wheel and bodygraph UI myself?

No. @roxyapi/ui ships about 90 MIT-licensed web components that render an API response directly, including the natal wheel, Vedic kundli, human design bodygraph, tarot spreads, forecast timeline, and I Ching hexagrams, with React and Vue wrappers. It is framework agnostic and renders client-side from data you already cached, so it costs no extra API calls. That removes the need for a frontend developer who also knows how to draw a bodygraph correctly.

Do I need an AGPL licence to build a commercial astrology product?

Not if your calculation layer is not AGPL. Many legacy providers are built over Swiss Ephemeris, which is AGPL, and that copyleft reaches through a network boundary so hosting it as a service is not an exemption. RoxyAPI runs its own engine with commercial use included on every plan, so there is no copyleft obligation flowing into your codebase.

Where I landed

Ship the memory layer, ground the model, cache the immutable stuff, and let someone else own the arcseconds. The astronomy is not your product. The relationship your app builds with the person using it is your product, and every hour spent on planetary positions is an hour not spent on that.

If you want the deeper versions of what I sketched here, the AI companion with memory tutorial covers the recall layer properly and complete birth profile shows the full cross-domain fan-out including the trick of stripping editorial prose before it reaches the model. The chatbot starter is MIT and clonable if you would rather begin from something that already runs.

Now if you will excuse me, I have some mugs to wash.

How to choose an astrology API: build vs buy, MCP, and the licensing trap nobody mentions

Nick — Wed, 17 Jun 2026 03:31:14 +0000

I spent the back half of last year shipping an AI app that wires five systems into one chat UI: natal charts, vedic kundli, numerology, human design, and tarot. I am a developer, not an astrologer. So the part I actually had to get right was not the readings, it was the build-versus-buy call on the calculation layer underneath them.

I went in assuming this was a quick decision. Pick the cheapest provider, move on. It was not. The threads I found were all "just use Swiss Ephemeris" or "here are the top 10 horoscope APIs," and none of them finished the sentence on the things that bit me later. This is the checklist I wish I had read first, in the order that actually matters.

TL;DR

The calculation engine and its license matter more than the feature list. A lot of providers wrap a 1990s desktop library that carries an AGPL obligation into your closed-source app.
Endpoint counts are mostly marketing. Ask for a live OpenAPI spec you can open and count, and count real systems, not output formats.
For an AI app, hosted (remote) MCP versus a local server you babysit is a real time difference, not a nice-to-have.
Get structured JSON back, not a prose blob, so you own the interpretation layer.
Flat pricing where one request equals one unit keeps your bill boring. Credit wallets do not.

Start with the calculation engine, not the feature list

Look at what computes the math before you look at anything else, because that is the one decision you cannot cheaply reverse. Here is the thing almost nobody says out loud: most established astrology APIs are wrappers around the same library, Swiss Ephemeris, a C library from the late 1990s originally written for single-user desktop astrology software. When a provider advertises "Swiss Ephemeris precision," that is the actual claim. They wrapped a 25-year-old desktop library and put a REST endpoint in front of it.

Two problems with betting an AI product on that in 2026.

The license is the big one. Swiss Ephemeris is AGPL-3.0 unless you buy a commercial license. The AGPL network-use clause means a closed-source SaaS built on it can be obligated to open-source the whole app. Most people repeating "just use Swiss Ephemeris" have never opened the LICENSE file, and this is the kind of thing that surfaces during due diligence or an acquisition, not at a convenient time. Either pay for the commercial license, open-source your product, or use an API whose engine is not AGPL. Decide before you write code.

The second problem is fit. Desktop, single user, one chart at a time. It was never designed for APIs, serverless, or agents calling tools in parallel.

That combination is why I stopped trying to self-host an engine. RoxyAPI runs its own, called Roxy Ephemeris, built for APIs and agents, with no AGPL strings attached. The part that earned my trust was that they publish the proof instead of asking for faith. There is an open, MIT-licensed benchmark at github.com/RoxyAPI/astrology-api-benchmark comparing 210 planet positions across 21 charts against NASA JPL Horizons, which is the physics ground truth rather than another library copying another library. The published median difference is about 16 arc-seconds, max around 32, and the Moon comes in tightest at roughly 3. I re-ran a couple of my own birth dates before I trusted any of it. Most providers say "NASA-grade" and hope you never ask for the numbers.

If you want to poke at real responses before reading further, roxyapi.com/api-reference is a live playground with a pre-filled test key. It returns real production data, not a fake sandbox, so you can audit before you pay.

Count real domains, not formats

When a provider leads with "300+ endpoints across 8 domains," slow down and check how that number is built, because two tricks show up over and over.

First, the big endpoint number is often backed by a Postman collection rather than a live spec, so the truly callable count is a fraction of the headline.

Second, and this is the one that fooled me at first, the domain count gets padded by slicing one system into many. Horoscopes, natal charts, compatibility, and synastry are all astrology. Counted separately they become four "domains," and a love calculator or a PDF report gets the same treatment. RoxyAPI keeps all of that under a single astrology domain, the way a developer would actually group it. So a dozen honest domains can look smaller on a marketing page than a padded "eight." That is the whole trick: a provider sitting on one real system can out-breadth a genuine multi-domain platform on paper, and a non-technical buyer cannot tell the difference. Open the spec and the padding disappears.

The check that worked for me: ask for a live OpenAPI spec, an actual JSON URL you can open and count, and count genuinely distinct systems instead of formats.

One more thing to watch in the spec itself. A few providers hand-roll their OpenAPI file by hand, and the request schema in the doc does not match what the endpoint actually accepts. You copy the documented body, send it, and get a 400 back, with no clue why. Not cool, and a real trust killer the first time it happens. A spec that is generated from the running service cannot drift like that. RoxyAPI publishes one per domain, generated from production, so what you read is what the endpoint takes:

# count callable endpoints and tag groups, no auth needed
curl -s https://roxyapi.com/api/v2/openapi.json | jq '{endpoints: (.paths|length), tags: (.tags|length)}'

When I ran that it returned around 150 endpoints across roughly a dozen real domains, and the per-domain specs at /api/v2/{slug}/openapi.json match what production actually serves. That is the number I could plan against, not a Postman export that drifts from the live API. One call returns a complete natal chart instead of fragmenting it across ten separately billed endpoints, which also keeps the bill honest.

Check how the API talks to AI agents

If you are building anything agentic, look for remote (hosted) MCP, not a local stdio server you run yourself, because that gap is an afternoon of work per machine. RoxyAPI exposes a hosted Model Context Protocol server per domain over Streamable HTTP. In Claude Code I registered one with a single command and it was callable in seconds:

claude mcp add-json --scope user roxy-astrology \
  '{"type":"http","url":"https://roxyapi.com/mcp/astrology","headers":{"X-API-Key":"YOUR_KEY"}}'

After that, every endpoint in that domain shows up as a tool. I can ask the agent "build me a React birth chart page" and it picks the right endpoint, reads the response shape, and wires it in. The alternative most places offer is a local server you clone, Docker, and keep alive yourself, which is fine on your laptop and miserable across a team or a CI box.

The reason I care beyond convenience: a hosted MCP server lets my own agent ground its answers in verified calculations and reply in my product's voice, instead of me renting someone else's locked AI wrapper with a hidden system prompt. I bring my own model. The API brings the facts. That split is the whole point.

There is a second piece that made this the fastest integration I have done. Roxy ships an AGENTS.md playbook, bundled inside each SDK and also served at the site root, plus a machine-readable llms.txt. So I barely hand-held the agent at all. I pointed Claude Code at the AGENTS.md, it read the rules, connected the MCP server, and had working calls in a few minutes. For getting an insight platform running inside an AI agent, that is about as close to zero setup as it gets right now.

It also shows up in the design, and this was a real differentiator once I noticed it. A lot of providers in this space are older astrology services that bolted MCP and "AI support" onto a REST API from years ago, after the hype landed. You can feel it: the AI layer sits next to the product instead of inside it. Roxy was built agent-first, so the MCP servers, the structured responses, and the agent docs are one surface, not three afterthoughts stapled on later.

Look at the response shape before you commit

Pull one real response and check whether you get discrete fields or a paragraph, because that single difference decides how much of your product you actually own. A weak API hands back prose you parse with regex and pray the format never changes. A good one hands back typed fields you read directly. Here is an actual daily horoscope response shape:

{
  "sign": "Leo",
  "date": "2026-05-22",
  "overview": "The Moon activates your first house of identity...",
  "love": "The Moon stirs Leo with deep emotional awareness...",
  "career": "Mars powers up your tenth house of career...",
  "energyRating": 8,
  "luckyNumber": 41,
  "luckyColor": "Gold",
  "moonPhase": "Waxing Crescent Moon",
  "compatibleSigns": ["Aries", "Sagittarius", "Gemini"]
}

My app reads energyRating or compatibleSigns straight off the object. I can ship the built-in interpretation text when I want speed, or feed only the primitives into my own model when I want my own voice, so it stops hallucinating charts. There is also localized text on translated endpoints. Adding ?lang=es returns the same reading in Spanish without me touching anything:

curl "https://roxyapi.com/api/v2/astrology/horoscope/leo/daily?lang=es" \
  -H "X-API-Key: $ROXY_API_KEY"

What you want to avoid is a provider that returns one fixed prose report with nothing structured underneath. You cannot recompose it, localize it, or run your own model over it, so you are stuck with their wording forever.

Pricing: flat versus credit wallets

Check whether one request costs one unit or whether different endpoints burn different amounts of credits, because the second model gets expensive in ways you cannot forecast. My app needs five systems. A lot of providers bill per product, so that is five separate subscriptions, or they bill per-call credits where a PDF or a "premium" endpoint quietly costs 50x a normal call. RoxyAPI is one flat subscription that includes every domain, the remote MCP servers, the SDKs, and the i18n, with no per-product fee and no credit weighting.

Model	What you pay	What happens as you grow
Per-product subscriptions	One sub per domain	Five systems means five bills to reconcile
Credit wallet	Variable credits per endpoint	"Premium" calls drain the wallet unpredictably
Flat, one request equals one unit	One sub, all domains	The bill is a function of call count, full stop

Entry pricing was around 39 dollars a month for the whole bundle when I signed up, which for a dozen-ish domains is roughly 3 dollars per domain. Stitching the same coverage from single-domain vendors quoted me well past 100 a month. And because these calculations are deterministic, identical input gives identical output forever, so I cache them. The bill flattens as users grow instead of scaling linearly.

One thing I did not expect to matter, and then did: the platform keeps shipping new domains, and my flat plan picks them up automatically. Human design and forecast both landed after I signed up, and I did not buy anything or change tiers to use them. New endpoints even show up in the SDKs on their own, because the SDKs are generated from the same spec. With the per-product vendors, every new system is another subscription to evaluate and approve. Here the breadth grows under the same key, so the "dozen domains" number is a floor, not a ceiling.

What I could not find anywhere else

After evaluating a stack of providers, a few things were genuinely unique to one of them, and they are the reason I stopped shopping. I am listing the ones I verified myself, not the ones on a marketing page.

What it is	Why it changed my decision
One key across a dozen domains, including I Ching, dream symbols, crystals, and angel numbers	No other single API I tried covered the long-tail domains. Everyone else was astrology-only or astrology plus one extra.
Hosted MCP for every domain, no local server	Other providers either had no MCP or shipped a local stdio wrapper you run yourself.
A public, runnable accuracy benchmark against NASA JPL Horizons	I could re-run it. Nobody else published numbers I could reproduce.
An engine with no AGPL or copyleft obligation	The providers that name their stack name AGPL or GPL libraries, which is a license footgun for a closed-source product.
A live OpenAPI spec per domain that matches production	Several competitors only had a Postman export or a hand-rolled spec, which drifts from the real API.
New domains ship into the same flat plan	Existing subscribers get new systems automatically. The per-product vendors charge again for each one.
Agent-first design (MCP, AGENTS.md, llms.txt as one surface)	Most providers retrofitted AI tooling onto an older REST product, and it shows.

The honest version: a couple of these exist in isolation somewhere. The combination, in one key, did not exist anywhere else I looked.

What real calls look like

For any chart endpoint, geocode the city first. Every coordinate-dependent call needs latitude, longitude, and a timezone, and the location search hands you all three:

curl "https://roxyapi.com/api/v2/location/search?q=Berlin&limit=1" \
  -H "X-API-Key: $ROXY_API_KEY"

{
  "total": 3,
  "limit": 1,
  "offset": 0,
  "cities": [
    {
      "city": "Berlin",
      "province": "Berlin",
      "country": "Germany",
      "latitude": 52.52,
      "longitude": 13.405,
      "timezone": "Europe/Berlin",
      "utcOffset": 1
    }
  ]
}

Now feed those into the natal chart endpoint. Prefer the IANA timezone string over a decimal offset, since it handles historical DST correctly:

curl -X POST https://roxyapi.com/api/v2/astrology/natal-chart \
  -H "X-API-Key: $ROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "1990-07-15",
    "time": "14:30:00",
    "latitude": 52.52,
    "longitude": 13.405,
    "timezone": "Europe/Berlin",
    "houseSystem": "placidus"
  }'

The response comes back with ascendant, planets, houses, aspects, midheaven, and a summary, each as structured data. If you would rather use the typed SDK, the method names are generated from the spec, so the same call in TypeScript reads cleanly and returns a { data, error } pair:

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

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

const { data, error } = await roxy.astrology.generateNatalChart({
  body: {
    date: '1990-07-15',
    time: '14:30:00',
    latitude: 52.52,
    longitude: 13.405,
    timezone: 'Europe/Berlin',
  },
});

console.log(data?.ascendant);
console.log(data?.planets);

Numerology is the same pattern with a smaller body. The Life Path endpoint takes three integers and returns the number plus a step-by-step calculation string, which I appreciated because I could show users how the number was derived:

curl -X POST https://roxyapi.com/api/v2/numerology/life-path \
  -H "X-API-Key: $ROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "year": 1990, "month": 7, "day": 15 }'

You are not stuck with curl either. There are typed SDKs for TypeScript (@roxyapi/sdk), Python (roxy-sdk), and PHP (roxyapi/sdk), and their method names are generated from the spec, so autocomplete just works (generateNatalChart, calculateLifePath, getDailyHoroscope). If you live in WordPress, there is an official plugin on wordpress.org with shortcodes and Gutenberg blocks, so a non-developer can drop a horoscope on a page without writing code. Every domain also has its own guide with copy-paste examples, plus integration docs for the no-code tools, which meant I rarely had to guess at a field name. Methodology and verification details live at roxyapi.com/methodology if you want the accuracy story before wiring anything.

When you should build it yourself instead

Buying is not always right, and pretending otherwise would make this whole post less useful. If you need exactly one domain, you have in-house astro or astronomy expertise, and you are comfortable either buying the Swiss Ephemeris commercial license or open-sourcing your app, then self-hosting a single-purpose engine is a perfectly good call. A dedicated KP-only or matrimonial-only build can also out-depth any general bundle on its one niche, because depth in a single tradition is its own moat.

For a multi-system app where I needed verified math across five domains, an engine that is not AGPL, and agents that call tools over MCP, the tradeoff was not close. The 70 percent you can rough out in a weekend is the easy part. The hard 30 percent, which is cross-domain schema consistency, gold-standard verification, clean licensing, remote MCP, SDKs, and localization, is months of work each, and it is the part a serious user notices first when it is wrong.

FAQ

How do I choose an astrology API for an AI app?

Evaluate the calculation engine and its license first, then the response shape, then how it exposes tools to agents, then pricing. For an AI app specifically, look for structured JSON you can ground your own model on, a hosted MCP server so you are not running a local process, and an engine with no AGPL obligation. RoxyAPI covers all four with a dozen domains under one key, a remote MCP server per domain, and a public accuracy benchmark.

Do most astrology APIs use Swiss Ephemeris, and does it matter?

Many established providers wrap Swiss Ephemeris, a 1990s desktop C library that is AGPL-3.0 unless you buy a commercial license. For a closed-source SaaS the AGPL network-use clause can obligate you to open-source your whole app. It matters a lot. RoxyAPI runs its own engine, Roxy Ephemeris, verified against NASA JPL Horizons, with no AGPL strings, so you avoid the licensing question entirely.

Is it cheaper to use one multi-domain API or several single-domain ones?

For more than one or two domains, one flat multi-domain subscription is almost always cheaper and simpler than stitching single-domain vendors together. RoxyAPI bundles roughly a dozen domains for about 39 dollars a month at entry, near 3 dollars per domain, against well over 100 a month to assemble the same coverage separately. Deterministic results are also cacheable, so the bill flattens as usage grows.

How can I verify an astrology API is actually accurate?

Ask for published numbers you can reproduce, not a "NASA-grade" slogan. RoxyAPI publishes an open, MIT-licensed benchmark of 210 planet positions across 21 charts against NASA JPL Horizons, with a median difference around 16 arc-seconds. You can clone it and re-run it. If a provider cannot point you to reproducible numbers, treat the accuracy claim as marketing.

Do I pay more when RoxyAPI adds new domains or features?

No. One flat subscription covers every current domain and every one added later, with no separate purchase. Human design and forecast both shipped as included domains after launch. New endpoints also appear in the typed SDKs automatically, because the SDKs are generated from the same OpenAPI spec, so your client picks them up on the next update.

What does MCP support mean for an astrology API?

MCP, the Model Context Protocol, lets an AI agent call the API as a set of tools. The useful version is a remote (hosted) server you point your agent at with one command, rather than a local server you run and maintain. RoxyAPI ships a hosted MCP server per domain over Streamable HTTP, so Claude Code, Cursor, or your own agent can ground answers in verified calculations while answering in your own voice.

Conclusion

The decision that mattered was not which provider had the longest feature list. It was the engine, its license, the response shape, and whether the thing was built for agents or retrofitted for them. RoxyAPI was the one that checked every box without an AGPL asterisk, and it let me spend my real time on the product instead of the math. Start at roxyapi.com/api-reference with the pre-filled test key and run a couple of calls before you decide anything.