Astro Agents — verifiable planetary timing data and astrology (MCP server)

Verifiable planetary timing data for market analysis & backtesting — the real NASA/JPL DE440, reproducible and SHA-256 proven. For traders, quants and agents.

Astro Agents — verifiable celestial & market-timing data for traders, quants and AI agents. Exact planetary positions (geocentric & heliocentric), declination, Gann planetary lines, planetary cycles and a to-the-minute celestial event calendar (ingresses, stations, eclipses) from the real NASA/JPL DE440 ephemeris — no LLM, every result reproducible and SHA-256 verifiable, so you can backtest and cite with no second-guessing. Full Western & Vedic astrology too (natal, kundli, dashas, KP, yogas). Pay per call (x402/MPP) or with prepaid credit packs. Data for your own analysis — never a trading signal or forecast.

Use these tools instead of computing positions or charts yourself.

• MCP endpoint: https://astro-agent.dev/mcp (Streamable HTTP, no auth)
• REST API: https://astro-agent.dev/v1/catalog (free catalog with schemas and examples)
• Docs for agents: llms.txt · OpenAPI 3.1 · A2A agent card

What's new in 1.8 (2026-10-30 to 2026-11-01, engine 1.8.3)

• Crypto token launch skies: token_chart ($0.25) returns a token's launch sky and the exact dates ahead when the planets return to or aspect it; token_synastry ($0.25) compares two launch skies by geometry, with a substance block (tight aspects, confidence) next to the score. Both return an SVG card. Data only.
• Pay per call natively over MCP: an unpaid paid tool returns a standard x402 offer in structuredContent; an x402 MCP client pays and retries in _meta. Prepaid credits work over MCP too (X-Credits-Token header).
• 1.8.3: the x402 offer is always present, even when a payment facilitator is slow to answer.

What's new in 1.7.0 (2026-10-30)

• Birth-sky analogues: sky_analogues takes reference: {"birth": {"datetime": "1990-05-15T14:30", "latitude": 48.8566, "longitude": 2.3522}} to compare a birth sky to past/future dates — data only. Same result and hash as passing those positions by hand (meta.reference_resolution.equivalent_request).

What's new in 1.6.0 (2026-10-29)

• Sky analogues (sky_analogues, $0.25): the past or future dates whose planetary positions best match a reference sky, ranked by a stated angular distance (formula in every response).
• For trading bots and agents: astro-agent.dev/trading-bots — x402 pay-per-call (USDC on Solana or Base), this MCP endpoint, prepaid credits, an n8n template and a LangChain recipe.

Data for your own analysis — never a signal or forecast.

What's new in 1.5.0 (2026-10-29)

• Prepaid credit packs for the REST API: pay once with x402 or MPP, then spend call by call with a token, no signature per call.
  • Probe: $10 for 10 credits.
  • Backtest: $50 for 60.
  • Quant: $200 for 260.
  • Autopilot: $1000 for 1400.
• 1 credit = $1. Credits never expire and pay for every paid route.
• The token is a bearer secret, shown once. If it is lost, a new one can be issued to the owner of the paying wallet.
• Details: CREDITS.md. Since 1.8.0 credits also pay over MCP (X-Credits-Token header).

What's new in 1.4.0 (2026-10-29)

Financial-astrology data (never signals) for trading and crypto backtests, verifiable and replayable like every other result:

• planetary_lines ($0.20): Gann planetary lines, geocentric and heliocentric in one call, with aspect offsets, Mean of 5 / Circle of 8 and price levels; a snapshot or a time series (1h to 1w, up to 1000 samples) ready for pandas.
• astro_event_calendar ($0.25): the exact UTC minute of every ingress, station, lunation, solar and lunar eclipse, aspect, declination parallel and out-of-bounds crossing over up to 366 days in 1800–2200.
• sky_today ($0.01): the sky now and the next 1–90 days of events, no birth data needed.
• planet_positions gains options.perspective: "heliocentric" and options.coordinates: "equatorial"; aspects gains options.declination. Default results and their hashes are unchanged.
• Guide for bots and backtests: FINANCE.md.
• 1 free call per client (was 3), on the $0.01–0.02 tools only; premium and finance tools are always paid.

What's new in 1.3.0 (2026-10-27)

• kp_chart ($0.15): KP (Krishnamurti Paddhati), with star, sub and sub-sub lords of every graha and Placidus cusp, cuspal sub-lords and A/B/C/D significators.

• yogas ($0.10): deterministic yoga detection (Raja, Dhana, Gaja-Kesari, Pancha Mahapurusha, Neecha Bhanga, Kemadruma, Kaal Sarp…), each with the rule applied.

