Sky analogues (matching skies)
sky_analoguesFinancial astrology sky analogues (matching skies, planetary cycle analogues): find the past or future dates whose planetary positions best match a reference sky (a moment, now, positions you give, or a birth sky: compare a birth sky to past/future dates), ranked by a stated angular distance, to line up market history (stocks, crypto) with similar skies in a backtest. E.g. {reference: '2026-10-29T00:00Z', direction: 'past', bodies: ['jupiter', 'saturn'], min_separation_days: 3650}. Data only. Matching skies by geometry, data only: give a reference (a UTC moment, 'now', your own positions, or a birth sky: compare a birth sky to past/future dates — data only) and get the dates in a range (past, future or both, 1800-2200, 1h..1w grid) whose sky is closest, ranked by a weighted mean of circular longitude differences (geocentric and/or heliocentric), pair angles (aspects), declination differences and retrograde-flag mismatches, in degrees. Each match gives its date, unix timestamp, score, every body's exact longitude and retrograde flag and each feature's distance, in columns ready for pandas. The metric formula is in the response; the same request returns the same bytes and hash, future dates included. Up to 100 matches and 36,600 candidate dates per call; no market data. 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/finance/analogues (x402 or MPP); always paid, never a free call.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "sky_analogues"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| range | No | 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 | No | How many matches. | |
| bodies | No | Bodies to match. Default: Sun..Pluto (geo), Mercury..Pluto with Earth (helio). | |
| format | No | 'columns' (pandas.DataFrame(result['matches'])) or 'rows' (one object per match). | columns |
| options | No | Optional zodiac settings. | |
| weights | No | 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 | No | What to compare: 'longitude' (default), 'aspects' (the angle between every pair of bodies), 'declination', 'retrograde' (geocentric flags, Mercury..Pluto). | |
| direction | No | Search before the reference (a birth: before the birth moment), after it, or both (default; the only choice with reference.values without 'datetime'). | both |
| reference | No | 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 configuration {values: {feature id: value}} (add 'datetime' to anchor direction and range at a time), or a birth sky {birth: {datetime: local '1990-05-15T14:30', latitude, longitude, timezone?}} to compare a birth sky to past/future dates. The birth moment is resolved as in /v1/western/positions (time zone from the coordinates or 'timezone'); a date alone means 12:00 local with a TIME_UNKNOWN warning (the Moon is then approximate, Jupiter..Pluto stay reliable). No houses or ascendant. meta.reference_resolution gives the equivalent {values, datetime} request, which returns the same result and result_sha256. 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). | |
| resolution | No | 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). | 1d |
| perspective | No | Positions seen from the Earth, from the Sun, or both. | geocentric |
| max_distance | No | Optional: only matches whose score (degrees) is at most this. | |
| min_separation_days | No | 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 | No | Keep only dates whose retrograde flags equal the reference's. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| meta | No | Provenance of the result. | |
| error | No | x402 offer only: why payment is required. | |
| result | No | The calculation result. | |
| accepts | No | x402 offer only: the payment options (scheme, network, amount, asset, payTo, ...). | |
| endpoint | No | The REST route that computed it, e.g. 'western/natal'. | |
| resource | No | x402 offer only: the resource being paid for. | |
| extensions | No | x402 offer only: protocol extensions (bazaar). | |
| x402Version | No | x402 offer only: protocol version (2). |