Quickstart: 60 seconds

From a key to planetary positions computed from NASA/JPL DE440. Three steps, nothing to install for curl.

1. Get a free key (20 s)

On /pricing, choose Free and enter your email: your key is shown on the next page. Then, in your terminal:

export ASTRO_AGENTS_KEY="paste-your-key-here"      # Windows PowerShell: $env:ASTRO_AGENTS_KEY="..."

No key yet? Run step 2 anyway: each client gets 1 free call on the $0.01-0.02 routes.

2. Make your first call (20 s)

Where are the Sun, the Moon and the planets on 1 October 2026 at 12:00 UTC?

curl

curl -s https://astro-agent.dev/v1/western/positions \
  -H "X-Credits-Token: $ASTRO_AGENTS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"datetime": "2026-10-01T12:00:00Z"}'

Python

import os
import requests

body = {'datetime': '2026-10-01T12:00:00Z'}
r = requests.post("https://astro-agent.dev/v1/western/positions", json=body,
                  headers={"X-Credits-Token": os.environ.get("ASTRO_AGENTS_KEY", "")}, timeout=60)
if not r.ok:
    raise SystemExit(f"{r.status_code}: {r.text}")
data = r.json()

for p in data["result"]["points"]:
    print(f'{p["name"]:<10} {p["longitude"]:9.4f} deg  speed {p["speed_longitude"]:+.4f} deg/day  '
          f'retrograde={p["retrograde"]}')
print("result_sha256:", data["meta"]["result_sha256"])

JavaScript (Node 18+)

// Node 18+ (built-in fetch). Save as call.mjs and run: node call.mjs
const body = {"datetime": "2026-10-01T12:00:00Z"};
const res = await fetch("https://astro-agent.dev/v1/western/positions", {
  method: "POST",
  headers: {"X-Credits-Token": process.env.ASTRO_AGENTS_KEY ?? "", "Content-Type": "application/json"},
  body: JSON.stringify(body),
});
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
const data = await res.json();

for (const p of data.result.points)
  console.log(p.name.padEnd(10), p.longitude.toFixed(4), "deg", p.retrograde ? "retrograde" : "");
console.log("result_sha256:", data.meta.result_sha256);

3. Read the result (20 s)

The Python version prints (Python needs pip install requests):

Sun         188.3302 deg  speed +0.9829 deg/day  retrograde=False
Moon         71.0483 deg  speed +14.2836 deg/day  retrograde=False
Mercury     211.3391 deg  speed +1.3140 deg/day  retrograde=False
...
result_sha256: 269109e17efc86d60897373ac8244ecff90f9c71f9dd1836d848fddba92fcae1

Each line is a body's ecliptic longitude (degrees, 0-360), its daily speed and whether it is retrograde. result_sha256 is the fingerprint of this exact result: the same request returns the same bytes, and POST /v1/verify recomputes it.

Next: a year of events

Every solar and lunar eclipse and every planetary station of 2026, to the minute ($0.25 per call; included in the Free plan's 100 monthly premium calls):

curl

curl -s https://astro-agent.dev/v1/finance/events \
  -H "X-Credits-Token: $ASTRO_AGENTS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"start": "2026-01-01", "end": "2026-12-31", "include": ["eclipse", "station"]}'

Python

import os
import requests

body = {'start': '2026-01-01', 'end': '2026-12-31', 'include': ['eclipse', 'station']}
r = requests.post("https://astro-agent.dev/v1/finance/events", json=body,
                  headers={"X-Credits-Token": os.environ.get("ASTRO_AGENTS_KEY", "")}, timeout=60)
if not r.ok:
    raise SystemExit(f"{r.status_code}: {r.text}")
data = r.json()

for ev in data["result"]["events"]:
    what = ev.get("kind") or ev.get("body") or ev.get("phase") or "-".join(ev.get("bodies", []))
    detail = ev.get("eclipse_type") or ev.get("turns") or ev.get("aspect") or ""
    print(ev["exact_utc"], ev["type"], what, detail)
print("result_sha256:", data["meta"]["result_sha256"])

JavaScript (Node 18+)

// Node 18+ (built-in fetch). Save as call.mjs and run: node call.mjs
const body = {"start": "2026-01-01", "end": "2026-12-31", "include": ["eclipse", "station"]};
const res = await fetch("https://astro-agent.dev/v1/finance/events", {
  method: "POST",
  headers: {"X-Credits-Token": process.env.ASTRO_AGENTS_KEY ?? "", "Content-Type": "application/json"},
  body: JSON.stringify(body),
});
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
const data = await res.json();

for (const ev of data.result.events) {
  const what = ev.kind || ev.body || ev.phase || (ev.bodies || []).join("-");
  console.log(ev.exact_utc, ev.type, what, ev.eclipse_type || ev.turns || ev.aspect || "");
}
console.log("result_sha256:", data.meta.result_sha256);

Where to go next

API reference (every route, parameter and field) · Playground (try any route without code) · Errors · Python SDK: pip install "astro-agents @ git+https://github.com/aidatatools-dev/astro-agents-clients#subdirectory=python" · AI agents: MCP server https://astro-agent.dev/mcp