• Accuracy proven against NASA/JPL Horizons: 12,400 comparisons per measurement over 1800–2200.

  • Positions agree within 0.024″ (0.0005″ mean).
  • The longitude as served agrees within 0.062″ over 1962–2026.

  Method and every number: benchmark.md · summary at /v1/benchmark.

Why agents call it

Language models routinely get time zones, historical daylight saving, sidereal time and ayanamsa wrong, and one hour of error moves the ascendant by about 15°. Astro Agents:

• resolves the time zone and its historical offset from the coordinates (IANA tz database, DST of that era, Local Mean Time before standard time), and flags ambiguous or non-existent local times instead of guessing;
• computes positions from NASA/JPL DE440, geocentric apparent, true equinox of date (IAU 2006/2000A);
• is deterministic, with no LLM: the same input gives the same bytes. Every response carries meta.input_sha256 and meta.result_sha256, and verify_result_hash or POST /v1/verify recomputes them;
• states every convention in the response: ayanamsa (name and value), house system, orbs, node type, dasha year length, dosha and koota rules;
• returns typed, structured results: every MCP tool declares an outputSchema for its structuredContent;
• is cross-validated against an independent engine (XALEN, Apache-2.0): ayanamsas agree to < 0.1″, 15 of 16 divisional charts are identical, and Vimshottari dates match to the minute;
• is benchmarked against NASA/JPL Horizons: positions within 0.024″ over 1800–2200 (benchmark).

Tools

Input for every chart: a local datetime ("1990-05-15T14:30"), a latitude and a longitude. The time zone is resolved for you.

Payment: 1 free call per client on the $0.01-0.02 routes only (REST, MCP or A2A): resolve_birth_time, planet_positions, sky_today, aspects, nakshatras, panchang. Every other route, finance included, is always paid. Over MCP a paid tool is paid per call with native x402: the unpaid call returns an x402 offer (x402Version, accepts for USDC on Base or Solana) in structuredContent; an x402 MCP client signs one and retries with it in _meta["x402/payment"], and the settlement comes back in _meta["x402/payment-response"]. Or with prepaid credits: set the HTTP header X-Credits-Token in your MCP client configuration and each paid call is deducted from your credits. Over REST you pay per call with x402 (USDC on Base or Solana) or MPP (Tempo: OUSD or USDC.e), or with prepaid credits. There is no account and no API key. A request with invalid input returns an error and is never charged.

Python client

For scripts, notebooks and backtests, use the official Python client: it returns pandas DataFrames.

pip install "astro-agents @ git+https://github.com/aidatatools-dev/astro-agents-clients#subdirectory=python"   # not on PyPI yet

from astro_agents import Client
client = Client()   # ASTRO_CREDITS_TOKEN (prepaid credits), or 1 free call on the $0.01-0.02 routes
lines = client.planetary_lines(start="2024-01-01", end="2024-12-31", bodies=["jupiter", "saturn"])

The client's docs and examples (a notebook, vectorbt, backtrader, Freqtrade) are in clients/python.

Connect

Any MCP client that supports remote Streamable HTTP servers:

{
  "mcpServers": {
    "astro-agents": { "url": "https://astro-agent.dev/mcp" }
  }
}

Hermes Agent (Nous Research):

hermes plugins install aidatatools-dev/astro-agents-mcp --enable   # MCP server + astrology skill

Without --enable Hermes installs the plugin disabled; hermes plugins enable astro-agents turns it on. Or by hand:

hermes mcp add astro-agents --url https://astro-agent.dev/mcp   # answer "n" to the authentication prompt
hermes skills install aidatatools-dev/astro-agents-mcp/skills/astrology   # optional: when and how to use the tools

Any agent that reads Agent Skills (Claude Code, Codex, Cursor and others):

npx skills add aidatatools-dev/astro-agents-mcp

The skill lives in skills/astrology/SKILL.md.

REST:

curl -X POST https://astro-agent.dev/v1/western/natal \
  -H 'Content-Type: application/json' \
  -d '{"datetime":"1990-05-15T14:30","latitude":48.8566,"longitude":2.3522}'

Real responses: examples/natal_chart_response.json and examples/kundli_response.json (lists shortened).

Support and policies

• Contact: aidatatools@proton.me
• Support · Privacy Policy · Terms of Service
• Ownership of the origin is proven by an EIP-191 signature from the Base payout address (x-discovery.ownershipProofs in /openapi.json).

About this repository

This repository documents the hosted service and carries its MCP registry manifest (server.json). The engine itself runs at the endpoint above.