Astro Agents - research-grade astronomical data API is an MCP server published by io.github.aidatatools-dev, hosted at astro-agent.dev. When last checked on 2026-11-21 it was working: it answers and lists its tools. It declares 20 tools, including rise_set_times, altitude_azimuth, observation_windows, moon_details, day_summary.
Research-grade astronomical data API: NASA/JPL DE440 ephemerides, any date, SHA-256 verifiable.
1,073 connections through 5 shared values. Tap any node.
Squares are this server's values; dots are other servers sharing them. A shared address or publisher is a lead, not proof of a common operator.
Inferred from the host name and headers: what a server runs on, not who runs it.
Sunrise, sunset, moonrise, moonset and twilight times for a place and date: rise, transit and set of the Sun, Moon and planets, civil/nautical/astronomical dawn and dusk, day length, golden hour and blue hour, in UTC and local time. E.g. {date: '2026-06-21', latitude: 48.8566, longitude: 2.3522}. For sky, weather, photography and outdoor apps: for one local calendar day at a place (time zone and DST resolved from the coordinates), each body's rise and set (with azimuth) and upper transit (with altitude), or 'always_up' / 'always_down' when it neither rises nor sets (polar day and night); for the Sun, dawn and dusk at -6, -12 and -18 degrees, solar noon, day length, and the golden hour (Sun between -4 and +6 degrees) and blue hour (-6 to -4) intervals. Times in UTC to the second, local time with its offset, and unix timestamps; every convention (refraction, limb, horizon) is in result.settings. Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.01 per call via REST POST https://astro-agent.dev/v1/astronomy/rise-set (x402 or MPP); each client gets 1 free call on the $0.01-0.02 tools, this one included.
| Parameter | Type | Description |
|---|---|---|
| date * | string | The local calendar day at the place, YYYY-MM-DD (1800-01-02..2199-12-30), midnight to midnight in its time zone. |
| bodies | array | Bodies to time. Default: all ten (Sun, Moon, Mercury..Pluto). The Sun's twilight block is always returned. |
| latitude * | number | Decimal degrees, north positive. |
| timezone | string | IANA zone for local times, e.g. 'Europe/Paris'. Optional: resolved from the coordinates (with its historical DST rules). |
| longitude * | number | Decimal degrees, east positive. |
| elevation_m | number | Height above the WGS84 ellipsoid, metres (no terrain or horizon dip is modelled). |
{
"name": "rise_set_times",
"title": "Rise, set and twilight times for a place",
"description": "Sunrise, sunset, moonrise, moonset and twilight times for a place and date: rise, transit and set of the Sun, Moon and planets, civil/nautical/astronomical dawn and dusk, day length, golden hour and blue hour, in UTC and local time. E.g. {date: '2026-06-21', latitude: 48.8566, longitude: 2.3522}. For sky, weather, photography and outdoor apps: for one local calendar day at a place (time zone and DST resolved from the coordinates), each body's rise and set (with azimuth) and upper transit (with altitude), or 'always_up' / 'always_down' when it neither rises nor sets (polar day and night); for the Sun, dawn and dusk at -6, -12 and -18 degrees, solar noon, day length, and the golden hour (Sun between -4 and +6 degrees) and blue hour (-6 to -4) intervals. Times in UTC to the second, local time with its offset, and unix timestamps; every convention (refraction, limb, horizon) is in result.settings. Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.01 per call via REST POST https://astro-agent.dev/v1/astronomy/rise-set (x402 or MPP); each client gets 1 free call on the $0.01-0.02 tools, this one included.",
"inputSchema": {
"type": "object",
"required": [
"date",
"latitude",
"longitude"
],
"properties": {
"date": {
"type": "string",
"description": "The local calendar day at the place, YYYY-MM-DD (1800-01-02..2199-12-30), midnight to midnight in its time zone."
},
"bodies": {
"type": "array",
"items": {
"enum": [
"sun",
"moon",
"mercury",
"venus",
"mars",
"jupiter",
"saturn",
"uranus",
"neptune",
"pluto"
],
"type": "string"
},
"description": "Bodies to time. Default: all ten (Sun, Moon, Mercury..Pluto). The Sun's twilight block is always returned."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Decimal degrees, north positive."
},
"timezone": {
"type": "string",
"description": "IANA zone for local times, e.g. 'Europe/Paris'. Optional: resolved from the coordinates (with its historical DST rules)."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Decimal degrees, east positive."
},
"elevation_m": {
"type": "number",
"default": 0,
"maximum": 9000,
"minimum": -500,
"description": "Height above the WGS84 ellipsoid, metres (no terrain or horizon dip is modelled)."
}
}
},
"outputSchema": {
"type": "object",
"anyOf": [
{
"required": [
"endpoint",
"result",
"meta"
]
},
{
"required": [
"x402Version",
"accepts"
]
}
],
"properties": {
"meta": {
"type": "object",
"required": [
"engine",
"deterministic",
"llm_used",
"input_sha256",
"result_sha256"
],
"properties": {
"frame": {
"type": "string",
"description": "Reference frame of the positions."
},
"engine": {
"type": "string",
"description": "Engine name and version."
},
"payment": {
"type": "object",
"description": "How this call was paid: protocol ('free' or 'none'), price and the free calls remaining."
},
"llm_used": {
"type": "boolean",
"description": "Always false: no language model is involved."
},
"ephemeris": {
"type": "string",
"description": "Ephemeris used (NASA/JPL DE440)."
},
"compute_ms": {
"type": "number",
"description": "Computation time in milliseconds."
},
"computed_at": {
"type": "string",
"description": "When it was computed (UTC, ISO 8601)."
},
"input_sha256": {
"type": "string",
"description": "SHA-256 of the canonical input."
},
"deterministic": {
"type": "boolean",
"description": "Always true: same input, same result."
},
"result_sha256": {
"type": "string",
"description": "SHA-256 of the canonical 'result'; check it with verify_result_hash."
},
"reproducibility": {
"type": "string",
"description": "How to reproduce and check this result."
},
"astronomy_library": {
"type": "string",
"description": "Astronomy library and version."
}
},
"description": "Provenance of the result."
},
"error": {
"type": "string",
"description": "x402 offer only: why payment is required."
},
"result": {
"type": "object",
"required": [
"subject",
"settings",
"bodies",
"sun"
],
"properties": {
"sun": {
"type": "object",
"description": "sunrise, solar_noon, sunset, civil/nautical/astronomical dawn and dusk (null when the Sun does not reach that depth), day_length_minutes, golden_hour and blue_hour intervals [{period, start, end}]."
},
"bodies": {
"type": "array",
"description": "One row per body: rise and set {utc, local (ISO 8601 with offset), timestamp (unix seconds)} with azimuth, transit with altitude (null when it does not happen that day), and state: rises_and_sets, rises_only, sets_only, always_up or always_down."
},
"subject": {
"type": "object",
"description": "The place (latitude, longitude, elevation_m), its time zone and how it was found, the local date and the day's window in UTC (midnight to midnight local time)."
},
"settings": {
"type": "object",
"description": "The bodies timed and every convention: observer model, rise/set limb and refraction, twilight and golden/blue hour altitudes."
}
},
"description": "The calculation result."
},
"accepts": {
"type": "array",
"items": {
"type": "object"
},
"minItems": 1,
"description": "x402 offer only: the payment options (scheme, network, amount, asset, payTo, ...)."
},
"endpoint": {
"type": "string",
"description": "The REST route that computed it, e.g. 'astronomy/rise-set'."
},
"resource": {
"type": "object",
"description": "x402 offer only: the resource being paid for."
},
"extensions": {
"type": "object",
"description": "x402 offer only: protocol extensions (bazaar)."
},
"x402Version": {
"type": "integer",
"description": "x402 offer only: protocol version (2)."
}
}
},
"annotations": {
"title": "Rise, set and twilight times for a place",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}Where the Sun, Moon and planets are in the sky from a place at a moment: altitude, azimuth, compass point, topocentric right ascension and declination, distance, elongation, illumination, magnitude and the sky state. E.g. {datetime: '2026-06-21T23:00', latitude: 48.8566, longitude: 2.3522}. For sky maps, telescope pointing, AR and observation apps: each body's apparent altitude and azimuth (with refraction, or airless), whether it is above the horizon, its topocentric right ascension and declination, distance (and the Moon's in km), angular distance from the Sun, illuminated fraction and visual magnitude (planets), plus the sky state (day, civil / nautical / astronomical twilight, night). Matches NASA/JPL Horizons to under a second of arc. Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.01 per call via REST POST https://astro-agent.dev/v1/astronomy/altaz (x402 or MPP); each client gets 1 free call on the $0.01-0.02 tools, this one included.
| Parameter | Type | Description |
|---|---|---|
| bodies | array | Bodies to locate. Default: all ten. |
| options | object | Refraction settings. |
| datetime * | string | The moment: UTC ('2026-06-21T21:00:00Z'), with an explicit offset, or local civil time at the place ('2026-06-21T23:00', time zone resolved from the coordinates). |
| latitude * | number | Decimal degrees, north positive. |
| timezone | string | IANA zone for local times, e.g. 'Europe/Paris'. Optional: resolved from the coordinates (with its historical DST rules). |
| longitude |
Which planets and the Moon can be observed tonight from a place, and when: windows above a minimum altitude while the sky is dark, with the best time, altitude, azimuth and magnitude. E.g. {date: '2026-06-21', latitude: 48.8566, longitude: 2.3522}. For observation planning: over the night that starts on 'date' (local noon to noon), the intervals when each body stands at least min_altitude_deg above the horizon while the Sun is at or below sun_altitude_max_deg (default -6: after civil dusk), each with start, end, duration and the best moment (highest altitude) with its azimuth and visual magnitude; plus the dark interval itself. Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.02 per call via REST POST https://astro-agent.dev/v1/astronomy/visibility (x402 or MPP); each client gets 1 free call on the $0.01-0.02 tools, this one included.
| Parameter | Type | Description |
|---|---|---|
| date * | string | The evening that starts the observing night, YYYY-MM-DD: the night runs from local noon on that date to local noon the next day. |
| bodies | array | Bodies to plan. Default: the Moon and Mercury..Neptune. |
| options | object | What counts as observable. |
| latitude * | number | Decimal degrees, north positive. |
| timezone | string | IANA zone for local times, e.g. 'Europe/Paris'. Optional: resolved from the coordinates (with its historical DST rules). |
| longitude * | number | Decimal degrees, east positive. |
Moon phase today and in detail: phase name and angle, illuminated fraction, age, distance, apparent size, the next new, quarter and full Moons, and the next perigee and apogee; with a place, moonrise and moonset. E.g. {datetime: '2026-01-03T12:00:00Z'}. For calendar, weather, photography and tide apps: phase (8 names), phase angle, illuminated fraction, waxing or waning, age in days since the new Moon, Brown lunation number, centre-to-centre distance in km and Earth radii, angular diameter, ecliptic position, the previous new Moon, the next four principal phases and the next perigee and apogee with their distances, to the second. With latitude/longitude: the Moon's altitude and azimuth there and that local day's moonrise, transit and moonset. Perigee and apogee match NASA/JPL Horizons to the minute. Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.01 per call via REST POST https://astro-agent.dev/v1/astronomy/moon (x402 or MPP); each client gets 1 free call on the $0.01-0.02 tools, this one included.
| Parameter | Type | Description |
|---|---|---|
| datetime | string | The moment: UTC, an explicit offset, or local civil time at the place given by latitude/longitude. Default: now (UTC, to the minute). |
| latitude | number | Optional: add the Moon's altitude and azimuth from this place and that local day's moonrise, transit and moonset. |
| timezone | string | IANA zone for local times, e.g. 'Europe/Paris'. Optional: resolved from the coordinates (with its historical DST rules). |
| longitude | number | Optional, with latitude. |
| elevation_m | number | Height above the WGS84 ellipsoid, metres (no terrain or horizon dip is modelled). |
Today's sky for a place in one call: sunrise, sunset, twilight, golden and blue hour, the Moon's phase and moonrise, the planets visible tonight, the next lunations and the next eclipse. E.g. {date: '2026-08-10', latitude: 48.8566, longitude: 2.3522}. The daily sky block of a weather, calendar or outdoor app, in one request: the Sun (rise, solar noon, set, civil / nautical / astronomical dawn and dusk, day length, golden and blue hour), the Moon (phase, illuminated fraction, age, distance, moonrise, transit, moonset, the next principal phase), the planets observable that night (window, best time, altitude, azimuth, magnitude; brightest first), the lunations and planetary stations of the next 7 days, and the next solar or lunar eclipse anywhere on Earth. Local times with offset, UTC and unix timestamps; each block follows the conventions of its own route. Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.02 per call via REST POST https://astro-agent.dev/v1/astronomy/day (x402 or MPP); each client gets 1 free call on the $0.01-0.02 tools, this one included.
| Parameter | Type | Description |
|---|---|---|
| date * | string | The local calendar day at the place, YYYY-MM-DD (1800-01-02..2199-12-30). |
| latitude * | number | Decimal degrees, north positive. |
| timezone | string | IANA zone for local times, e.g. 'Europe/Paris'. Optional: resolved from the coordinates (with its historical DST rules). |
| longitude * | number | Decimal degrees, east positive. |
| elevation_m | number | Height above the WGS84 ellipsoid, metres (no terrain or horizon dip is modelled). |
Equinoxes and solstices of a year, Earth's perihelion and aphelion, and optionally the Sun day by day (sunrise, sunset, day length, declination, equation of time) for a place. E.g. {year: 2026}. For calendars, almanacs, education and solar apps: the March and September equinoxes and the June and December solstices (UTC, and local with a place), Earth's perihelion and aphelion with their distances, and with daily=true a row per day: solar noon, the Sun's apparent declination, the equation of time and, for a place, sunrise, sunset and day length, plus the longest and shortest days. Matches the published 2026 times to the minute. Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.01 per call via REST POST https://astro-agent.dev/v1/astronomy/seasons (x402 or MPP); each client gets 1 free call on the $0.01-0.02 tools, this one included.
| Parameter | Type | Description |
|---|---|---|
| year * | integer | Calendar year. |
| daily | boolean | Add one row per day: solar noon, the Sun's declination, the equation of time and, with a place, sunrise, sunset and day length. |
| latitude | number | Optional: local times, and with daily=true the day-by-day sunrise, sunset and day length at this place. |
| timezone | string | IANA zone for local times, e.g. 'Europe/Paris'. Optional: resolved from the coordinates (with its historical DST rules). |
| longitude | number | Optional, with latitude. |
| elevation_m | number | Height above the WGS84 ellipsoid, metres (no terrain or horizon dip is modelled). |
Julian day, modified Julian day, sidereal time (Greenwich and local, mean and apparent), Delta T, TAI-UTC and UT1-UTC for a moment. E.g. {datetime: '2026-06-21T12:00:00Z', longitude: 2.35, latitude: 48.86}. For telescope control, data reduction and education: the Julian day in UTC, UT1, TT and TDB, the modified Julian day, Julian centuries since J2000 (TT), Delta T (TT - UT1), TAI - UTC and UT1 - UTC, Greenwich mean and apparent sidereal time and, with a longitude, the local ones; plus day of year and ISO week. Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.01 per call via REST POST https://astro-agent.dev/v1/astronomy/time (x402 or MPP); each client gets 1 free call on the $0.01-0.02 tools, this one included.
| Parameter | Type | Description |
|---|---|---|
| datetime * | string | The moment: UTC ('2026-06-21T12:00:00Z'), with an explicit offset, or local civil time with latitude/longitude. |
| latitude | number | Optional: resolve a local time, and give the local sidereal time. |
| timezone | string | IANA zone for local times, e.g. 'Europe/Paris'. Optional: resolved from the coordinates (with its historical DST rules). |
| longitude | number | Optional, with latitude. |
{
"name": "time_scales",
"title": "Julian day, sidereal time, Delta T and time scales",
"description": "Julian day, modified Julian day, sidereal time (Greenwich and local, mean and apparent), Delta T, TAI-UTC and UT1-UTC for a moment. E.g. {datetime: '2026-06-21T12:00:00Z', longitude: 2.35, latitude: 48.86}. For telescope control, data reduction and education: the Julian day in UTC, UT1, TT and TDB, the modified Julian day, Julian centuries since J2000 (TT), Delta T (TT - UT1), TAI - UTC and UT1 - UTC, Greenwich mean and apparent sidereal time and, with a longitude, the local ones; plus day of year and ISO week. Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.01 per call via REST POST https://astro-agent.dev/v1/astronomy/time (x402 or MPP); each client gets 1 free call on the $0.01-0.02 tools, this one included.",
"inputSchema": {
"type": "object",
"required": [
"datetime"
],
"properties": {
"datetime": {
"type": "string",
"description": "The moment: UTC ('2026-06-21T12:00:00Z'), with an explicit offset, or local civil time with latitude/longitude."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Optional: resolve a local time, and give the local sidereal time."
},
"timezone": {
"type": "string",
"description": "IANA zone for local times, e.g. 'Europe/Paris'. Optional: resolved from the coordinates (with its historical DST rules)."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Optional, with latitude."
}
}
},
"outputSchema": {
"type": "object",
"anyOf": [
{
"required": [
"endpoint",
"result",
"meta"
]
},
{
"required": [
"x402Version",
"accepts"
]
}
],
"properties": {
"meta": {
"type": "object",
"required": [
"engine",
"deterministic",
"llm_used",
"input_sha256",
"result_sha256"
],
"properties": {
"frame": {
"type": "string",
"description": "Reference frame of the positions."
},
"engine": {
"type": "string",
"description": "Engine name and version."
},
"payment": {
"type": "object",
"description": "How this call was paid: protocol ('free' or 'none'), price and the free calls remaining."
},
"llm_used": {
"type": "boolean",
"description": "Always false: no language model is involved."
},
"ephemeris": {
"type": "string",
"description": "Ephemeris used (NASA/JPL DE440)."
},
"compute_ms": {
"type": "number",
"description": "Computation time in milliseconds."
},
"computed_at": {
"type": "string",
"description": "When it was computed (UTC, ISO 8601)."
},
"input_sha256": {
"type": "string",
"description": "SHA-256 of the canonical input."
},
"deterministic": {
"type": "boolean",
"description": "Always true: same input, same result."
},
"result_sha256": {
"type": "string",
"description": "SHA-256 of the canonical 'result'; check it with verify_result_hash."
},
"reproducibility": {
"type": "string",
"description": "How to reproduce and check this result."
},
"astronomy_library": {
"type": "string",
"description": "Astronomy library and version."
}
},
"description": "Provenance of the result."
},
"error": {
"type": "string",
"description": "x402 offer only: why payment is required."
},
"result": {
"type": "object",
"required": [
"subject",
"settings",
"utc",
"unix_seconds",
"julian_day",
"modified_julian_day",
"julian_centuries_tt_since_j2000",
"delta_t_seconds",
"tai_minus_utc_seconds",
"ut1_minus_utc_seconds",
"sidereal_time",
"day_of_year",
"iso_week"
],
"properties": {
"utc": {
"type": "string",
"description": "UTC, ISO 8601."
},
"subject": {
"type": "object",
"description": "The resolved moment ('time': input, time zone and offset, UTC, Julian days, Delta T)."
},
"iso_week": {
"type": "string",
"description": "ISO 8601 week, e.g. 2026-W25."
},
"settings": {
"type": "object",
"description": "Every convention."
},
"julian_day": {
"type": "object",
"description": "Julian day in utc, ut1, tt and tdb."
},
"day_of_year": {
"type": "integer",
"description": "1..366."
},
"unix_seconds": {
"type": "number",
"description": "Seconds since 1970-01-01T00:00:00Z."
},
"sidereal_time": {
"type": "object",
"description": "gmst_hours, gast_hours and, with a place, longitude, lmst_hours, last_hours."
},
"delta_t_seconds": {
"type": "number",
"description": "TT - UT1, seconds."
},
"modified_julian_day": {
"type": "number",
"description": "JD(UTC) - 2400000.5."
},
"tai_minus_utc_seconds": {
"type": "number",
"description": "Leap seconds (TAI - UTC)."
},
"ut1_minus_utc_seconds": {
"type": "number",
"description": "UT1 - UTC, seconds."
},
"julian_centuries_tt_since_j2000": {
"type": "number",
"description": "(JD(TT) - 2451545.0) / 36525."
}
},
"description": "The calculation result."
},
"accepts": {
"type": "array",
"items": {
"type": "object"
},
"minItems": 1,
"description": "x402 offer only: the payment options (scheme, network, amount, asset, payTo, ...)."
},
"endpoint": {
"type": "string",
"description": "The REST route that computed it, e.g. 'astronomy/rise-set'."
},
"resource": {
"type": "object",
"description": "x402 offer only: the resource being paid for."
},
"extensions": {
"type": "object",
"description": "x402 offer only: protocol extensions (bazaar)."
},
"x402Version": {
"type": "integer",
"description": "x402 offer only: protocol version (2)."
}
}
},
"annotations": {
"title": "Julian day, sidereal time, Delta T and time scales",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}Convert sky coordinates between equatorial (J2000, of date), ecliptic, galactic and horizontal (alt-az) frames. E.g. {frame: 'equatorial_j2000', coordinates: {ra_hours: 6.7525, dec: -16.7161}, datetime: '2026-06-21T21:00:00Z', latitude: 48.8566, longitude: 2.3522}. For catalogues, planetarium and telescope software: give a direction in one frame and get it in all the others: equatorial J2000 (ICRS) and of date, ecliptic J2000 and of date, galactic, and horizontal (altitude, azimuth) when a datetime and a place are given. Geometric frame rotations of a direction (no aberration or refraction is added: use astronomy/altaz for where a body appears). Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.01 per call via REST POST https://astro-agent.dev/v1/astronomy/convert (x402 or MPP); each client gets 1 free call on the $0.01-0.02 tools, this one included.
| Parameter | Type | Description |
|---|---|---|
| frame * | string | The frame of the input coordinates. |
| datetime | string | Needed for the of-date and horizontal frames (UTC, offset, or local time with latitude/longitude). |
| latitude | number | Observer latitude, for the horizontal frame. |
| longitude | number | Observer longitude, for the horizontal frame. |
| coordinates * | object | The direction, with the two fields of its frame. |
Planetary phenomena between two dates: oppositions, conjunctions with the Sun, greatest elongations of Mercury and Venus, conjunctions between planets, perihelion and aphelion. E.g. {start: '2026-01-01', end: '2026-12-31', include: ['opposition']}. For almanacs, observing guides and astronomy newsletters: between two dates (up to 366 days, 1800-2199), each planet's conjunctions with the Sun, oppositions (with the Earth distance), greatest elongations east or west (with the angle), conjunctions between planets (with their angular separation and distance from the Sun), and perihelion and aphelion (heliocentric distance), each with a stable key. Matches the published 2026 dates. Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.10 per call via REST POST https://astro-agent.dev/v1/astronomy/phenomena (x402 or MPP); always paid, never a free call.
| Parameter | Type | Description |
|---|---|---|
| end * | string | Last UTC date, YYYY-MM-DD, at most 366 days after start. |
| start * | string | First UTC date, YYYY-MM-DD (1800-01-08..2199-12-30). |
| bodies | array | Planets to follow. Default: Mercury..Neptune. |
| include | array | Phenomena to return. Default: all. |
{
"name": "planetary_phenomena",
"title": "Planetary phenomena: oppositions, conjunctions, elongations",
"description": "Planetary phenomena between two dates: oppositions, conjunctions with the Sun, greatest elongations of Mercury and Venus, conjunctions between planets, perihelion and aphelion. E.g. {start: '2026-01-01', end: '2026-12-31', include: ['opposition']}. For almanacs, observing guides and astronomy newsletters: between two dates (up to 366 days, 1800-2199), each planet's conjunctions with the Sun, oppositions (with the Earth distance), greatest elongations east or west (with the angle), conjunctions between planets (with their angular separation and distance from the Sun), and perihelion and aphelion (heliocentric distance), each with a stable key. Matches the published 2026 dates. Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.10 per call via REST POST https://astro-agent.dev/v1/astronomy/phenomena (x402 or MPP); always paid, never a free call.",
"inputSchema": {
"type": "object",
"required": [
"start",
"end"
],
"properties": {
"end": {
"type": "string",
"description": "Last UTC date, YYYY-MM-DD, at most 366 days after start."
},
"start": {
"type": "string",
"description": "First UTC date, YYYY-MM-DD (1800-01-08..2199-12-30)."
},
"bodies": {
"type": "array",
"items": {
"enum": [
"mercury",
"venus",
"mars",
"jupiter",
"saturn",
"uranus",
"neptune"
],
"type": "string"
},
"description": "Planets to follow. Default: Mercury..Neptune."
},
"include": {
"type": "array",
"items": {
"enum": [
"conjunction",
"opposition",
"greatest_elongation",
"planet_conjunction",
"perihelion",
"aphelion"
],
"type": "string"
},
"description": "Phenomena to return. Default: all."
}
}
},
"outputSchema": {
"type": "object",
"anyOf": [
{
"required": [
"endpoint",
"result",
"meta"
]
},
{
"required": [
"x402Version",
"accepts"
]
}
],
"properties": {
"meta": {
"type": "object",
"required": [
"engine",
"deterministic",
"llm_used",
"input_sha256",
"result_sha256"
],
"properties": {
"frame": {
"type": "string",
"description": "Reference frame of the positions."
},
"engine": {
"type": "string",
"description": "Engine name and version."
},
"payment": {
"type": "object",
"description": "How this call was paid: protocol ('free' or 'none'), price and the free calls remaining."
},
"llm_used": {
"type": "boolean",
"description": "Always false: no language model is involved."
},
"ephemeris": {
"type": "string",
"description": "Ephemeris used (NASA/JPL DE440)."
},
"compute_ms": {
"type": "number",
"description": "Computation time in milliseconds."
},
"computed_at": {
"type": "string",
"description": "When it was computed (UTC, ISO 8601)."
},
"input_sha256": {
"type": "string",
"description": "SHA-256 of the canonical input."
},
"deterministic": {
"type": "boolean",
"description": "Always true: same input, same result."
},
"result_sha256": {
"type": "string",
"description": "SHA-256 of the canonical 'result'; check it with verify_result_hash."
},
"reproducibility": {
"type": "string",
"description": "How to reproduce and check this result."
},
"astronomy_library": {
"type": "string",
"description": "Astronomy library and version."
}
},
"description": "Provenance of the result."
},
"error": {
"type": "string",
"description": "x402 offer only: why payment is required."
},
"result": {
"type": "object",
"required": [
"settings",
"events",
"counts"
],
"properties": {
"counts": {
"type": "object",
"description": "Number of events per type."
},
"events": {
"type": "array",
"description": "In time order: {type, utc, timestamp, key, body | bodies, and per type: kind (inferior / superior), separation_from_sun_deg, distance_au, direction (east / west), elongation_deg, separation_deg, elongation_from_sun_deg, heliocentric_distance_au}."
},
"settings": {
"type": "object",
"description": "start, end, bodies, include and every convention."
}
},
"description": "The calculation result."
},
"accepts": {
"type": "array",
"items": {
"type": "object"
},
"minItems": 1,
"description": "x402 offer only: the payment options (scheme, network, amount, asset, payTo, ...)."
},
"endpoint": {
"type": "string",
"description": "The REST route that computed it, e.g. 'astronomy/rise-set'."
},
"resource": {
"type": "object",
"description": "x402 offer only: the resource being paid for."
},
"extensions": {
"type": "object",
"description": "x402 offer only: protocol extensions (bazaar)."
},
"x402Version": {
"type": "integer",
"description": "x402 offer only: protocol version (2)."
}
}
},
"annotations": {
"title": "Planetary phenomena: oppositions, conjunctions, elongations",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}Solar and lunar eclipses seen from a place: local type, contact times (C1-C4, P1-P4, U1-U4), magnitude, obscuration, duration of totality and the Sun's or Moon's altitude. E.g. {start: '2026-08-01', end: '2026-08-31', latitude: 39.47, longitude: -0.38}. For eclipse chasers, planetariums, schools and travel apps: solar eclipses from the place's own viewpoint (local type: total, annular, partial or none; contacts C1, C2, maximum, C3, C4 with the Sun's altitude and azimuth; magnitude, obscuration, duration, duration of totality or annularity) and lunar eclipses (penumbral and umbral contacts P1, U1, U2, maximum, U3, U4, P4 with the Moon's altitude, umbral and penumbral magnitude, durations), each marked visible when the body is above the horizon. Matches NASA's predictions to a few seconds (2024-04-08 at Dallas, 2025-03-14 lunar eclipse). Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.10 per call via REST POST https://astro-agent.dev/v1/astronomy/eclipse-local (x402 or MPP); always paid, never a free call.
| Parameter | Type | Description |
|---|---|---|
| end * | string | Last UTC date, YYYY-MM-DD, at most 366 days after start. |
| kinds | array | Eclipse kinds to return. Default: both. |
| start * | string | First UTC date, YYYY-MM-DD (1800-01-08..2199-12-30). |
| latitude * | number | Decimal degrees, north positive. |
| timezone | string | IANA zone for local times, e.g. 'Europe/Paris'. Optional: resolved from the coordinates (with its historical DST rules). |
| longitude |
Solunar periods for a place and day: major periods around the Moon's upper and lower transits, minor periods around moonrise and moonset, in local time. E.g. {date: '2026-06-21', latitude: 48.8566, longitude: 2.3522}. For fishing, hunting and outdoor apps that use the solunar timing convention: for one local day at a place, each major period (centred on the Moon's upper transit overhead and lower transit underfoot, 2 h by default) and minor period (centred on moonrise and moonset, 1 h by default) with its start, centre and end in local time, the Moon's altitude at its transits and its phase. The events are exact (astronomy/rise-set conventions); the windows are the convention's, adjustable. No rating attached. Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.01 per call via REST POST https://astro-agent.dev/v1/astronomy/solunar (x402 or MPP); each client gets 1 free call on the $0.01-0.02 tools, this one included.
| Parameter | Type | Description |
|---|---|---|
| date * | string | The local calendar day at the place, YYYY-MM-DD (1800-01-02..2199-12-30). |
| options | object | Window lengths. |
| latitude * | number | Decimal degrees, north positive. |
| timezone | string | IANA zone for local times, e.g. 'Europe/Paris'. Optional: resolved from the coordinates (with its historical DST rules). |
| longitude * | number | Decimal degrees, east positive. |
| elevation_m | number |
Planetary positions and ephemeris API (NASA/JPL DE440): the ecliptic longitude, latitude, speed, retrograde flag and distance of the Sun, Moon, planets and lunar nodes at any moment 1800-2200, geocentric or heliocentric, ecliptic or equatorial (right ascension, declination). E.g. {datetime: '2026-10-01T12:00:00Z'}. Geocentric apparent positions from NASA/JPL DE440 (true ecliptic and equinox of date, IAU 2006/2000A), with the Moon's ascending and descending nodes and its mean apogee. Location is optional (only used to interpret a local time). Options: 'heliocentric' perspective (seen from the Sun) and 'equatorial' coordinates (right ascension, declination, and whether |declination| exceeds the obliquity). Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.01 per call via REST POST https://astro-agent.dev/v1/astronomy/positions (x402 or MPP); each client gets 1 free call on the $0.01-0.02 tools, this one included.
| Parameter | Type | Description |
|---|---|---|
| date | string | YYYY-MM-DD (use with 'time' instead of 'datetime'). |
| time | string | HH:MM or HH:MM:SS, 24 h. Omit if unknown (computed at 12:00 with a TIME_UNKNOWN warning). |
| options | object | Optional. |
| datetime | string | Local civil date-time, ISO 8601: '1990-05-15T14:30' (local clock time at the place) or with an explicit offset '1990-05-15T14:30:00+02:00'. Alternative: 'date' + 'time'. |
| latitude | number | Decimal degrees, north positive. |
| timezone | string | IANA zone, e.g. 'Asia/Kolkata'. Optional: resolved from the coordinates, with the historical offset (DST, Local Mean Time) of that date. |
The sky now (no location needed): planet positions, retrograde planets and the Moon phase, plus the exact UTC minute of the next stations, lunations and separations. E.g. {datetime: '2026-10-01T00:00Z', days: 30}. One call for 'what is happening in the sky': positions, retrograde planets, the Moon's phase, and the events of the next days (1-90): stations, lunations, separations of 0, 60, 90, 120 and 180 degrees, and ecliptic longitudes crossing multiples of 30 degrees, each to the minute (UTC). Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.01 per call via REST POST https://astro-agent.dev/v1/astronomy/sky (x402 or MPP); each client gets 1 free call on the $0.01-0.02 tools, this one included.
| Parameter | Type | Description |
|---|---|---|
| date | string | YYYY-MM-DD (use with 'time' instead of 'datetime'). |
| days | integer | How many days ahead to list events. Example: 30. |
| time | string | HH:MM or HH:MM:SS, 24 h. Omit if unknown (computed at 12:00 with a TIME_UNKNOWN warning). |
| datetime | string | Local civil date-time, ISO 8601: '1990-05-15T14:30' (local clock time at the place) or with an explicit offset '1990-05-15T14:30:00+02:00'. Alternative: 'date' + 'time'. |
| latitude | number | Decimal degrees, north positive. |
| timezone | string | IANA zone, e.g. 'Asia/Kolkata'. Optional: resolved from the coordinates, with the historical offset (DST, Local Mean Time) of that date. |
| longitude | number |
Angular separations between planets at a moment, or between longitudes you supply: the pairs near 0, 60, 90, 120 or 180 degrees (or any angle you choose) with the deviation, approaching or receding; optionally equal and opposite declinations. E.g. {longitudes: {sun: 54.4, moon: 297.4}}. For a moment (computed from DE440) or for longitudes you supply: every pair of bodies at a chosen separation angle, with its deviation from the exact angle, the tolerance applied, and whether the bodies are approaching or receding from it. Option 'declination': pairs with equal or opposite declinations. Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.02 per call via REST POST https://astro-agent.dev/v1/astronomy/angles (x402 or MPP); each client gets 1 free call on the $0.01-0.02 tools, this one included.
| Parameter | Type | Description |
|---|---|---|
| date | string | YYYY-MM-DD (use with 'time' instead of 'datetime'). |
| time | string | HH:MM or HH:MM:SS, 24 h. Omit if unknown (computed at 12:00 with a TIME_UNKNOWN warning). |
| options | object | Optional. |
| datetime | string | Local civil date-time, ISO 8601: '1990-05-15T14:30' (local clock time at the place) or with an explicit offset '1990-05-15T14:30:00+02:00'. Alternative: 'date' + 'time'. |
| latitude | number | Decimal degrees, north positive. |
| timezone | string | IANA zone, e.g. 'Asia/Kolkata'. Optional: resolved from the coordinates, with the historical offset (DST, Local Mean Time) of that date. |
| longitude |
Celestial event calendar: the exact UTC minute and unix timestamp of every solar and lunar eclipse, planetary station (retrograde / direct), lunation and separation between two dates, 1800-2200. E.g. {start: '2026-01-01', end: '2026-12-31', include: ['eclipse', 'station']}. A calendar of exact events between two dates: solar and lunar eclipses (type and magnitude), stations (retrograde / direct), new and full Moons and quarters, separations between planets at chosen angles, ecliptic longitudes crossing multiples of 30 degrees, equal / opposite declinations, and declinations passing the obliquity of the ecliptic. Geocentric or heliocentric. Each event has its UTC minute, a unix timestamp and a stable key. Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.25 per call via REST POST https://astro-agent.dev/v1/astronomy/events (x402 or MPP); always paid, never a free call.
| Parameter | Type | Description |
|---|---|---|
| end * | string | Last UTC date, YYYY-MM-DD, at most 366 days after start (inclusive). |
| start * | string | First UTC date, YYYY-MM-DD, 1800..2199. Example: '2024-01-01'. |
| angles | any | Separation angles in degrees, 'all' or a list from [0, 30, 45, 60, 72, 90, 120, 135, 144, 150, 180]. Default: [0, 60, 90, 120, 180]. |
| bodies | array | Planets searched. Default: Sun..Pluto (geo), Mercury..Pluto with Earth (helio). |
| include | array | Event types. Default: all that apply to the perspective. 'separation': two bodies reach one of the 'angles'; 'longitude_crossing': a body's ecliptic longitude crosses a multiple of 30 degrees; 'declination': equal or opposite declinations; 'declination_beyond_obliquity': |declination| passes the obl… |
Planetary longitude time series: planet degrees seen from the Earth and from the Sun (geocentric and heliocentric) at a moment or every hour to every week, as pandas-ready columns, with speeds, retrograde flags and declinations. E.g. {start: '2024-01-01', end: '2024-12-31', interval: '1w', bodies: ['jupiter', 'saturn']}. Planetary longitudes as data: at a moment, or as a series of up to 1000 samples (columns ready for pandas). Geocentric apparent and heliocentric geometric, each with its speed and retrograde flag; optional offsets (longitude + angle), circular or arithmetic multi-body averages, unwrapped degrees for plotting, and declinations. Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.20 per call via REST POST https://astro-agent.dev/v1/astronomy/longitude-series (x402 or MPP); always paid, never a free call.
| Parameter | Type | Description |
|---|---|---|
| end | string | Series: last UTC date, YYYY-MM-DD (at most 1000 samples). |
| start | string | Series: first UTC date, YYYY-MM-DD. Example: '2024-01-01'. |
| bodies | array | Bodies. Default: Sun..Pluto (geocentric), Mercury..Pluto with the Earth (heliocentric). |
| format | string | Series layout: 'columns' (pandas.DataFrame(result['series'])) or 'rows' (one object per sample). |
| unwrap | boolean | Series: continuous degrees (no 360 -> 0 jump), for plotting. |
| offsets | any | Angles in degrees added to every longitude (+angle and -angle), 'all' or a list from [0, 30, 45, 60, 72, 90, 120, 135, 144, 150, 180]. Default: none (the longitude itself). |
Sky similarity search: find the past or future dates whose planetary positions best match a reference sky, ranked by a stated angular distance in degrees. E.g. {reference: '2026-10-29T00:00Z', direction: 'past', bodies: ['jupiter', 'saturn']}. Searches a date grid (1 hour to 1 week steps, 1800-2200) for the skies closest to a reference: by longitude, by the separations between bodies, by declination, optionally with the same retrograde flags. The score is a weighted mean angular distance in degrees, defined in result.settings.metric. Data for your own analysis — never a signal or forecast. Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.25 per call via REST POST https://astro-agent.dev/v1/astronomy/sky-analogues (x402 or MPP); always paid, never a free call.
| Parameter | Type | Description |
|---|---|---|
| range | object | Candidate dates. Default (a reference with a time): the longest window the caps allow, up to 100 years in the chosen direction (50 on each side for 'both'). |
| top_n | integer | How many matches. |
| bodies | array | Bodies to match. Default: Sun..Pluto (geo), Mercury..Pluto with Earth (helio). |
| format | string | 'columns' (pandas.DataFrame(result['matches'])) or 'rows' (one object per match). |
| weights | object | Optional {feature id: weight}, default 1 each, e.g. {'geo.jupiter': 2}. Feature ids: '<geo|helio>.<body>' (longitude, 0-360), '<geo|helio>.<a>-<b>:angle' (separation, 0-180), '<geo|helio>.<body>:declination' (degrees) and 'geo.<body>:retrograde' (true/false). |
| features | array | What to compare: 'longitude' (default), 'separations' (the angle between every pair of bodies), 'declination', 'retrograde' (a filter on equal retrograde flags). |
Local time to UTC conversion: convert a local date, time and place into exact Universal Time, with the historical time zone and UTC offset, Delta T, Local Mean Time and true solar time. E.g. {datetime: '1947-08-15T00:00', latitude: 28.6139, longitude: 77.209}. Resolves the IANA time zone from coordinates, applies the offset in force on that date (historical daylight saving, Local Mean Time before standard time), flags ambiguous or non-existent local times instead of guessing, and returns Julian Days (UT/TT), Delta T, Local Mean Time, true (apparent) solar time and the equation of time. Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.01 per call via REST POST https://astro-agent.dev/v1/astronomy/local-time (x402 or MPP); each client gets 1 free call on the $0.01-0.02 tools, this one included.
| Parameter | Type | Description |
|---|---|---|
| date | string | YYYY-MM-DD (use with 'time' instead of 'datetime'). |
| time | string | HH:MM or HH:MM:SS, 24 h. Omit if unknown (computed at 12:00 with a TIME_UNKNOWN warning). |
| datetime | string | Local civil date-time, ISO 8601: '1990-05-15T14:30' (local clock time at the place) or with an explicit offset '1990-05-15T14:30:00+02:00'. Alternative: 'date' + 'time'. |
| latitude | number | Decimal degrees, north positive. |
| timezone | string | IANA zone, e.g. 'Asia/Kolkata'. Optional: resolved from the coordinates, with the historical offset (DST, Local Mean Time) of that date. |
| longitude | number | Decimal degrees, east positive. |
List every astronomical data and ephemeris tool with its price, input schema and an example request: planet positions, event calendar (eclipses, Mercury retrograde), longitude series, sky similarity search and more. Free; call it first to pick the right tool.
No parameters.
{
"name": "astro_catalog",
"title": "Catalog (free)",
"description": "List every astronomical data and ephemeris tool with its price, input schema and an example request: planet positions, event calendar (eclipses, Mercury retrograde), longitude series, sky similarity search and more. Free; call it first to pick the right tool.",
"inputSchema": {
"type": "object",
"properties": {}
},
"outputSchema": {
"type": "object",
"required": [
"service",
"calls",
"premium"
],
"properties": {
"calls": {
"type": "array",
"description": "The $0.01-0.02 tools: MCP tool name, price, REST route, what it computes and an example request (input schemas are in tools/list)."
},
"payment": {
"type": "object",
"description": "Free calls, payment protocols (x402, MPP) and networks."
},
"premium": {
"type": "array",
"description": "The full-chart tools, same fields as 'calls'."
},
"service": {
"type": "string",
"description": "Service name."
},
"support": {
"type": "object",
"description": "Contact, documentation and policies."
},
"tagline": {
"type": "string",
"description": "One-line summary of the service."
},
"accuracy": {
"type": "object",
"description": "Headline of the accuracy benchmark against NASA/JPL Horizons (largest deviations in arcseconds) with links to the details."
},
"discovery": {
"type": "object",
"description": "Discovery documents: OpenAPI, MCP server card, A2A agent card."
},
"whats_new": {
"type": "object",
"description": "What the current release added (version, date, and each new tool or proof with its route, price and summary)."
},
"start_here": {
"type": "string",
"description": "Which tool to call first for common questions."
},
"engine_version": {
"type": "string",
"description": "Calculation engine version."
},
"free_endpoints": {
"type": "object",
"description": "Endpoints that are always free (catalog, verify, health, benchmark)."
},
"why_use_this_instead_of_computing_it_yourself": {
"type": "array",
"description": "Reasons to prefer these tools over computing a chart yourself."
}
}
},
"annotations": {
"title": "Catalog (free)",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}Verify that an astronomical data result was not altered: recompute the SHA-256 of a 'result' object returned by any tool and compare it with the result_sha256 you hold. Free.
| Parameter | Type | Description |
|---|---|---|
| result * | object | The 'result' object exactly as a tool returned it. |
| result_sha256 | string | The meta.result_sha256 returned with it (64 hex characters). Omit to only recompute the hash. |
{
"name": "verify_result_hash",
"title": "Verify a result hash (free)",
"description": "Verify that an astronomical data result was not altered: recompute the SHA-256 of a 'result' object returned by any tool and compare it with the result_sha256 you hold. Free.",
"inputSchema": {
"type": "object",
"required": [
"result"
],
"properties": {
"result": {
"type": "object",
"description": "The 'result' object exactly as a tool returned it."
},
"result_sha256": {
"type": "string",
"description": "The meta.result_sha256 returned with it (64 hex characters). Omit to only recompute the hash."
}
}
},
"outputSchema": {
"type": "object",
"required": [
"result_sha256"
],
"properties": {
"matches": {
"type": "boolean",
"description": "Whether it equals the result_sha256 you sent. Absent if you sent none."
},
"result_sha256": {
"type": "string",
"description": "SHA-256 recomputed from the 'result' you sent."
}
}
},
"annotations": {
"title": "Verify a result hash (free)",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}Astro Agents 1.10.0: Research-grade astronomical data & computation API — NASA/JPL DE440 ephemerides for any date, past, present or future, reproducible and SHA-256 verifiable. Research-grade astronomical data and computation from NASA/JPL DE440 -- no LLM, any date from 1800 to 2200 (past, present or future), every result reproducible and hashed (meta.result_sha256; verify_result_hash recomputes it), accuracy benchmarked against NASA/JPL Horizons (https://astro-agent.dev/benchmark.md). Data only: no predictions, never a signal or forecast. Use these tools instead of computing positions yourself: time zones, historical DST, Delta T and sidereal time are where language models err. Astronomy tools: day_summary (the whole day's sky for a place in one call), rise_set_times (rise, transit and set of every body for a place and local day, twilight, golden and blue hour), altitude_azimuth (where each body is in the sky from a place), observation_windows (when each planet can be observed tonight), moon_details (phase, illumination, distance, next phases, perigee and apogee), local_eclipse (eclipse contacts and visibility from a place), planetary_phenomena (oppositions, conjunctions, greatest elongations), seasons (equinoxes, solstices, perihelion, day length), solunar_periods (lunar transit and moonrise/moonset windows), body_positions (geocentric or heliocentric, ecliptic or equatorial: right ascension, declination; speeds, retrograde flags), sky_now (positions, Moon phase, the next stations, lunations and separations), angular_separations (angles between bodies), celestial_events (solar and lunar eclipses, stations, lunations, separations, to the minute), longitude_series (time series, geocentric + heliocentric, 1 hour to 1 week), similar_skies (the dates whose sky best matches a reference sky, by a stated angular distance), convert_coordinates (equatorial, ecliptic, galactic, horizontal), time_scales (Julian day, sidereal time, Delta T), resolve_local_time (any local time -> UT, historical time zone, Delta T, Local Mean Time, true solar time). Inputs: a 'datetime' (UTC 'Z', an explicit offset, or local clock time with 'latitude' + 'longitude': the time zone and its historical offset are resolved for you). 1 free call per client on the $0.01-0.02 tools; every other tool is always paid: per call over REST (x402 or MPP), or right here over MCP: prepaid credits (HTTP header X-Credits-Token in this server's configuration) or native x402 per call (the tool result carries the x402 offer; retry with the signed payment in _meta['x402/payment'], the settlement comes back in _meta['x402/payment-response']). astro_catalog lists every tool with prices and examples.
Names, descriptions and schemas were written by the server and are shown as data.
Pattern matches on what the server declares. They show what it says it can do, not what it does.
None yet. Changes appear after a server's second daily check.
| number |
| Decimal degrees, east positive. |
| elevation_m | number | Height above the WGS84 ellipsoid, metres (no terrain or horizon dip is modelled). |
{
"name": "altitude_azimuth",
"title": "Altitude and azimuth of every body from a place",
"description": "Where the Sun, Moon and planets are in the sky from a place at a moment: altitude, azimuth, compass point, topocentric right ascension and declination, distance, elongation, illumination, magnitude and the sky state. E.g. {datetime: '2026-06-21T23:00', latitude: 48.8566, longitude: 2.3522}. For sky maps, telescope pointing, AR and observation apps: each body's apparent altitude and azimuth (with refraction, or airless), whether it is above the horizon, its topocentric right ascension and declination, distance (and the Moon's in km), angular distance from the Sun, illuminated fraction and visual magnitude (planets), plus the sky state (day, civil / nautical / astronomical twilight, night). Matches NASA/JPL Horizons to under a second of arc. Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.01 per call via REST POST https://astro-agent.dev/v1/astronomy/altaz (x402 or MPP); each client gets 1 free call on the $0.01-0.02 tools, this one included.",
"inputSchema": {
"type": "object",
"required": [
"datetime",
"latitude",
"longitude"
],
"properties": {
"bodies": {
"type": "array",
"items": {
"enum": [
"sun",
"moon",
"mercury",
"venus",
"mars",
"jupiter",
"saturn",
"uranus",
"neptune",
"pluto"
],
"type": "string"
},
"description": "Bodies to locate. Default: all ten."
},
"options": {
"type": "object",
"properties": {
"refraction": {
"type": "boolean",
"default": true,
"description": "Apply atmospheric refraction to the altitude (true) or give the geometric, airless altitude (false)."
},
"pressure_hpa": {
"type": [
"number",
"string"
],
"default": "standard",
"description": "Air pressure for refraction, hPa, or 'standard' (from the elevation)."
},
"temperature_c": {
"type": "number",
"default": 10,
"description": "Air temperature for refraction, deg C."
}
},
"description": "Refraction settings."
},
"datetime": {
"type": "string",
"description": "The moment: UTC ('2026-06-21T21:00:00Z'), with an explicit offset, or local civil time at the place ('2026-06-21T23:00', time zone resolved from the coordinates)."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Decimal degrees, north positive."
},
"timezone": {
"type": "string",
"description": "IANA zone for local times, e.g. 'Europe/Paris'. Optional: resolved from the coordinates (with its historical DST rules)."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Decimal degrees, east positive."
},
"elevation_m": {
"type": "number",
"default": 0,
"maximum": 9000,
"minimum": -500,
"description": "Height above the WGS84 ellipsoid, metres (no terrain or horizon dip is modelled)."
}
}
},
"outputSchema": {
"type": "object",
"anyOf": [
{
"required": [
"endpoint",
"result",
"meta"
]
},
{
"required": [
"x402Version",
"accepts"
]
}
],
"properties": {
"meta": {
"type": "object",
"required": [
"engine",
"deterministic",
"llm_used",
"input_sha256",
"result_sha256"
],
"properties": {
"frame": {
"type": "string",
"description": "Reference frame of the positions."
},
"engine": {
"type": "string",
"description": "Engine name and version."
},
"payment": {
"type": "object",
"description": "How this call was paid: protocol ('free' or 'none'), price and the free calls remaining."
},
"llm_used": {
"type": "boolean",
"description": "Always false: no language model is involved."
},
"ephemeris": {
"type": "string",
"description": "Ephemeris used (NASA/JPL DE440)."
},
"compute_ms": {
"type": "number",
"description": "Computation time in milliseconds."
},
"computed_at": {
"type": "string",
"description": "When it was computed (UTC, ISO 8601)."
},
"input_sha256": {
"type": "string",
"description": "SHA-256 of the canonical input."
},
"deterministic": {
"type": "boolean",
"description": "Always true: same input, same result."
},
"result_sha256": {
"type": "string",
"description": "SHA-256 of the canonical 'result'; check it with verify_result_hash."
},
"reproducibility": {
"type": "string",
"description": "How to reproduce and check this result."
},
"astronomy_library": {
"type": "string",
"description": "Astronomy library and version."
}
},
"description": "Provenance of the result."
},
"error": {
"type": "string",
"description": "x402 offer only: why payment is required."
},
"result": {
"type": "object",
"required": [
"subject",
"settings",
"sky",
"bodies"
],
"properties": {
"sky": {
"type": "object",
"description": "The Sun's altitude and the sky state: day, civil_twilight, nautical_twilight, astronomical_twilight or night."
},
"bodies": {
"type": "array",
"description": "One row per body: altitude, azimuth, compass point, above_horizon, right_ascension_hours, declination, distance_au (and distance_km for the Moon), elongation from the Sun, illuminated_fraction and magnitude (planets)."
},
"subject": {
"type": "object",
"description": "The place, its time zone, and the resolved moment ('time': local input, UTC, offset, Julian days, Delta T)."
},
"settings": {
"type": "object",
"description": "The bodies, whether refraction is applied (with temperature and pressure) and every convention."
}
},
"description": "The calculation result."
},
"accepts": {
"type": "array",
"items": {
"type": "object"
},
"minItems": 1,
"description": "x402 offer only: the payment options (scheme, network, amount, asset, payTo, ...)."
},
"endpoint": {
"type": "string",
"description": "The REST route that computed it, e.g. 'astronomy/rise-set'."
},
"resource": {
"type": "object",
"description": "x402 offer only: the resource being paid for."
},
"extensions": {
"type": "object",
"description": "x402 offer only: protocol extensions (bazaar)."
},
"x402Version": {
"type": "integer",
"description": "x402 offer only: protocol version (2)."
}
}
},
"annotations": {
"title": "Altitude and azimuth of every body from a place",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}| elevation_m | number | Height above the WGS84 ellipsoid, metres (no terrain or horizon dip is modelled). |
{
"name": "observation_windows",
"title": "Observation windows for a night",
"description": "Which planets and the Moon can be observed tonight from a place, and when: windows above a minimum altitude while the sky is dark, with the best time, altitude, azimuth and magnitude. E.g. {date: '2026-06-21', latitude: 48.8566, longitude: 2.3522}. For observation planning: over the night that starts on 'date' (local noon to noon), the intervals when each body stands at least min_altitude_deg above the horizon while the Sun is at or below sun_altitude_max_deg (default -6: after civil dusk), each with start, end, duration and the best moment (highest altitude) with its azimuth and visual magnitude; plus the dark interval itself. Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.02 per call via REST POST https://astro-agent.dev/v1/astronomy/visibility (x402 or MPP); each client gets 1 free call on the $0.01-0.02 tools, this one included.",
"inputSchema": {
"type": "object",
"required": [
"date",
"latitude",
"longitude"
],
"properties": {
"date": {
"type": "string",
"description": "The evening that starts the observing night, YYYY-MM-DD: the night runs from local noon on that date to local noon the next day."
},
"bodies": {
"type": "array",
"items": {
"enum": [
"moon",
"mercury",
"venus",
"mars",
"jupiter",
"saturn",
"uranus",
"neptune",
"pluto"
],
"type": "string"
},
"description": "Bodies to plan. Default: the Moon and Mercury..Neptune."
},
"options": {
"type": "object",
"properties": {
"min_altitude_deg": {
"type": "number",
"default": 10,
"maximum": 89,
"minimum": -5,
"description": "Lowest useful altitude of the body above the horizon, degrees."
},
"sun_altitude_max_deg": {
"type": "number",
"default": -6,
"maximum": 0,
"minimum": -18,
"description": "The sky counts as dark when the Sun is at or below this altitude: -6 civil, -12 nautical, -18 astronomical."
}
},
"description": "What counts as observable."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Decimal degrees, north positive."
},
"timezone": {
"type": "string",
"description": "IANA zone for local times, e.g. 'Europe/Paris'. Optional: resolved from the coordinates (with its historical DST rules)."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Decimal degrees, east positive."
},
"elevation_m": {
"type": "number",
"default": 0,
"maximum": 9000,
"minimum": -500,
"description": "Height above the WGS84 ellipsoid, metres (no terrain or horizon dip is modelled)."
}
}
},
"outputSchema": {
"type": "object",
"anyOf": [
{
"required": [
"endpoint",
"result",
"meta"
]
},
{
"required": [
"x402Version",
"accepts"
]
}
],
"properties": {
"meta": {
"type": "object",
"required": [
"engine",
"deterministic",
"llm_used",
"input_sha256",
"result_sha256"
],
"properties": {
"frame": {
"type": "string",
"description": "Reference frame of the positions."
},
"engine": {
"type": "string",
"description": "Engine name and version."
},
"payment": {
"type": "object",
"description": "How this call was paid: protocol ('free' or 'none'), price and the free calls remaining."
},
"llm_used": {
"type": "boolean",
"description": "Always false: no language model is involved."
},
"ephemeris": {
"type": "string",
"description": "Ephemeris used (NASA/JPL DE440)."
},
"compute_ms": {
"type": "number",
"description": "Computation time in milliseconds."
},
"computed_at": {
"type": "string",
"description": "When it was computed (UTC, ISO 8601)."
},
"input_sha256": {
"type": "string",
"description": "SHA-256 of the canonical input."
},
"deterministic": {
"type": "boolean",
"description": "Always true: same input, same result."
},
"result_sha256": {
"type": "string",
"description": "SHA-256 of the canonical 'result'; check it with verify_result_hash."
},
"reproducibility": {
"type": "string",
"description": "How to reproduce and check this result."
},
"astronomy_library": {
"type": "string",
"description": "Astronomy library and version."
}
},
"description": "Provenance of the result."
},
"error": {
"type": "string",
"description": "x402 offer only: why payment is required."
},
"result": {
"type": "object",
"required": [
"subject",
"settings",
"dark",
"bodies"
],
"properties": {
"dark": {
"type": "array",
"description": "The intervals when the Sun is at or below sun_altitude_max_deg: [{start, end}]."
},
"bodies": {
"type": "array",
"description": "One row per body: visible, total_minutes, max_altitude and windows [{start, end, duration_minutes, best: {utc, local, timestamp, altitude, azimuth, magnitude}}]."
},
"subject": {
"type": "object",
"description": "The place, its time zone, the date and the night's window in UTC (local noon to noon)."
},
"settings": {
"type": "object",
"description": "The bodies, min_altitude_deg, sun_altitude_max_deg, the sampling step and every convention."
}
},
"description": "The calculation result."
},
"accepts": {
"type": "array",
"items": {
"type": "object"
},
"minItems": 1,
"description": "x402 offer only: the payment options (scheme, network, amount, asset, payTo, ...)."
},
"endpoint": {
"type": "string",
"description": "The REST route that computed it, e.g. 'astronomy/rise-set'."
},
"resource": {
"type": "object",
"description": "x402 offer only: the resource being paid for."
},
"extensions": {
"type": "object",
"description": "x402 offer only: protocol extensions (bazaar)."
},
"x402Version": {
"type": "integer",
"description": "x402 offer only: protocol version (2)."
}
}
},
"annotations": {
"title": "Observation windows for a night",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}{
"name": "moon_details",
"title": "Moon phase, illumination, distance and next phases",
"description": "Moon phase today and in detail: phase name and angle, illuminated fraction, age, distance, apparent size, the next new, quarter and full Moons, and the next perigee and apogee; with a place, moonrise and moonset. E.g. {datetime: '2026-01-03T12:00:00Z'}. For calendar, weather, photography and tide apps: phase (8 names), phase angle, illuminated fraction, waxing or waning, age in days since the new Moon, Brown lunation number, centre-to-centre distance in km and Earth radii, angular diameter, ecliptic position, the previous new Moon, the next four principal phases and the next perigee and apogee with their distances, to the second. With latitude/longitude: the Moon's altitude and azimuth there and that local day's moonrise, transit and moonset. Perigee and apogee match NASA/JPL Horizons to the minute. Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.01 per call via REST POST https://astro-agent.dev/v1/astronomy/moon (x402 or MPP); each client gets 1 free call on the $0.01-0.02 tools, this one included.",
"inputSchema": {
"type": "object",
"properties": {
"datetime": {
"type": "string",
"description": "The moment: UTC, an explicit offset, or local civil time at the place given by latitude/longitude. Default: now (UTC, to the minute)."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Optional: add the Moon's altitude and azimuth from this place and that local day's moonrise, transit and moonset."
},
"timezone": {
"type": "string",
"description": "IANA zone for local times, e.g. 'Europe/Paris'. Optional: resolved from the coordinates (with its historical DST rules)."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Optional, with latitude."
},
"elevation_m": {
"type": "number",
"default": 0,
"maximum": 9000,
"minimum": -500,
"description": "Height above the WGS84 ellipsoid, metres (no terrain or horizon dip is modelled)."
}
}
},
"outputSchema": {
"type": "object",
"anyOf": [
{
"required": [
"endpoint",
"result",
"meta"
]
},
{
"required": [
"x402Version",
"accepts"
]
}
],
"properties": {
"meta": {
"type": "object",
"required": [
"engine",
"deterministic",
"llm_used",
"input_sha256",
"result_sha256"
],
"properties": {
"frame": {
"type": "string",
"description": "Reference frame of the positions."
},
"engine": {
"type": "string",
"description": "Engine name and version."
},
"payment": {
"type": "object",
"description": "How this call was paid: protocol ('free' or 'none'), price and the free calls remaining."
},
"llm_used": {
"type": "boolean",
"description": "Always false: no language model is involved."
},
"ephemeris": {
"type": "string",
"description": "Ephemeris used (NASA/JPL DE440)."
},
"compute_ms": {
"type": "number",
"description": "Computation time in milliseconds."
},
"computed_at": {
"type": "string",
"description": "When it was computed (UTC, ISO 8601)."
},
"input_sha256": {
"type": "string",
"description": "SHA-256 of the canonical input."
},
"deterministic": {
"type": "boolean",
"description": "Always true: same input, same result."
},
"result_sha256": {
"type": "string",
"description": "SHA-256 of the canonical 'result'; check it with verify_result_hash."
},
"reproducibility": {
"type": "string",
"description": "How to reproduce and check this result."
},
"astronomy_library": {
"type": "string",
"description": "Astronomy library and version."
}
},
"description": "Provenance of the result."
},
"error": {
"type": "string",
"description": "x402 offer only: why payment is required."
},
"result": {
"type": "object",
"required": [
"subject",
"settings",
"phase",
"distance",
"position",
"previous_new_moon",
"next_phases",
"next_perigee",
"next_apogee"
],
"properties": {
"local": {
"type": "object",
"description": "With latitude/longitude only: location, time zone, altitude, azimuth, above_horizon and that local day's rise, transit, set and state."
},
"phase": {
"type": "object",
"description": "name (new moon, waxing crescent... waning crescent), phase_angle (0-360), illuminated_fraction, waxing, age_days, lunation (Brown)."
},
"subject": {
"type": "object",
"description": "The resolved moment ('time': input, UTC, Julian days, Delta T)."
},
"distance": {
"type": "object",
"description": "km, earth_radii and angular_diameter_arcmin."
},
"position": {
"type": "object",
"description": "Geocentric apparent ecliptic_longitude and ecliptic_latitude, degrees."
},
"settings": {
"type": "object",
"description": "Every convention: frame, phase angle, illumination, age, lunation, distance."
},
"next_apogee": {
"type": [
"object",
"null"
],
"description": "{utc, timestamp, distance_km} of the next farthest point (null when it falls after 2199-12-30)."
},
"next_phases": {
"type": "array",
"description": "The next new, first quarter, full and last quarter Moons in time order: [{phase, utc, timestamp}]."
},
"next_perigee": {
"type": [
"object",
"null"
],
"description": "{utc, timestamp, distance_km} of the next closest approach (null when it falls after 2199-12-30)."
},
"previous_new_moon": {
"type": [
"object",
"null"
],
"description": "{utc, timestamp} of the last new Moon (null within a month of 1800-01-01)."
}
},
"description": "The calculation result."
},
"accepts": {
"type": "array",
"items": {
"type": "object"
},
"minItems": 1,
"description": "x402 offer only: the payment options (scheme, network, amount, asset, payTo, ...)."
},
"endpoint": {
"type": "string",
"description": "The REST route that computed it, e.g. 'astronomy/rise-set'."
},
"resource": {
"type": "object",
"description": "x402 offer only: the resource being paid for."
},
"extensions": {
"type": "object",
"description": "x402 offer only: protocol extensions (bazaar)."
},
"x402Version": {
"type": "integer",
"description": "x402 offer only: protocol version (2)."
}
}
},
"annotations": {
"title": "Moon phase, illumination, distance and next phases",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}{
"name": "day_summary",
"title": "Astronomical summary of the day for a place",
"description": "Today's sky for a place in one call: sunrise, sunset, twilight, golden and blue hour, the Moon's phase and moonrise, the planets visible tonight, the next lunations and the next eclipse. E.g. {date: '2026-08-10', latitude: 48.8566, longitude: 2.3522}. The daily sky block of a weather, calendar or outdoor app, in one request: the Sun (rise, solar noon, set, civil / nautical / astronomical dawn and dusk, day length, golden and blue hour), the Moon (phase, illuminated fraction, age, distance, moonrise, transit, moonset, the next principal phase), the planets observable that night (window, best time, altitude, azimuth, magnitude; brightest first), the lunations and planetary stations of the next 7 days, and the next solar or lunar eclipse anywhere on Earth. Local times with offset, UTC and unix timestamps; each block follows the conventions of its own route. Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.02 per call via REST POST https://astro-agent.dev/v1/astronomy/day (x402 or MPP); each client gets 1 free call on the $0.01-0.02 tools, this one included.",
"inputSchema": {
"type": "object",
"required": [
"date",
"latitude",
"longitude"
],
"properties": {
"date": {
"type": "string",
"description": "The local calendar day at the place, YYYY-MM-DD (1800-01-02..2199-12-30)."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Decimal degrees, north positive."
},
"timezone": {
"type": "string",
"description": "IANA zone for local times, e.g. 'Europe/Paris'. Optional: resolved from the coordinates (with its historical DST rules)."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Decimal degrees, east positive."
},
"elevation_m": {
"type": "number",
"default": 0,
"maximum": 9000,
"minimum": -500,
"description": "Height above the WGS84 ellipsoid, metres (no terrain or horizon dip is modelled)."
}
}
},
"outputSchema": {
"type": "object",
"anyOf": [
{
"required": [
"endpoint",
"result",
"meta"
]
},
{
"required": [
"x402Version",
"accepts"
]
}
],
"properties": {
"meta": {
"type": "object",
"required": [
"engine",
"deterministic",
"llm_used",
"input_sha256",
"result_sha256"
],
"properties": {
"frame": {
"type": "string",
"description": "Reference frame of the positions."
},
"engine": {
"type": "string",
"description": "Engine name and version."
},
"payment": {
"type": "object",
"description": "How this call was paid: protocol ('free' or 'none'), price and the free calls remaining."
},
"llm_used": {
"type": "boolean",
"description": "Always false: no language model is involved."
},
"ephemeris": {
"type": "string",
"description": "Ephemeris used (NASA/JPL DE440)."
},
"compute_ms": {
"type": "number",
"description": "Computation time in milliseconds."
},
"computed_at": {
"type": "string",
"description": "When it was computed (UTC, ISO 8601)."
},
"input_sha256": {
"type": "string",
"description": "SHA-256 of the canonical input."
},
"deterministic": {
"type": "boolean",
"description": "Always true: same input, same result."
},
"result_sha256": {
"type": "string",
"description": "SHA-256 of the canonical 'result'; check it with verify_result_hash."
},
"reproducibility": {
"type": "string",
"description": "How to reproduce and check this result."
},
"astronomy_library": {
"type": "string",
"description": "Astronomy library and version."
}
},
"description": "Provenance of the result."
},
"error": {
"type": "string",
"description": "x402 offer only: why payment is required."
},
"result": {
"type": "object",
"required": [
"subject",
"settings",
"sun",
"moon",
"planets_tonight",
"next_events",
"next_eclipse"
],
"properties": {
"sun": {
"type": "object",
"description": "sunrise, solar_noon, sunset, civil/nautical/astronomical dawn and dusk, day_length_minutes, golden_hour and blue_hour [{period, start, end}]."
},
"moon": {
"type": "object",
"description": "name, illuminated_fraction, age_days, waxing, distance_km, rise, transit, set, state and next_phase {phase, utc, local, timestamp} (null at the very end of the range)."
},
"subject": {
"type": "object",
"description": "The place, its time zone, the local date and the day's window in UTC."
},
"settings": {
"type": "object",
"description": "The conventions of each block (they follow astronomy/rise-set, astronomy/moon and astronomy/visibility)."
},
"next_events": {
"type": "array",
"description": "Lunations ({phase}) and planetary stations ({body, turns}) of the next 7 days, each with utc, local and timestamp."
},
"next_eclipse": {
"type": [
"object",
"null"
],
"description": "The next solar or lunar eclipse anywhere on Earth within a year: {kind, eclipse_type, utc, local, timestamp, note}, or null."
},
"planets_tonight": {
"type": "array",
"description": "The planets observable that night, brightest first: [{body, from, to, best: {utc, local, timestamp, altitude, azimuth, magnitude}, magnitude}]."
}
},
"description": "The calculation result."
},
"accepts": {
"type": "array",
"items": {
"type": "object"
},
"minItems": 1,
"description": "x402 offer only: the payment options (scheme, network, amount, asset, payTo, ...)."
},
"endpoint": {
"type": "string",
"description": "The REST route that computed it, e.g. 'astronomy/rise-set'."
},
"resource": {
"type": "object",
"description": "x402 offer only: the resource being paid for."
},
"extensions": {
"type": "object",
"description": "x402 offer only: protocol extensions (bazaar)."
},
"x402Version": {
"type": "integer",
"description": "x402 offer only: protocol version (2)."
}
}
},
"annotations": {
"title": "Astronomical summary of the day for a place",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}{
"name": "seasons",
"title": "Equinoxes, solstices, perihelion and day length over a year",
"description": "Equinoxes and solstices of a year, Earth's perihelion and aphelion, and optionally the Sun day by day (sunrise, sunset, day length, declination, equation of time) for a place. E.g. {year: 2026}. For calendars, almanacs, education and solar apps: the March and September equinoxes and the June and December solstices (UTC, and local with a place), Earth's perihelion and aphelion with their distances, and with daily=true a row per day: solar noon, the Sun's apparent declination, the equation of time and, for a place, sunrise, sunset and day length, plus the longest and shortest days. Matches the published 2026 times to the minute. Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.01 per call via REST POST https://astro-agent.dev/v1/astronomy/seasons (x402 or MPP); each client gets 1 free call on the $0.01-0.02 tools, this one included.",
"inputSchema": {
"type": "object",
"required": [
"year"
],
"properties": {
"year": {
"type": "integer",
"maximum": 2199,
"minimum": 1800,
"description": "Calendar year."
},
"daily": {
"type": "boolean",
"default": false,
"description": "Add one row per day: solar noon, the Sun's declination, the equation of time and, with a place, sunrise, sunset and day length."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Optional: local times, and with daily=true the day-by-day sunrise, sunset and day length at this place."
},
"timezone": {
"type": "string",
"description": "IANA zone for local times, e.g. 'Europe/Paris'. Optional: resolved from the coordinates (with its historical DST rules)."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Optional, with latitude."
},
"elevation_m": {
"type": "number",
"default": 0,
"maximum": 9000,
"minimum": -500,
"description": "Height above the WGS84 ellipsoid, metres (no terrain or horizon dip is modelled)."
}
}
},
"outputSchema": {
"type": "object",
"anyOf": [
{
"required": [
"endpoint",
"result",
"meta"
]
},
{
"required": [
"x402Version",
"accepts"
]
}
],
"properties": {
"meta": {
"type": "object",
"required": [
"engine",
"deterministic",
"llm_used",
"input_sha256",
"result_sha256"
],
"properties": {
"frame": {
"type": "string",
"description": "Reference frame of the positions."
},
"engine": {
"type": "string",
"description": "Engine name and version."
},
"payment": {
"type": "object",
"description": "How this call was paid: protocol ('free' or 'none'), price and the free calls remaining."
},
"llm_used": {
"type": "boolean",
"description": "Always false: no language model is involved."
},
"ephemeris": {
"type": "string",
"description": "Ephemeris used (NASA/JPL DE440)."
},
"compute_ms": {
"type": "number",
"description": "Computation time in milliseconds."
},
"computed_at": {
"type": "string",
"description": "When it was computed (UTC, ISO 8601)."
},
"input_sha256": {
"type": "string",
"description": "SHA-256 of the canonical input."
},
"deterministic": {
"type": "boolean",
"description": "Always true: same input, same result."
},
"result_sha256": {
"type": "string",
"description": "SHA-256 of the canonical 'result'; check it with verify_result_hash."
},
"reproducibility": {
"type": "string",
"description": "How to reproduce and check this result."
},
"astronomy_library": {
"type": "string",
"description": "Astronomy library and version."
}
},
"description": "Provenance of the result."
},
"error": {
"type": "string",
"description": "x402 offer only: why payment is required."
},
"result": {
"type": "object",
"required": [
"subject",
"settings",
"seasons",
"earth_orbit"
],
"properties": {
"daily": {
"type": "array",
"description": "With daily=true: one row per local day: date, solar_noon, sun_declination, equation_of_time_minutes and, with a place, sunrise, sunset, day_length_minutes (null when the Sun does not rise or set)."
},
"seasons": {
"type": "array",
"description": "[{event: march_equinox | june_solstice | september_equinox | december_solstice, utc, timestamp, local (with a place)}]."
},
"subject": {
"type": "object",
"description": "The year and, with a place, its location and time zone."
},
"summary": {
"type": "object",
"description": "With daily=true and a place: longest_day, shortest_day and their lengths in minutes."
},
"settings": {
"type": "object",
"description": "Whether daily rows are included, and every convention."
},
"earth_orbit": {
"type": "object",
"description": "perihelion and aphelion lists: [{utc, timestamp, local, distance_km, distance_au}]."
}
},
"description": "The calculation result."
},
"accepts": {
"type": "array",
"items": {
"type": "object"
},
"minItems": 1,
"description": "x402 offer only: the payment options (scheme, network, amount, asset, payTo, ...)."
},
"endpoint": {
"type": "string",
"description": "The REST route that computed it, e.g. 'astronomy/rise-set'."
},
"resource": {
"type": "object",
"description": "x402 offer only: the resource being paid for."
},
"extensions": {
"type": "object",
"description": "x402 offer only: protocol extensions (bazaar)."
},
"x402Version": {
"type": "integer",
"description": "x402 offer only: protocol version (2)."
}
}
},
"annotations": {
"title": "Equinoxes, solstices, perihelion and day length over a year",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}{
"name": "convert_coordinates",
"title": "Coordinate conversion between sky frames",
"description": "Convert sky coordinates between equatorial (J2000, of date), ecliptic, galactic and horizontal (alt-az) frames. E.g. {frame: 'equatorial_j2000', coordinates: {ra_hours: 6.7525, dec: -16.7161}, datetime: '2026-06-21T21:00:00Z', latitude: 48.8566, longitude: 2.3522}. For catalogues, planetarium and telescope software: give a direction in one frame and get it in all the others: equatorial J2000 (ICRS) and of date, ecliptic J2000 and of date, galactic, and horizontal (altitude, azimuth) when a datetime and a place are given. Geometric frame rotations of a direction (no aberration or refraction is added: use astronomy/altaz for where a body appears). Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.01 per call via REST POST https://astro-agent.dev/v1/astronomy/convert (x402 or MPP); each client gets 1 free call on the $0.01-0.02 tools, this one included.",
"inputSchema": {
"type": "object",
"required": [
"frame",
"coordinates"
],
"properties": {
"frame": {
"enum": [
"equatorial_j2000",
"equatorial_of_date",
"ecliptic_j2000",
"ecliptic_of_date",
"galactic",
"horizontal"
],
"type": "string",
"description": "The frame of the input coordinates."
},
"datetime": {
"type": "string",
"description": "Needed for the of-date and horizontal frames (UTC, offset, or local time with latitude/longitude)."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Observer latitude, for the horizontal frame."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Observer longitude, for the horizontal frame."
},
"coordinates": {
"type": "object",
"properties": {
"dec": {
"type": "number",
"description": "Equatorial frames: declination, degrees."
},
"azimuth": {
"type": "number",
"description": "Horizontal frame: azimuth from north, degrees 0-360."
},
"altitude": {
"type": "number",
"description": "Horizontal frame: altitude, degrees."
},
"latitude": {
"type": "number",
"description": "Ecliptic and galactic frames: latitude, degrees."
},
"ra_hours": {
"type": "number",
"description": "Equatorial frames: right ascension, hours 0-24."
},
"longitude": {
"type": "number",
"description": "Ecliptic and galactic frames: longitude, degrees 0-360."
}
},
"description": "The direction, with the two fields of its frame."
}
}
},
"outputSchema": {
"type": "object",
"anyOf": [
{
"required": [
"endpoint",
"result",
"meta"
]
},
{
"required": [
"x402Version",
"accepts"
]
}
],
"properties": {
"meta": {
"type": "object",
"required": [
"engine",
"deterministic",
"llm_used",
"input_sha256",
"result_sha256"
],
"properties": {
"frame": {
"type": "string",
"description": "Reference frame of the positions."
},
"engine": {
"type": "string",
"description": "Engine name and version."
},
"payment": {
"type": "object",
"description": "How this call was paid: protocol ('free' or 'none'), price and the free calls remaining."
},
"llm_used": {
"type": "boolean",
"description": "Always false: no language model is involved."
},
"ephemeris": {
"type": "string",
"description": "Ephemeris used (NASA/JPL DE440)."
},
"compute_ms": {
"type": "number",
"description": "Computation time in milliseconds."
},
"computed_at": {
"type": "string",
"description": "When it was computed (UTC, ISO 8601)."
},
"input_sha256": {
"type": "string",
"description": "SHA-256 of the canonical input."
},
"deterministic": {
"type": "boolean",
"description": "Always true: same input, same result."
},
"result_sha256": {
"type": "string",
"description": "SHA-256 of the canonical 'result'; check it with verify_result_hash."
},
"reproducibility": {
"type": "string",
"description": "How to reproduce and check this result."
},
"astronomy_library": {
"type": "string",
"description": "Astronomy library and version."
}
},
"description": "Provenance of the result."
},
"error": {
"type": "string",
"description": "x402 offer only: why payment is required."
},
"result": {
"type": "object",
"required": [
"subject",
"settings",
"frames"
],
"properties": {
"frames": {
"type": "object",
"description": "equatorial_j2000 {ra_hours, dec}, ecliptic_j2000 and galactic {longitude, latitude}; with a moment, equatorial_of_date and ecliptic_of_date; with a moment and a place, horizontal {altitude, azimuth}."
},
"subject": {
"type": "object",
"description": "The input frame and coordinates, and the resolved moment when given."
},
"settings": {
"type": "object",
"description": "Every convention: the frames and what the rotation does not include."
}
},
"description": "The calculation result."
},
"accepts": {
"type": "array",
"items": {
"type": "object"
},
"minItems": 1,
"description": "x402 offer only: the payment options (scheme, network, amount, asset, payTo, ...)."
},
"endpoint": {
"type": "string",
"description": "The REST route that computed it, e.g. 'astronomy/rise-set'."
},
"resource": {
"type": "object",
"description": "x402 offer only: the resource being paid for."
},
"extensions": {
"type": "object",
"description": "x402 offer only: protocol extensions (bazaar)."
},
"x402Version": {
"type": "integer",
"description": "x402 offer only: protocol version (2)."
}
}
},
"annotations": {
"title": "Coordinate conversion between sky frames",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}| number |
| Decimal degrees, east positive. |
| elevation_m | number | Height above the WGS84 ellipsoid, metres (no terrain or horizon dip is modelled). |
{
"name": "local_eclipse",
"title": "Local circumstances of solar and lunar eclipses",
"description": "Solar and lunar eclipses seen from a place: local type, contact times (C1-C4, P1-P4, U1-U4), magnitude, obscuration, duration of totality and the Sun's or Moon's altitude. E.g. {start: '2026-08-01', end: '2026-08-31', latitude: 39.47, longitude: -0.38}. For eclipse chasers, planetariums, schools and travel apps: solar eclipses from the place's own viewpoint (local type: total, annular, partial or none; contacts C1, C2, maximum, C3, C4 with the Sun's altitude and azimuth; magnitude, obscuration, duration, duration of totality or annularity) and lunar eclipses (penumbral and umbral contacts P1, U1, U2, maximum, U3, U4, P4 with the Moon's altitude, umbral and penumbral magnitude, durations), each marked visible when the body is above the horizon. Matches NASA's predictions to a few seconds (2024-04-08 at Dallas, 2025-03-14 lunar eclipse). Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.10 per call via REST POST https://astro-agent.dev/v1/astronomy/eclipse-local (x402 or MPP); always paid, never a free call.",
"inputSchema": {
"type": "object",
"required": [
"start",
"end",
"latitude",
"longitude"
],
"properties": {
"end": {
"type": "string",
"description": "Last UTC date, YYYY-MM-DD, at most 366 days after start."
},
"kinds": {
"type": "array",
"items": {
"enum": [
"solar",
"lunar"
],
"type": "string"
},
"description": "Eclipse kinds to return. Default: both."
},
"start": {
"type": "string",
"description": "First UTC date, YYYY-MM-DD (1800-01-08..2199-12-30)."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Decimal degrees, north positive."
},
"timezone": {
"type": "string",
"description": "IANA zone for local times, e.g. 'Europe/Paris'. Optional: resolved from the coordinates (with its historical DST rules)."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Decimal degrees, east positive."
},
"elevation_m": {
"type": "number",
"default": 0,
"maximum": 9000,
"minimum": -500,
"description": "Height above the WGS84 ellipsoid, metres (no terrain or horizon dip is modelled)."
}
}
},
"outputSchema": {
"type": "object",
"anyOf": [
{
"required": [
"endpoint",
"result",
"meta"
]
},
{
"required": [
"x402Version",
"accepts"
]
}
],
"properties": {
"meta": {
"type": "object",
"required": [
"engine",
"deterministic",
"llm_used",
"input_sha256",
"result_sha256"
],
"properties": {
"frame": {
"type": "string",
"description": "Reference frame of the positions."
},
"engine": {
"type": "string",
"description": "Engine name and version."
},
"payment": {
"type": "object",
"description": "How this call was paid: protocol ('free' or 'none'), price and the free calls remaining."
},
"llm_used": {
"type": "boolean",
"description": "Always false: no language model is involved."
},
"ephemeris": {
"type": "string",
"description": "Ephemeris used (NASA/JPL DE440)."
},
"compute_ms": {
"type": "number",
"description": "Computation time in milliseconds."
},
"computed_at": {
"type": "string",
"description": "When it was computed (UTC, ISO 8601)."
},
"input_sha256": {
"type": "string",
"description": "SHA-256 of the canonical input."
},
"deterministic": {
"type": "boolean",
"description": "Always true: same input, same result."
},
"result_sha256": {
"type": "string",
"description": "SHA-256 of the canonical 'result'; check it with verify_result_hash."
},
"reproducibility": {
"type": "string",
"description": "How to reproduce and check this result."
},
"astronomy_library": {
"type": "string",
"description": "Astronomy library and version."
}
},
"description": "Provenance of the result."
},
"error": {
"type": "string",
"description": "x402 offer only: why payment is required."
},
"result": {
"type": "object",
"required": [
"subject",
"settings",
"eclipses",
"counts"
],
"properties": {
"counts": {
"type": "object",
"description": "eclipses, and visible: those with the Sun or Moon above the horizon at a contact or at maximum."
},
"subject": {
"type": "object",
"description": "The place and its time zone."
},
"eclipses": {
"type": "array",
"description": "One row per eclipse: kind, global_type, greatest_eclipse_utc, key, visible, and local_type (solar), magnitude, obscuration, umbral/penumbral magnitude (lunar), contacts [{contact, utc, local, timestamp, and the Sun's or Moon's altitude, azimuth, above_horizon}], durations and visible."
},
"settings": {
"type": "object",
"description": "start, end, kinds and every convention (discs, contacts, magnitude, visibility)."
}
},
"description": "The calculation result."
},
"accepts": {
"type": "array",
"items": {
"type": "object"
},
"minItems": 1,
"description": "x402 offer only: the payment options (scheme, network, amount, asset, payTo, ...)."
},
"endpoint": {
"type": "string",
"description": "The REST route that computed it, e.g. 'astronomy/rise-set'."
},
"resource": {
"type": "object",
"description": "x402 offer only: the resource being paid for."
},
"extensions": {
"type": "object",
"description": "x402 offer only: protocol extensions (bazaar)."
},
"x402Version": {
"type": "integer",
"description": "x402 offer only: protocol version (2)."
}
}
},
"annotations": {
"title": "Local circumstances of solar and lunar eclipses",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}| Height above the WGS84 ellipsoid, metres (no terrain or horizon dip is modelled). |
{
"name": "solunar_periods",
"title": "Solunar periods: lunar transits, moonrise and moonset",
"description": "Solunar periods for a place and day: major periods around the Moon's upper and lower transits, minor periods around moonrise and moonset, in local time. E.g. {date: '2026-06-21', latitude: 48.8566, longitude: 2.3522}. For fishing, hunting and outdoor apps that use the solunar timing convention: for one local day at a place, each major period (centred on the Moon's upper transit overhead and lower transit underfoot, 2 h by default) and minor period (centred on moonrise and moonset, 1 h by default) with its start, centre and end in local time, the Moon's altitude at its transits and its phase. The events are exact (astronomy/rise-set conventions); the windows are the convention's, adjustable. No rating attached. Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.01 per call via REST POST https://astro-agent.dev/v1/astronomy/solunar (x402 or MPP); each client gets 1 free call on the $0.01-0.02 tools, this one included.",
"inputSchema": {
"type": "object",
"required": [
"date",
"latitude",
"longitude"
],
"properties": {
"date": {
"type": "string",
"description": "The local calendar day at the place, YYYY-MM-DD (1800-01-02..2199-12-30)."
},
"options": {
"type": "object",
"properties": {
"major_minutes": {
"type": "integer",
"default": 120,
"maximum": 360,
"minimum": 10,
"description": "Length of a major period, centred on a lunar transit."
},
"minor_minutes": {
"type": "integer",
"default": 60,
"maximum": 360,
"minimum": 10,
"description": "Length of a minor period, centred on moonrise or moonset."
}
},
"description": "Window lengths."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Decimal degrees, north positive."
},
"timezone": {
"type": "string",
"description": "IANA zone for local times, e.g. 'Europe/Paris'. Optional: resolved from the coordinates (with its historical DST rules)."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Decimal degrees, east positive."
},
"elevation_m": {
"type": "number",
"default": 0,
"maximum": 9000,
"minimum": -500,
"description": "Height above the WGS84 ellipsoid, metres (no terrain or horizon dip is modelled)."
}
}
},
"outputSchema": {
"type": "object",
"anyOf": [
{
"required": [
"endpoint",
"result",
"meta"
]
},
{
"required": [
"x402Version",
"accepts"
]
}
],
"properties": {
"meta": {
"type": "object",
"required": [
"engine",
"deterministic",
"llm_used",
"input_sha256",
"result_sha256"
],
"properties": {
"frame": {
"type": "string",
"description": "Reference frame of the positions."
},
"engine": {
"type": "string",
"description": "Engine name and version."
},
"payment": {
"type": "object",
"description": "How this call was paid: protocol ('free' or 'none'), price and the free calls remaining."
},
"llm_used": {
"type": "boolean",
"description": "Always false: no language model is involved."
},
"ephemeris": {
"type": "string",
"description": "Ephemeris used (NASA/JPL DE440)."
},
"compute_ms": {
"type": "number",
"description": "Computation time in milliseconds."
},
"computed_at": {
"type": "string",
"description": "When it was computed (UTC, ISO 8601)."
},
"input_sha256": {
"type": "string",
"description": "SHA-256 of the canonical input."
},
"deterministic": {
"type": "boolean",
"description": "Always true: same input, same result."
},
"result_sha256": {
"type": "string",
"description": "SHA-256 of the canonical 'result'; check it with verify_result_hash."
},
"reproducibility": {
"type": "string",
"description": "How to reproduce and check this result."
},
"astronomy_library": {
"type": "string",
"description": "Astronomy library and version."
}
},
"description": "Provenance of the result."
},
"error": {
"type": "string",
"description": "x402 offer only: why payment is required."
},
"result": {
"type": "object",
"required": [
"subject",
"settings",
"moon",
"periods",
"counts"
],
"properties": {
"moon": {
"type": "object",
"description": "The Moon's phase at mid-day: name, illuminated_fraction, age_days."
},
"counts": {
"type": "object",
"description": "Number of major and minor periods that day."
},
"periods": {
"type": "array",
"description": "In time order: {type: major | minor, event: upper_transit | lower_transit | moonrise | moonset, centre, start, end (each {utc, local, timestamp}), moon_altitude (transits)}."
},
"subject": {
"type": "object",
"description": "The place, its time zone, the local date and the day's window in UTC."
},
"settings": {
"type": "object",
"description": "major_minutes, minor_minutes and the convention."
}
},
"description": "The calculation result."
},
"accepts": {
"type": "array",
"items": {
"type": "object"
},
"minItems": 1,
"description": "x402 offer only: the payment options (scheme, network, amount, asset, payTo, ...)."
},
"endpoint": {
"type": "string",
"description": "The REST route that computed it, e.g. 'astronomy/rise-set'."
},
"resource": {
"type": "object",
"description": "x402 offer only: the resource being paid for."
},
"extensions": {
"type": "object",
"description": "x402 offer only: protocol extensions (bazaar)."
},
"x402Version": {
"type": "integer",
"description": "x402 offer only: protocol version (2)."
}
}
},
"annotations": {
"title": "Solunar periods: lunar transits, moonrise and moonset",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}| longitude | number | Decimal degrees, east positive. |
| time_basis | string | What the given clock time is: civil wall-clock (default), UTC, Local Mean Time, or true (apparent) solar time. |
| ambiguous_time | string | Which occurrence to use when a local time happens twice (DST fall-back). |
{
"name": "body_positions",
"title": "Planetary positions for any date (ephemeris)",
"description": "Planetary positions and ephemeris API (NASA/JPL DE440): the ecliptic longitude, latitude, speed, retrograde flag and distance of the Sun, Moon, planets and lunar nodes at any moment 1800-2200, geocentric or heliocentric, ecliptic or equatorial (right ascension, declination). E.g. {datetime: '2026-10-01T12:00:00Z'}. Geocentric apparent positions from NASA/JPL DE440 (true ecliptic and equinox of date, IAU 2006/2000A), with the Moon's ascending and descending nodes and its mean apogee. Location is optional (only used to interpret a local time). Options: 'heliocentric' perspective (seen from the Sun) and 'equatorial' coordinates (right ascension, declination, and whether |declination| exceeds the obliquity). Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.01 per call via REST POST https://astro-agent.dev/v1/astronomy/positions (x402 or MPP); each client gets 1 free call on the $0.01-0.02 tools, this one included.",
"inputSchema": {
"type": "object",
"required": [],
"properties": {
"date": {
"type": "string",
"description": "YYYY-MM-DD (use with 'time' instead of 'datetime')."
},
"time": {
"type": "string",
"description": "HH:MM or HH:MM:SS, 24 h. Omit if unknown (computed at 12:00 with a TIME_UNKNOWN warning)."
},
"options": {
"type": "object",
"properties": {
"bodies": {
"oneOf": [
{
"enum": [
"all"
],
"type": "string"
},
{
"type": "array",
"items": {
"enum": [
"sun",
"moon",
"mercury",
"venus",
"mars",
"jupiter",
"saturn",
"uranus",
"neptune",
"pluto",
"lunar_node_true",
"lunar_node_true_descending",
"lunar_node_mean",
"lunar_apogee_mean"
],
"type": "string"
}
}
],
"description": "'all' or a list from ['sun', 'moon', 'mercury', 'venus', 'mars', 'jupiter', 'saturn', 'uranus', 'neptune', 'pluto', 'lunar_node_true', 'lunar_node_true_descending', 'lunar_node_mean', 'lunar_apogee_mean']. Default: the Sun, the Moon, Mercury..Pluto, the Moon's true ascending node, its descending node and its mean apogee."
},
"coordinates": {
"enum": [
"ecliptic",
"equatorial"
],
"type": "string",
"default": "ecliptic",
"description": "'ecliptic' (default: longitude/latitude) or 'equatorial': also each body's right ascension, declination, their daily speeds and whether |declination| exceeds the obliquity of the ecliptic."
},
"perspective": {
"enum": [
"geocentric",
"heliocentric"
],
"type": "string",
"default": "geocentric",
"description": "'geocentric' (default) or 'heliocentric' (geometric, seen from the Sun: the Earth instead of the Sun and the Moon, no lunar points)."
}
},
"description": "Optional.",
"additionalProperties": false
},
"datetime": {
"type": "string",
"examples": [
"1990-05-15T14:30"
],
"description": "Local civil date-time, ISO 8601: '1990-05-15T14:30' (local clock time at the place) or with an explicit offset '1990-05-15T14:30:00+02:00'. Alternative: 'date' + 'time'."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Decimal degrees, north positive."
},
"timezone": {
"type": "string",
"description": "IANA zone, e.g. 'Asia/Kolkata'. Optional: resolved from the coordinates, with the historical offset (DST, Local Mean Time) of that date."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Decimal degrees, east positive."
},
"time_basis": {
"enum": [
"civil",
"utc",
"lmt",
"true_solar"
],
"type": "string",
"default": "civil",
"description": "What the given clock time is: civil wall-clock (default), UTC, Local Mean Time, or true (apparent) solar time."
},
"ambiguous_time": {
"enum": [
"earlier",
"later"
],
"type": "string",
"default": "earlier",
"description": "Which occurrence to use when a local time happens twice (DST fall-back)."
}
}
},
"outputSchema": {
"type": "object",
"anyOf": [
{
"required": [
"endpoint",
"result",
"meta"
]
},
{
"required": [
"x402Version",
"accepts"
]
}
],
"properties": {
"meta": {
"type": "object",
"required": [
"engine",
"deterministic",
"llm_used",
"input_sha256",
"result_sha256"
],
"properties": {
"frame": {
"type": "string",
"description": "Reference frame of the positions."
},
"engine": {
"type": "string",
"description": "Engine name and version."
},
"payment": {
"type": "object",
"description": "How this call was paid: protocol ('free' or 'none'), price and the free calls remaining."
},
"llm_used": {
"type": "boolean",
"description": "Always false: no language model is involved."
},
"ephemeris": {
"type": "string",
"description": "Ephemeris used (NASA/JPL DE440)."
},
"compute_ms": {
"type": "number",
"description": "Computation time in milliseconds."
},
"computed_at": {
"type": "string",
"description": "When it was computed (UTC, ISO 8601)."
},
"input_sha256": {
"type": "string",
"description": "SHA-256 of the canonical input."
},
"deterministic": {
"type": "boolean",
"description": "Always true: same input, same result."
},
"result_sha256": {
"type": "string",
"description": "SHA-256 of the canonical 'result'; check it with verify_result_hash."
},
"reproducibility": {
"type": "string",
"description": "How to reproduce and check this result."
},
"astronomy_library": {
"type": "string",
"description": "Astronomy library and version."
}
},
"description": "Provenance of the result."
},
"error": {
"type": "string",
"description": "x402 offer only: why payment is required."
},
"result": {
"type": "object",
"required": [
"subject",
"settings",
"points"
],
"properties": {
"points": {
"type": "array",
"description": "One entry per body (Sun to Pluto, the Moon's ascending and descending nodes, its mean apogee): ecliptic longitude and latitude, daily speed, retrograde flag, distance in AU; with equatorial coordinates, right ascension, declination and whether |declination| exceeds the obliquity."
},
"subject": {
"type": "object",
"description": "The resolved input: 'time' (local input, time zone and historical UTC offset, UT, Julian days, Delta T) and, when given, 'location' (latitude, longitude)."
},
"settings": {
"type": "object",
"description": "Settings applied: the longitude reference (true equinox of date), perspective, coordinates."
}
},
"description": "The calculation result."
},
"accepts": {
"type": "array",
"items": {
"type": "object"
},
"minItems": 1,
"description": "x402 offer only: the payment options (scheme, network, amount, asset, payTo, ...)."
},
"endpoint": {
"type": "string",
"description": "The REST route that computed it, e.g. 'astronomy/rise-set'."
},
"resource": {
"type": "object",
"description": "x402 offer only: the resource being paid for."
},
"extensions": {
"type": "object",
"description": "x402 offer only: protocol extensions (bazaar)."
},
"x402Version": {
"type": "integer",
"description": "x402 offer only: protocol version (2)."
}
}
},
"annotations": {
"title": "Planetary positions for any date (ephemeris)",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}| Decimal degrees, east positive. |
| time_basis | string | What the given clock time is: civil wall-clock (default), UTC, Local Mean Time, or true (apparent) solar time. |
| ambiguous_time | string | Which occurrence to use when a local time happens twice (DST fall-back). |
{
"name": "sky_now",
"title": "The sky now: positions, Moon phase, next events",
"description": "The sky now (no location needed): planet positions, retrograde planets and the Moon phase, plus the exact UTC minute of the next stations, lunations and separations. E.g. {datetime: '2026-10-01T00:00Z', days: 30}. One call for 'what is happening in the sky': positions, retrograde planets, the Moon's phase, and the events of the next days (1-90): stations, lunations, separations of 0, 60, 90, 120 and 180 degrees, and ecliptic longitudes crossing multiples of 30 degrees, each to the minute (UTC). Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.01 per call via REST POST https://astro-agent.dev/v1/astronomy/sky (x402 or MPP); each client gets 1 free call on the $0.01-0.02 tools, this one included.",
"inputSchema": {
"type": "object",
"required": [],
"properties": {
"date": {
"type": "string",
"description": "YYYY-MM-DD (use with 'time' instead of 'datetime')."
},
"days": {
"type": "integer",
"default": 30,
"maximum": 90,
"minimum": 1,
"description": "How many days ahead to list events. Example: 30."
},
"time": {
"type": "string",
"description": "HH:MM or HH:MM:SS, 24 h. Omit if unknown (computed at 12:00 with a TIME_UNKNOWN warning)."
},
"datetime": {
"type": "string",
"examples": [
"1990-05-15T14:30"
],
"description": "Local civil date-time, ISO 8601: '1990-05-15T14:30' (local clock time at the place) or with an explicit offset '1990-05-15T14:30:00+02:00'. Alternative: 'date' + 'time'."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Decimal degrees, north positive."
},
"timezone": {
"type": "string",
"description": "IANA zone, e.g. 'Asia/Kolkata'. Optional: resolved from the coordinates, with the historical offset (DST, Local Mean Time) of that date."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Decimal degrees, east positive."
},
"time_basis": {
"enum": [
"civil",
"utc",
"lmt",
"true_solar"
],
"type": "string",
"default": "civil",
"description": "What the given clock time is: civil wall-clock (default), UTC, Local Mean Time, or true (apparent) solar time."
},
"ambiguous_time": {
"enum": [
"earlier",
"later"
],
"type": "string",
"default": "earlier",
"description": "Which occurrence to use when a local time happens twice (DST fall-back)."
}
}
},
"outputSchema": {
"type": "object",
"anyOf": [
{
"required": [
"endpoint",
"result",
"meta"
]
},
{
"required": [
"x402Version",
"accepts"
]
}
],
"properties": {
"meta": {
"type": "object",
"required": [
"engine",
"deterministic",
"llm_used",
"input_sha256",
"result_sha256"
],
"properties": {
"frame": {
"type": "string",
"description": "Reference frame of the positions."
},
"engine": {
"type": "string",
"description": "Engine name and version."
},
"payment": {
"type": "object",
"description": "How this call was paid: protocol ('free' or 'none'), price and the free calls remaining."
},
"llm_used": {
"type": "boolean",
"description": "Always false: no language model is involved."
},
"ephemeris": {
"type": "string",
"description": "Ephemeris used (NASA/JPL DE440)."
},
"compute_ms": {
"type": "number",
"description": "Computation time in milliseconds."
},
"computed_at": {
"type": "string",
"description": "When it was computed (UTC, ISO 8601)."
},
"input_sha256": {
"type": "string",
"description": "SHA-256 of the canonical input."
},
"deterministic": {
"type": "boolean",
"description": "Always true: same input, same result."
},
"result_sha256": {
"type": "string",
"description": "SHA-256 of the canonical 'result'; check it with verify_result_hash."
},
"reproducibility": {
"type": "string",
"description": "How to reproduce and check this result."
},
"astronomy_library": {
"type": "string",
"description": "Astronomy library and version."
}
},
"description": "Provenance of the result."
},
"error": {
"type": "string",
"description": "x402 offer only: why payment is required."
},
"result": {
"type": "object",
"required": [
"subject",
"settings",
"now",
"events",
"counts"
],
"properties": {
"now": {
"type": "object",
"description": "The sky at the moment: 'points' (positions, speeds, retrograde flags), 'retrograde' (bodies retrograde now) and 'moon' (elongation, phase name, illumination, waxing)."
},
"counts": {
"type": "object",
"description": "Number of events of each type."
},
"events": {
"type": "array",
"description": "Events in time order, each with 'type' (eclipse, lunation, station, separation, longitude_crossing, declination, declination_beyond_obliquity), its details, 'exact_utc'."
},
"subject": {
"type": "object",
"description": "The resolved input: 'time' (local input, time zone and historical UTC offset, UT, Julian days, Delta T) and, when given, 'location' (latitude, longitude)."
},
"settings": {
"type": "object",
"description": "Settings applied: days ahead, the bodies, the separation angles searched, the longitude reference and the precision of event times."
},
"warnings": {
"type": "array",
"description": "Notes on the input or the calculation (for example an assumed local noon when only a date is given). Present only when there is something to say."
}
},
"description": "The calculation result."
},
"accepts": {
"type": "array",
"items": {
"type": "object"
},
"minItems": 1,
"description": "x402 offer only: the payment options (scheme, network, amount, asset, payTo, ...)."
},
"endpoint": {
"type": "string",
"description": "The REST route that computed it, e.g. 'astronomy/rise-set'."
},
"resource": {
"type": "object",
"description": "x402 offer only: the resource being paid for."
},
"extensions": {
"type": "object",
"description": "x402 offer only: protocol extensions (bazaar)."
},
"x402Version": {
"type": "integer",
"description": "x402 offer only: protocol version (2)."
}
}
},
"annotations": {
"title": "The sky now: positions, Moon phase, next events",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}| number |
| Decimal degrees, east positive. |
| longitudes | object | Optional {body: degrees} or {body: {longitude, speed, declination?, declination_speed?}}; when given, no ephemeris is used. |
| time_basis | string | What the given clock time is: civil wall-clock (default), UTC, Local Mean Time, or true (apparent) solar time. |
| ambiguous_time | string | Which occurrence to use when a local time happens twice (DST fall-back). |
{
"name": "angular_separations",
"title": "Angular separations between bodies",
"description": "Angular separations between planets at a moment, or between longitudes you supply: the pairs near 0, 60, 90, 120 or 180 degrees (or any angle you choose) with the deviation, approaching or receding; optionally equal and opposite declinations. E.g. {longitudes: {sun: 54.4, moon: 297.4}}. For a moment (computed from DE440) or for longitudes you supply: every pair of bodies at a chosen separation angle, with its deviation from the exact angle, the tolerance applied, and whether the bodies are approaching or receding from it. Option 'declination': pairs with equal or opposite declinations. Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.02 per call via REST POST https://astro-agent.dev/v1/astronomy/angles (x402 or MPP); each client gets 1 free call on the $0.01-0.02 tools, this one included.",
"inputSchema": {
"type": "object",
"properties": {
"date": {
"type": "string",
"description": "YYYY-MM-DD (use with 'time' instead of 'datetime')."
},
"time": {
"type": "string",
"description": "HH:MM or HH:MM:SS, 24 h. Omit if unknown (computed at 12:00 with a TIME_UNKNOWN warning)."
},
"options": {
"type": "object",
"properties": {
"angles": {
"oneOf": [
{
"enum": [
"all"
],
"type": "string"
},
{
"type": "array",
"items": {
"enum": [
0,
30,
45,
60,
72,
90,
120,
135,
144,
150,
180
],
"type": "integer"
}
}
],
"description": "Separation angles in degrees, 'all' or a list from [0, 30, 45, 60, 72, 90, 120, 135, 144, 150, 180]. Default: [0, 60, 90, 120, 180]."
},
"bodies": {
"oneOf": [
{
"enum": [
"all"
],
"type": "string"
},
{
"type": "array",
"items": {
"enum": [
"sun",
"moon",
"mercury",
"venus",
"mars",
"jupiter",
"saturn",
"uranus",
"neptune",
"pluto",
"lunar_node_true",
"lunar_node_true_descending",
"lunar_node_mean",
"lunar_apogee_mean"
],
"type": "string"
}
}
],
"description": "'all' or a list from ['sun', 'moon', 'mercury', 'venus', 'mars', 'jupiter', 'saturn', 'uranus', 'neptune', 'pluto', 'lunar_node_true', 'lunar_node_true_descending', 'lunar_node_mean', 'lunar_apogee_mean']. Default: the Sun, the Moon, Mercury..Pluto, the Moon's true ascending node, its descending node and its mean apogee."
},
"tolerances": {
"type": "object",
"description": "Tolerance in degrees per angle, e.g. {\"90\": 6}. Defaults: 0 and 180: 8; 90 and 120: 7; 60: 5; the others: 2.",
"additionalProperties": {
"type": "number",
"maximum": 15,
"minimum": 0
}
},
"declination": {
"type": "boolean",
"default": false,
"description": "Also return the declinations and the pairs with equal or opposite declinations."
},
"declination_tolerance": {
"type": "number",
"default": 1,
"maximum": 3,
"minimum": 0,
"description": "Tolerance in degrees for equal / opposite declinations."
},
"sun_moon_tolerance_bonus": {
"type": "number",
"default": 2,
"maximum": 5,
"minimum": 0,
"description": "Extra tolerance in degrees when either body is the Sun or the Moon."
}
},
"description": "Optional.",
"additionalProperties": false
},
"datetime": {
"type": "string",
"examples": [
"1990-05-15T14:30"
],
"description": "Local civil date-time, ISO 8601: '1990-05-15T14:30' (local clock time at the place) or with an explicit offset '1990-05-15T14:30:00+02:00'. Alternative: 'date' + 'time'."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Decimal degrees, north positive."
},
"timezone": {
"type": "string",
"description": "IANA zone, e.g. 'Asia/Kolkata'. Optional: resolved from the coordinates, with the historical offset (DST, Local Mean Time) of that date."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Decimal degrees, east positive."
},
"longitudes": {
"type": "object",
"description": "Optional {body: degrees} or {body: {longitude, speed, declination?, declination_speed?}}; when given, no ephemeris is used.",
"additionalProperties": true
},
"time_basis": {
"enum": [
"civil",
"utc",
"lmt",
"true_solar"
],
"type": "string",
"default": "civil",
"description": "What the given clock time is: civil wall-clock (default), UTC, Local Mean Time, or true (apparent) solar time."
},
"ambiguous_time": {
"enum": [
"earlier",
"later"
],
"type": "string",
"default": "earlier",
"description": "Which occurrence to use when a local time happens twice (DST fall-back)."
}
}
},
"outputSchema": {
"type": "object",
"anyOf": [
{
"required": [
"endpoint",
"result",
"meta"
]
},
{
"required": [
"x402Version",
"accepts"
]
}
],
"properties": {
"meta": {
"type": "object",
"required": [
"engine",
"deterministic",
"llm_used",
"input_sha256",
"result_sha256"
],
"properties": {
"frame": {
"type": "string",
"description": "Reference frame of the positions."
},
"engine": {
"type": "string",
"description": "Engine name and version."
},
"payment": {
"type": "object",
"description": "How this call was paid: protocol ('free' or 'none'), price and the free calls remaining."
},
"llm_used": {
"type": "boolean",
"description": "Always false: no language model is involved."
},
"ephemeris": {
"type": "string",
"description": "Ephemeris used (NASA/JPL DE440)."
},
"compute_ms": {
"type": "number",
"description": "Computation time in milliseconds."
},
"computed_at": {
"type": "string",
"description": "When it was computed (UTC, ISO 8601)."
},
"input_sha256": {
"type": "string",
"description": "SHA-256 of the canonical input."
},
"deterministic": {
"type": "boolean",
"description": "Always true: same input, same result."
},
"result_sha256": {
"type": "string",
"description": "SHA-256 of the canonical 'result'; check it with verify_result_hash."
},
"reproducibility": {
"type": "string",
"description": "How to reproduce and check this result."
},
"astronomy_library": {
"type": "string",
"description": "Astronomy library and version."
}
},
"description": "Provenance of the result."
},
"error": {
"type": "string",
"description": "x402 offer only: why payment is required."
},
"result": {
"type": "object",
"required": [
"settings",
"separations"
],
"properties": {
"settings": {
"type": "object",
"description": "The separation angles and tolerances applied, the rule, and where the longitudes came from."
},
"separations": {
"type": "array",
"description": "Pairs at a separation angle: point_a, point_b, angle (degrees), deviation from it, tolerance, exactness percentage, approaching or receding."
},
"declinations": {
"type": "object",
"description": "With options.declination: the declination of each body, degrees."
},
"declination_relations": {
"type": "array",
"description": "With options.declination: pairs with equal or opposite declinations (relation, both declinations, deviation, tolerance)."
}
},
"description": "The calculation result."
},
"accepts": {
"type": "array",
"items": {
"type": "object"
},
"minItems": 1,
"description": "x402 offer only: the payment options (scheme, network, amount, asset, payTo, ...)."
},
"endpoint": {
"type": "string",
"description": "The REST route that computed it, e.g. 'astronomy/rise-set'."
},
"resource": {
"type": "object",
"description": "x402 offer only: the resource being paid for."
},
"extensions": {
"type": "object",
"description": "x402 offer only: protocol extensions (bazaar)."
},
"x402Version": {
"type": "integer",
"description": "x402 offer only: protocol version (2)."
}
}
},
"annotations": {
"title": "Angular separations between bodies",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}| perspective | string | 'geocentric' (default) or 'heliocentric'. Heliocentric gives separations and longitude crossings only (no stations, lunations or eclipses). |
| include_moon | boolean | Also the Moon's separations, longitude crossings and declination events (geocentric only; many more events). |
{
"name": "celestial_events",
"title": "Celestial event calendar (eclipses, stations, lunations)",
"description": "Celestial event calendar: the exact UTC minute and unix timestamp of every solar and lunar eclipse, planetary station (retrograde / direct), lunation and separation between two dates, 1800-2200. E.g. {start: '2026-01-01', end: '2026-12-31', include: ['eclipse', 'station']}. A calendar of exact events between two dates: solar and lunar eclipses (type and magnitude), stations (retrograde / direct), new and full Moons and quarters, separations between planets at chosen angles, ecliptic longitudes crossing multiples of 30 degrees, equal / opposite declinations, and declinations passing the obliquity of the ecliptic. Geocentric or heliocentric. Each event has its UTC minute, a unix timestamp and a stable key. Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.25 per call via REST POST https://astro-agent.dev/v1/astronomy/events (x402 or MPP); always paid, never a free call.",
"inputSchema": {
"type": "object",
"required": [
"start",
"end"
],
"properties": {
"end": {
"type": "string",
"description": "Last UTC date, YYYY-MM-DD, at most 366 days after start (inclusive)."
},
"start": {
"type": "string",
"description": "First UTC date, YYYY-MM-DD, 1800..2199. Example: '2024-01-01'."
},
"angles": {
"oneOf": [
{
"enum": [
"all"
],
"type": "string"
},
{
"type": "array",
"items": {
"enum": [
0,
30,
45,
60,
72,
90,
120,
135,
144,
150,
180
],
"type": "integer"
}
}
],
"description": "Separation angles in degrees, 'all' or a list from [0, 30, 45, 60, 72, 90, 120, 135, 144, 150, 180]. Default: [0, 60, 90, 120, 180]."
},
"bodies": {
"type": "array",
"items": {
"enum": [
"sun",
"mercury",
"venus",
"earth",
"mars",
"jupiter",
"saturn",
"uranus",
"neptune",
"pluto"
],
"type": "string"
},
"description": "Planets searched. Default: Sun..Pluto (geo), Mercury..Pluto with Earth (helio)."
},
"include": {
"type": "array",
"items": {
"enum": [
"declination",
"declination_beyond_obliquity",
"eclipse",
"longitude_crossing",
"lunation",
"separation",
"station"
],
"type": "string"
},
"description": "Event types. Default: all that apply to the perspective. 'separation': two bodies reach one of the 'angles'; 'longitude_crossing': a body's ecliptic longitude crosses a multiple of 30 degrees; 'declination': equal or opposite declinations; 'declination_beyond_obliquity': |declination| passes the obliquity of the ecliptic; 'station', 'lunation', 'eclipse'."
},
"perspective": {
"enum": [
"geocentric",
"heliocentric"
],
"type": "string",
"default": "geocentric",
"description": "'geocentric' (default) or 'heliocentric'. Heliocentric gives separations and longitude crossings only (no stations, lunations or eclipses)."
},
"include_moon": {
"type": "boolean",
"default": false,
"description": "Also the Moon's separations, longitude crossings and declination events (geocentric only; many more events)."
}
}
},
"outputSchema": {
"type": "object",
"anyOf": [
{
"required": [
"endpoint",
"result",
"meta"
]
},
{
"required": [
"x402Version",
"accepts"
]
}
],
"properties": {
"meta": {
"type": "object",
"required": [
"engine",
"deterministic",
"llm_used",
"input_sha256",
"result_sha256"
],
"properties": {
"frame": {
"type": "string",
"description": "Reference frame of the positions."
},
"engine": {
"type": "string",
"description": "Engine name and version."
},
"payment": {
"type": "object",
"description": "How this call was paid: protocol ('free' or 'none'), price and the free calls remaining."
},
"llm_used": {
"type": "boolean",
"description": "Always false: no language model is involved."
},
"ephemeris": {
"type": "string",
"description": "Ephemeris used (NASA/JPL DE440)."
},
"compute_ms": {
"type": "number",
"description": "Computation time in milliseconds."
},
"computed_at": {
"type": "string",
"description": "When it was computed (UTC, ISO 8601)."
},
"input_sha256": {
"type": "string",
"description": "SHA-256 of the canonical input."
},
"deterministic": {
"type": "boolean",
"description": "Always true: same input, same result."
},
"result_sha256": {
"type": "string",
"description": "SHA-256 of the canonical 'result'; check it with verify_result_hash."
},
"reproducibility": {
"type": "string",
"description": "How to reproduce and check this result."
},
"astronomy_library": {
"type": "string",
"description": "Astronomy library and version."
}
},
"description": "Provenance of the result."
},
"error": {
"type": "string",
"description": "x402 offer only: why payment is required."
},
"result": {
"type": "object",
"required": [
"settings",
"events",
"counts"
],
"properties": {
"counts": {
"type": "object",
"description": "Number of events of each type."
},
"events": {
"type": "array",
"description": "Events in time order, each with 'type' (eclipse, lunation, station, separation, longitude_crossing, declination, declination_beyond_obliquity), its details, 'exact_utc', unix 'timestamp' and a stable 'key'."
},
"settings": {
"type": "object",
"description": "Settings applied: date range, perspective, event types, bodies, separation angles, frame, longitude reference, precision and the eclipse method."
}
},
"description": "The calculation result."
},
"accepts": {
"type": "array",
"items": {
"type": "object"
},
"minItems": 1,
"description": "x402 offer only: the payment options (scheme, network, amount, asset, payTo, ...)."
},
"endpoint": {
"type": "string",
"description": "The REST route that computed it, e.g. 'astronomy/rise-set'."
},
"resource": {
"type": "object",
"description": "x402 offer only: the resource being paid for."
},
"extensions": {
"type": "object",
"description": "x402 offer only: protocol extensions (bazaar)."
},
"x402Version": {
"type": "integer",
"description": "x402 offer only: protocol version (2)."
}
}
},
"annotations": {
"title": "Celestial event calendar (eclipses, stations, lunations)",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}| averages | array | Multi-body longitude averages: mean_of_5 = (Jupiter+Saturn+Uranus+Neptune+Pluto)/5, circle_of_8 = (Mercury+Venus+Mars+Jupiter+Saturn+Uranus+Neptune+Pluto)/8, in each perspective. |
| datetime | string | A moment (snapshot): ISO 8601 with Z or an offset, e.g. '2024-01-01T00:00Z'. A local time needs 'timezone' or coordinates. Omit when giving start/end. |
| interval | string | Series sampling step: 1 hour, 4 hours, 12 hours, 1 day or 1 week. |
| time_utc | string | Series: UTC time of day of the first sample, HH:MM. |
| timezone | string | IANA zone, e.g. 'Asia/Kolkata'. Optional: resolved from the coordinates, with the historical offset (DST, Local Mean Time) of that date. |
| perspective | string | Geocentric, heliocentric, or both in one call (default). |
| average_method | string | 'arithmetic' mean of the 0-360 longitude values or 'circular' (vector) mean of the directions. |
| include_declination | boolean | Series: also a declination column per body. |
{
"name": "longitude_series",
"title": "Planetary longitude series (geocentric + heliocentric)",
"description": "Planetary longitude time series: planet degrees seen from the Earth and from the Sun (geocentric and heliocentric) at a moment or every hour to every week, as pandas-ready columns, with speeds, retrograde flags and declinations. E.g. {start: '2024-01-01', end: '2024-12-31', interval: '1w', bodies: ['jupiter', 'saturn']}. Planetary longitudes as data: at a moment, or as a series of up to 1000 samples (columns ready for pandas). Geocentric apparent and heliocentric geometric, each with its speed and retrograde flag; optional offsets (longitude + angle), circular or arithmetic multi-body averages, unwrapped degrees for plotting, and declinations. Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.20 per call via REST POST https://astro-agent.dev/v1/astronomy/longitude-series (x402 or MPP); always paid, never a free call.",
"inputSchema": {
"type": "object",
"properties": {
"end": {
"type": "string",
"description": "Series: last UTC date, YYYY-MM-DD (at most 1000 samples)."
},
"start": {
"type": "string",
"description": "Series: first UTC date, YYYY-MM-DD. Example: '2024-01-01'."
},
"bodies": {
"type": "array",
"items": {
"enum": [
"sun",
"moon",
"mercury",
"venus",
"earth",
"mars",
"jupiter",
"saturn",
"uranus",
"neptune",
"pluto",
"lunar_node_mean",
"lunar_node_true"
],
"type": "string"
},
"description": "Bodies. Default: Sun..Pluto (geocentric), Mercury..Pluto with the Earth (heliocentric)."
},
"format": {
"enum": [
"columns",
"rows"
],
"type": "string",
"default": "columns",
"description": "Series layout: 'columns' (pandas.DataFrame(result['series'])) or 'rows' (one object per sample)."
},
"unwrap": {
"type": "boolean",
"default": false,
"description": "Series: continuous degrees (no 360 -> 0 jump), for plotting."
},
"offsets": {
"oneOf": [
{
"enum": [
"all"
],
"type": "string"
},
{
"type": "array",
"items": {
"enum": [
0,
30,
45,
60,
72,
90,
120,
135,
144,
150,
180
],
"type": "integer"
}
}
],
"description": "Angles in degrees added to every longitude (+angle and -angle), 'all' or a list from [0, 30, 45, 60, 72, 90, 120, 135, 144, 150, 180]. Default: none (the longitude itself)."
},
"averages": {
"type": "array",
"items": {
"enum": [
"mean_of_5",
"circle_of_8"
],
"type": "string"
},
"description": "Multi-body longitude averages: mean_of_5 = (Jupiter+Saturn+Uranus+Neptune+Pluto)/5, circle_of_8 = (Mercury+Venus+Mars+Jupiter+Saturn+Uranus+Neptune+Pluto)/8, in each perspective."
},
"datetime": {
"type": "string",
"description": "A moment (snapshot): ISO 8601 with Z or an offset, e.g. '2024-01-01T00:00Z'. A local time needs 'timezone' or coordinates. Omit when giving start/end."
},
"interval": {
"enum": [
"1h",
"4h",
"12h",
"1d",
"1w"
],
"type": "string",
"default": "1d",
"description": "Series sampling step: 1 hour, 4 hours, 12 hours, 1 day or 1 week."
},
"time_utc": {
"type": "string",
"default": "00:00",
"description": "Series: UTC time of day of the first sample, HH:MM."
},
"timezone": {
"type": "string",
"description": "IANA zone, e.g. 'Asia/Kolkata'. Optional: resolved from the coordinates, with the historical offset (DST, Local Mean Time) of that date."
},
"perspective": {
"enum": [
"geocentric",
"heliocentric",
"both"
],
"type": "string",
"default": "both",
"description": "Geocentric, heliocentric, or both in one call (default)."
},
"average_method": {
"enum": [
"arithmetic",
"circular"
],
"type": "string",
"default": "arithmetic",
"description": "'arithmetic' mean of the 0-360 longitude values or 'circular' (vector) mean of the directions."
},
"include_declination": {
"type": "boolean",
"default": false,
"description": "Series: also a declination column per body."
}
}
},
"outputSchema": {
"type": "object",
"anyOf": [
{
"required": [
"endpoint",
"result",
"meta"
]
},
{
"required": [
"x402Version",
"accepts"
]
}
],
"properties": {
"meta": {
"type": "object",
"required": [
"engine",
"deterministic",
"llm_used",
"input_sha256",
"result_sha256"
],
"properties": {
"frame": {
"type": "string",
"description": "Reference frame of the positions."
},
"engine": {
"type": "string",
"description": "Engine name and version."
},
"payment": {
"type": "object",
"description": "How this call was paid: protocol ('free' or 'none'), price and the free calls remaining."
},
"llm_used": {
"type": "boolean",
"description": "Always false: no language model is involved."
},
"ephemeris": {
"type": "string",
"description": "Ephemeris used (NASA/JPL DE440)."
},
"compute_ms": {
"type": "number",
"description": "Computation time in milliseconds."
},
"computed_at": {
"type": "string",
"description": "When it was computed (UTC, ISO 8601)."
},
"input_sha256": {
"type": "string",
"description": "SHA-256 of the canonical input."
},
"deterministic": {
"type": "boolean",
"description": "Always true: same input, same result."
},
"result_sha256": {
"type": "string",
"description": "SHA-256 of the canonical 'result'; check it with verify_result_hash."
},
"reproducibility": {
"type": "string",
"description": "How to reproduce and check this result."
},
"astronomy_library": {
"type": "string",
"description": "Astronomy library and version."
}
},
"description": "Provenance of the result."
},
"error": {
"type": "string",
"description": "x402 offer only: why payment is required."
},
"result": {
"type": "object",
"required": [
"settings",
"counts"
],
"properties": {
"lines": {
"type": "array",
"description": "Snapshot only: one entry per line (id such as 'helio.jupiter+90', perspective, base body or average, offset, degree 0-360; speed, retrograde flag and declination on base lines)."
},
"counts": {
"type": "object",
"description": "Number of lines (snapshot) or of samples and columns (series)."
},
"series": {
"type": [
"object",
"array"
],
"description": "Series only: 'columns' format = {time_utc: [...], timestamp: [...], <line id>: [...]}; 'rows' format = one object per sample."
},
"subject": {
"type": "object",
"description": "Snapshot only: the resolved moment (UTC, Julian days, Delta T)."
},
"settings": {
"type": "object",
"description": "Settings applied: perspectives, bodies, offsets, averages and their members, frames, line id format and, for a series, interval, samples and columns."
},
"warnings": {
"type": "array",
"description": "Notes on the input or the calculation (for example an assumed local noon when only a date is given). Present only when there is something to say."
}
},
"description": "The calculation result."
},
"accepts": {
"type": "array",
"items": {
"type": "object"
},
"minItems": 1,
"description": "x402 offer only: the payment options (scheme, network, amount, asset, payTo, ...)."
},
"endpoint": {
"type": "string",
"description": "The REST route that computed it, e.g. 'astronomy/rise-set'."
},
"resource": {
"type": "object",
"description": "x402 offer only: the resource being paid for."
},
"extensions": {
"type": "object",
"description": "x402 offer only: protocol extensions (bazaar)."
},
"x402Version": {
"type": "integer",
"description": "x402 offer only: protocol version (2)."
}
}
},
"annotations": {
"title": "Planetary longitude series (geocentric + heliocentric)",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}| direction | string | Search before the reference (with a local date-time and place: before that moment), after it, or both (default; the only choice with reference.values without 'datetime'). |
| reference | any | The sky to match: 'now' (default; the current UTC hour or day, echoed in result.reference.date_utc), a UTC moment ('2026-10-29T00:00Z' or 'YYYY-MM-DD'), {datetime: ...}, your own values {values: {feature id: value}} (add 'datetime' to anchor direction and range at a time), or a local date-time and p… |
| resolution | string | Step of the candidate grid. At most 36,600 candidate dates per call, and at most 660,000 dates x ephemeris series (one per body and perspective, plus one per retrograde-flagged body). |
| perspective | string | Positions seen from the Earth, from the Sun, or both. |
| max_distance | number | Optional: only matches whose score (degrees) is at most this. |
| min_separation_days | number | Minimum gap between two matches and between a match and the reference time, so one passage gives one match. Raise it (e.g. 3650) to skip the current cycle of slow planets. |
| require_same_retrograde | boolean | Keep only dates whose retrograde flags equal the reference's. |
{
"name": "similar_skies",
"title": "Sky similarity search (matching skies)",
"description": "Sky similarity search: find the past or future dates whose planetary positions best match a reference sky, ranked by a stated angular distance in degrees. E.g. {reference: '2026-10-29T00:00Z', direction: 'past', bodies: ['jupiter', 'saturn']}. Searches a date grid (1 hour to 1 week steps, 1800-2200) for the skies closest to a reference: by longitude, by the separations between bodies, by declination, optionally with the same retrograde flags. The score is a weighted mean angular distance in degrees, defined in result.settings.metric. Data for your own analysis — never a signal or forecast. Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.25 per call via REST POST https://astro-agent.dev/v1/astronomy/sky-analogues (x402 or MPP); always paid, never a free call.",
"inputSchema": {
"type": "object",
"properties": {
"range": {
"type": "object",
"properties": {
"end": {
"type": "string",
"description": "Last UTC date, YYYY-MM-DD (inclusive)."
},
"start": {
"type": "string",
"description": "First UTC date, YYYY-MM-DD, 1800..2199."
}
},
"description": "Candidate dates. Default (a reference with a time): the longest window the caps allow, up to 100 years in the chosen direction (50 on each side for 'both')."
},
"top_n": {
"type": "integer",
"default": 10,
"maximum": 100,
"minimum": 1,
"description": "How many matches."
},
"bodies": {
"type": "array",
"items": {
"enum": [
"sun",
"moon",
"mercury",
"venus",
"earth",
"mars",
"jupiter",
"saturn",
"uranus",
"neptune",
"pluto"
],
"type": "string"
},
"description": "Bodies to match. Default: Sun..Pluto (geo), Mercury..Pluto with Earth (helio)."
},
"format": {
"enum": [
"columns",
"rows"
],
"type": "string",
"default": "columns",
"description": "'columns' (pandas.DataFrame(result['matches'])) or 'rows' (one object per match)."
},
"weights": {
"type": "object",
"description": "Optional {feature id: weight}, default 1 each, e.g. {'geo.jupiter': 2}. Feature ids: '<geo|helio>.<body>' (longitude, 0-360), '<geo|helio>.<a>-<b>:angle' (separation, 0-180), '<geo|helio>.<body>:declination' (degrees) and 'geo.<body>:retrograde' (true/false).",
"additionalProperties": {
"type": "number",
"minimum": 0
}
},
"features": {
"type": "array",
"items": {
"enum": [
"longitude",
"separations",
"declination",
"retrograde"
],
"type": "string"
},
"description": "What to compare: 'longitude' (default), 'separations' (the angle between every pair of bodies), 'declination', 'retrograde' (a filter on equal retrograde flags)."
},
"direction": {
"enum": [
"past",
"future",
"both"
],
"type": "string",
"default": "both",
"description": "Search before the reference (with a local date-time and place: before that moment), after it, or both (default; the only choice with reference.values without 'datetime')."
},
"reference": {
"oneOf": [
{
"type": "string"
},
{
"type": "object",
"required": [
"datetime"
],
"properties": {
"datetime": {
"type": "string"
}
}
},
{
"type": "object",
"required": [
"values"
],
"properties": {
"values": {
"type": "object"
},
"datetime": {
"type": "string"
}
}
},
{
"type": "object",
"required": [
"place"
],
"properties": {
"place": {
"type": "object",
"required": [
"datetime",
"latitude",
"longitude"
],
"properties": {
"datetime": {
"type": "string"
},
"latitude": {
"type": "number"
},
"timezone": {
"type": "string"
},
"longitude": {
"type": "number"
}
}
}
}
}
],
"description": "The sky to match: 'now' (default; the current UTC hour or day, echoed in result.reference.date_utc), a UTC moment ('2026-10-29T00:00Z' or 'YYYY-MM-DD'), {datetime: ...}, your own values {values: {feature id: value}} (add 'datetime' to anchor direction and range at a time), or a local date-time and place {place: {datetime: local '1990-05-15T14:30', latitude, longitude, timezone?}}: the time zone comes from the coordinates or 'timezone'; a date alone means 12:00 local with a TIME_UNKNOWN warning. meta.reference_resolution gives the equivalent {values, datetime} request. Feature ids: '<geo|helio>.<body>' (longitude, 0-360), '<geo|helio>.<a>-<b>:angle' (separation, 0-180), '<geo|helio>.<body>:declination' (degrees) and 'geo.<body>:retrograde'."
},
"resolution": {
"enum": [
"1h",
"4h",
"12h",
"1d",
"1w"
],
"type": "string",
"default": "1d",
"description": "Step of the candidate grid. At most 36,600 candidate dates per call, and at most 660,000 dates x ephemeris series (one per body and perspective, plus one per retrograde-flagged body)."
},
"perspective": {
"enum": [
"geocentric",
"heliocentric",
"both"
],
"type": "string",
"default": "geocentric",
"description": "Positions seen from the Earth, from the Sun, or both."
},
"max_distance": {
"type": "number",
"maximum": 180,
"minimum": 0,
"description": "Optional: only matches whose score (degrees) is at most this."
},
"min_separation_days": {
"type": "number",
"default": 30,
"minimum": 0,
"description": "Minimum gap between two matches and between a match and the reference time, so one passage gives one match. Raise it (e.g. 3650) to skip the current cycle of slow planets."
},
"require_same_retrograde": {
"type": "boolean",
"default": false,
"description": "Keep only dates whose retrograde flags equal the reference's."
}
}
},
"outputSchema": {
"type": "object",
"anyOf": [
{
"required": [
"endpoint",
"result",
"meta"
]
},
{
"required": [
"x402Version",
"accepts"
]
}
],
"properties": {
"meta": {
"type": "object",
"required": [
"engine",
"deterministic",
"llm_used",
"input_sha256",
"result_sha256"
],
"properties": {
"frame": {
"type": "string",
"description": "Reference frame of the positions."
},
"engine": {
"type": "string",
"description": "Engine name and version."
},
"payment": {
"type": "object",
"description": "How this call was paid: protocol ('free' or 'none'), price and the free calls remaining."
},
"llm_used": {
"type": "boolean",
"description": "Always false: no language model is involved."
},
"ephemeris": {
"type": "string",
"description": "Ephemeris used (NASA/JPL DE440)."
},
"compute_ms": {
"type": "number",
"description": "Computation time in milliseconds."
},
"computed_at": {
"type": "string",
"description": "When it was computed (UTC, ISO 8601)."
},
"input_sha256": {
"type": "string",
"description": "SHA-256 of the canonical input."
},
"deterministic": {
"type": "boolean",
"description": "Always true: same input, same result."
},
"result_sha256": {
"type": "string",
"description": "SHA-256 of the canonical 'result'; check it with verify_result_hash."
},
"reproducibility": {
"type": "string",
"description": "How to reproduce and check this result."
},
"astronomy_library": {
"type": "string",
"description": "Astronomy library and version."
}
},
"description": "Provenance of the result."
},
"error": {
"type": "string",
"description": "x402 offer only: why payment is required."
},
"result": {
"type": "object",
"required": [
"settings",
"reference",
"matches",
"counts"
],
"properties": {
"counts": {
"type": "object",
"description": "Number of candidate dates, eligible dates and matches."
},
"matches": {
"type": [
"object",
"array"
],
"description": "Matching dates ranked by score: 'columns' format = {rank: [...], date_utc: [...], timestamp: [...], score: [...], <body or feature>: [...], distance:<feature id>: [...]}; 'rows' format = one object per match."
},
"settings": {
"type": "object",
"description": "Settings applied: reference source, direction, range, resolution, perspectives, bodies, features and their ids, weights, top_n, max_distance, min_separation_days, frames, column names and the metric definition (formula per feature)."
},
"reference": {
"type": "object",
"description": "The reference sky: its date_utc and timestamp with every body's longitude and retrograde flag (and matched angles / declinations), or the values you gave."
}
},
"description": "The calculation result."
},
"accepts": {
"type": "array",
"items": {
"type": "object"
},
"minItems": 1,
"description": "x402 offer only: the payment options (scheme, network, amount, asset, payTo, ...)."
},
"endpoint": {
"type": "string",
"description": "The REST route that computed it, e.g. 'astronomy/rise-set'."
},
"resource": {
"type": "object",
"description": "x402 offer only: the resource being paid for."
},
"extensions": {
"type": "object",
"description": "x402 offer only: protocol extensions (bazaar)."
},
"x402Version": {
"type": "integer",
"description": "x402 offer only: protocol version (2)."
}
}
},
"annotations": {
"title": "Sky similarity search (matching skies)",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}| time_basis | string | What the given clock time is: civil wall-clock (default), UTC, Local Mean Time, or true (apparent) solar time. |
| ambiguous_time | string | Which occurrence to use when a local time happens twice (DST fall-back). |
{
"name": "resolve_local_time",
"title": "Local time resolver (historical time zones)",
"description": "Local time to UTC conversion: convert a local date, time and place into exact Universal Time, with the historical time zone and UTC offset, Delta T, Local Mean Time and true solar time. E.g. {datetime: '1947-08-15T00:00', latitude: 28.6139, longitude: 77.209}. Resolves the IANA time zone from coordinates, applies the offset in force on that date (historical daylight saving, Local Mean Time before standard time), flags ambiguous or non-existent local times instead of guessing, and returns Julian Days (UT/TT), Delta T, Local Mean Time, true (apparent) solar time and the equation of time. Deterministic (JPL DE440, no LLM); every result carries meta.result_sha256. Price $0.01 per call via REST POST https://astro-agent.dev/v1/astronomy/local-time (x402 or MPP); each client gets 1 free call on the $0.01-0.02 tools, this one included.",
"inputSchema": {
"type": "object",
"required": [],
"properties": {
"date": {
"type": "string",
"description": "YYYY-MM-DD (use with 'time' instead of 'datetime')."
},
"time": {
"type": "string",
"description": "HH:MM or HH:MM:SS, 24 h. Omit if unknown (computed at 12:00 with a TIME_UNKNOWN warning)."
},
"datetime": {
"type": "string",
"examples": [
"1990-05-15T14:30"
],
"description": "Local civil date-time, ISO 8601: '1990-05-15T14:30' (local clock time at the place) or with an explicit offset '1990-05-15T14:30:00+02:00'. Alternative: 'date' + 'time'."
},
"latitude": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Decimal degrees, north positive."
},
"timezone": {
"type": "string",
"description": "IANA zone, e.g. 'Asia/Kolkata'. Optional: resolved from the coordinates, with the historical offset (DST, Local Mean Time) of that date."
},
"longitude": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Decimal degrees, east positive."
},
"time_basis": {
"enum": [
"civil",
"utc",
"lmt",
"true_solar"
],
"type": "string",
"default": "civil",
"description": "What the given clock time is: civil wall-clock (default), UTC, Local Mean Time, or true (apparent) solar time."
},
"ambiguous_time": {
"enum": [
"earlier",
"later"
],
"type": "string",
"default": "earlier",
"description": "Which occurrence to use when a local time happens twice (DST fall-back)."
}
},
"description": "Coordinates or a timezone are needed to interpret a local time."
},
"outputSchema": {
"type": "object",
"anyOf": [
{
"required": [
"endpoint",
"result",
"meta"
]
},
{
"required": [
"x402Version",
"accepts"
]
}
],
"properties": {
"meta": {
"type": "object",
"required": [
"engine",
"deterministic",
"llm_used",
"input_sha256",
"result_sha256"
],
"properties": {
"frame": {
"type": "string",
"description": "Reference frame of the positions."
},
"engine": {
"type": "string",
"description": "Engine name and version."
},
"payment": {
"type": "object",
"description": "How this call was paid: protocol ('free' or 'none'), price and the free calls remaining."
},
"llm_used": {
"type": "boolean",
"description": "Always false: no language model is involved."
},
"ephemeris": {
"type": "string",
"description": "Ephemeris used (NASA/JPL DE440)."
},
"compute_ms": {
"type": "number",
"description": "Computation time in milliseconds."
},
"computed_at": {
"type": "string",
"description": "When it was computed (UTC, ISO 8601)."
},
"input_sha256": {
"type": "string",
"description": "SHA-256 of the canonical input."
},
"deterministic": {
"type": "boolean",
"description": "Always true: same input, same result."
},
"result_sha256": {
"type": "string",
"description": "SHA-256 of the canonical 'result'; check it with verify_result_hash."
},
"reproducibility": {
"type": "string",
"description": "How to reproduce and check this result."
},
"astronomy_library": {
"type": "string",
"description": "Astronomy library and version."
}
},
"description": "Provenance of the result."
},
"error": {
"type": "string",
"description": "x402 offer only: why payment is required."
},
"result": {
"type": "object",
"required": [
"time",
"location"
],
"properties": {
"time": {
"type": "object",
"description": "Resolved time: local input, IANA time zone and how it was found, historical UTC offset, DST flag, UTC instant, Julian days (UT and TT), Delta T, local mean time, true solar time and the equation of time."
},
"location": {
"type": "object",
"description": "The latitude and longitude used, in decimal degrees."
},
"warnings": {
"type": "array",
"description": "Notes on the input or the calculation (for example an assumed local noon when only a date is given). Present only when there is something to say."
}
},
"description": "The calculation result."
},
"accepts": {
"type": "array",
"items": {
"type": "object"
},
"minItems": 1,
"description": "x402 offer only: the payment options (scheme, network, amount, asset, payTo, ...)."
},
"endpoint": {
"type": "string",
"description": "The REST route that computed it, e.g. 'astronomy/rise-set'."
},
"resource": {
"type": "object",
"description": "x402 offer only: the resource being paid for."
},
"extensions": {
"type": "object",
"description": "x402 offer only: protocol extensions (bazaar)."
},
"x402Version": {
"type": "integer",
"description": "x402 offer only: protocol version (2)."
}
}
},
"annotations": {
"title": "Local time resolver (historical time zones)",
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true,
"destructiveHint": false
}
}