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