Sun times (sunrise, sunset, twilight)
GET /api/sun-timesSunrise, sunset, solar noon, day length and the civil, nautical and astronomical twilights for any point and date, plus the sun's elevation and azimuth at a given time. Send GET /api/sun-times with the required fields lat and lon and pay $0.001 per call over x402 or MPP, or call it free by solving a proof-of-work challenge. It returns a JSON object with lat, lon, date, sunrise, sunset and 12 more.
Computed with the NOAA solar equations; times are UTC, good to about a minute away from the poles. Says so when the sun stays up or down all day.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
lat | number | yes | Latitude, -90 to 90 Also accepted as latitude. |
lon | number | yes | Longitude, -180 to 180 Also accepted as lng, long, longitude. |
date | string | no | Date, YYYY-MM-DD (default today, UTC). Events are those around the point's solar noon on that date |
time | string | no | Optional ISO 8601 time at which to give the sun's elevation and azimuth, for example 2026-06-21T16:00:00Z |
Example request
curl -i "https://agent402.tools/api/sun-times?lat=40.7128&lon=-74.006&date=2026-06-21&time=2026-06-21T16%3A00%3A00Z"
Without payment this returns HTTP 402 Payment Required with the exact price for sun-times; any x402 v2 or MPP client pays it and retries.
Example response
{
"lat": 40.7128,
"lon": -74.006,
"date": "2026-06-21",
"sunrise": "2026-06-21T09:25:05Z",
"sunset": "2026-06-22T00:30:42Z",
"solarNoon": "2026-06-21T16:57:54Z",
"dayLengthMinutes": 906,
"civilDawn": "2026-06-21T08:51:40Z",
"civilDusk": "2026-06-22T01:04:07Z",
"nauticalDawn": "2026-06-21T08:09:00Z",
"nauticalDusk": "2026-06-22T01:46:47Z",
"astronomicalDawn": "2026-06-21T07:18:36Z",
"astronomicalDusk": "2026-06-22T02:37:12Z",
"noonElevation": 72.72,
"position": {
"time": "2026-06-21T16:00:00.000Z",
"elevation": 68.88,
"azimuth": 140.48
},
"timezone": "UTC",
"method": "NOAA solar equations"
}| Field | Type | Always present | In the example |
|---|---|---|---|
lat | number | yes | 40.7128 |
lon | number | yes | -74.006 |
date | string | yes | 2026-06-21 |
sunrise | string | yes | 2026-06-21T09:25:05Z |
sunset | string | yes | 2026-06-22T00:30:42Z |
solarNoon | string | yes | 2026-06-21T16:57:54Z |
dayLengthMinutes | number | yes | 906 |
civilDawn | string | yes | 2026-06-21T08:51:40Z |
civilDusk | string | yes | 2026-06-22T01:04:07Z |
nauticalDawn | string | yes | 2026-06-21T08:09:00Z |
nauticalDusk | string | yes | 2026-06-22T01:46:47Z |
astronomicalDawn | string | yes | 2026-06-21T07:18:36Z |
astronomicalDusk | string | yes | 2026-06-22T02:37:12Z |
noonElevation | number | yes | 72.72 |
position | object | yes | 3 fields: time, elevation, azimuth |
timezone | string | yes | UTC |
method | string | yes | NOAA solar equations |
From an MCP client
catalog.call {
"slug": "sun-times",
"params": {
"lat": 40.7128,
"lon": -74.006,
"date": "2026-06-21",
"time": "2026-06-21T16:00:00Z"
}
}On the hosted connector at https://agent402.tools/mcp, catalog.call runs sun-times free (rate-limited, no wallet). Local install: npx -y agent402-mcp@0.13.32.
Errors and behavior
latandlonare required. An input the tool rejects returns an HTTP 4xx whose body carrieserror,tool,expected,requiredandexample, so the caller can correct it.- A paid call that ends in any status of 400 or above is not charged over x402, MPP or a prepaid credits key: settlement runs after the tool and only on a successful response. The exception is a Tempo push credential, a transfer the buyer sent before the call: it settles before the tool runs, so if the tool then fails the payment is recorded as a refund owed to the paying wallet.
- Free tier: no outbound network call leaves the server for this tool, so proof-of-work (16 leading zero bits of sha256) pays for it.
- A
POSTwith a JSON body to /api/sun-times is served as this GET, with the body as the input. - An
Idempotency-Keyheader makes a retried paid call replay the first 200 instead of charging again (an answer larger than 1 MB is not replayed).
Paid call (JavaScript agent)
import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
const client = new x402Client();
client.setSpendControls?.({ maxAmountPerPayment: "$0.001" }); // refuse any quote above this tool's price
registerExactEvmScheme(client, { signer: privateKeyToAccount(KEY) });
const payFetch = wrapFetchWithPayment(fetch, client);
const res = await payFetch("https://agent402.tools/api/sun-times?lat=40.7128&lon=-74.006&date=2026-06-21&time=2026-06-21T16%3A00%3A00Z");No wallet? Pay with compute
Fetch a challenge, solve the sha256 puzzle (16 leading zero bits, a fraction of a second of CPU), and resend with the X-Pow-Solution header:
import { createHash } from "node:crypto";
const lz = (b) => { let t = 0; for (const x of b) { if (!x) { t += 8; continue; } t += Math.clz32(x) - 24; break; } return t; };
const c = await (await fetch("https://agent402.tools/api/pow/challenge?slug=sun-times")).json();
let n = 0;
while (lz(createHash("sha256").update(c.challenge + ":" + n).digest()) < c.difficulty) n++;
await fetch("https://agent402.tools/api/sun-times?lat=40.7128&lon=-74.006&date=2026-06-21&time=2026-06-21T16%3A00%3A00Z", { method: "GET", headers: { "X-Pow-Solution": c.token + ":" + n } });Related tools
A2A Agent Card validate
Validate an A2A (Agent2Agent protocol) Agent Card: required fields, skill shape, transport names, capability flags.
Amortization schedule
Build the full per-period amortization schedule for a fully-amortizing loan.
Annuity present/future value
Present and future value of a level annuity (equal periodic payments).
AQI calculator (US EPA)
US EPA Air Quality Index from the pollutant concentrations you supply: PM2.5 and PM10 (µg/m³, 24-hour), ozone (ppb.
Barcode / QR decode
Decode a barcode or QR code from an image.
Barcode product lookup
Look up a product by its UPC/EAN barcode number via Open Food Facts (open data): name, brand, category, quantity.