# Touchstone Sky — Astronomical Ephemeris API

> Touchstone Sky — Astronomical Ephemeris API is a paid API for AI agents from touchstone.locomot.io, paid per call via x402, $0.003/call, status unknown (last checked 2026-09-13).

Returns sun, moon, planetary body positions, twilight times, and next seasonal event for a given lat/lon and optional time

## Facts

- Endpoint: GET https://touchstone.locomot.io/sky
- Price: $0.003/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-13
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/touchstone-sky-astronomical-ephemeris-api-c6fa0eca
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_8qQzLN8RfLKCDobHefSR-

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability touchstone-sky-astronomical-ephemeris-api-c6fa0eca
```

Example prompt: What are the sunrise, sunset, and twilight times today at latitude 37.77 and longitude -122.42, and when is the next solstice or equinox?

## When to prefer this

Use this endpoint when you need precise, physics-based astronomical ephemeris data for a geographic location — including sun/moon rise/set times, planetary positions, twilight windows, and seasonal events. It is preferable over weather APIs (which focus on atmospheric data) or simple sunrise APIs (which lack moon, planets, and twilight breakdown). Best suited for stargazing apps, navigation tools, astronomical planning, outdoor activity scheduling, or any application requiring precise celestial timing.

## Known failure modes

- Missing lat or lon parameters returns a 400/422 validation error
- Latitude out of range -90 to 90 or longitude out of range -180 to 180 returns schema validation error
- Malformed or non-ISO-8601 'when' timestamp results in parse error
- Payment not provided or insufficient for x402 protocol returns 402 Payment Required
- Elevation value out of reasonable range may cause computation anomalies

## How this service works

Deterministic ephemeris snapshot (one location/time). Free sample, no payment required: GET /play/sky

## Output

Returns a JSON object with sun data (rise, set, azimuth, altitude), moon data (rise, set, phase, illumination), positions of other planetary bodies, an array of twilight events (civil, nautical, astronomical), the next upcoming seasonal event (solstice/equinox), and metadata about the computation engine and kernel. The response is deterministic for a given input.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET",
      "HEAD",
      "DELETE"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "required": [
      "lat",
      "lon"
     ],
     "properties": {
      "lat": {
       "type": "number",
       "maximum": 90,
       "minimum": -90
      },
      "lon": {
       "type": "number",
       "maximum": 180,
       "minimum": -180
      },
      "when": {
       "type": "string",
       "description": "ISO-8601 UTC; default now"
      },
      "elevation_m": {
       "type": "number",
       "description": "optional, default 0"
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "properties": {
    "sun": {
     "type": "object"
    },
    "moon": {
     "type": "object"
    },
    "query": {
     "type": "object"
    },
    "bodies": {
     "type": "object"
    },
    "engine": {
     "type": "string"
    },
    "kernel": {
     "type": "string"
    },
    "twilight": {
     "type": "array"
    },
    "visible_now": {
     "type": "object"
    },
    "deterministic": {
     "type": "boolean"
    },
    "next_season_event": {
     "type": "object"
    }
   }
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/touchstone-sky-astronomical-ephemeris-api-c6fa0eca/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from touchstone.locomot.io](https://www.zero.xyz/host/touchstone.locomot.io/llms.txt)