Official US weather forecast for a coordinate (US land + territories). Pass lat + lon. Returns the National Weather Service forecast as a list of periods — by default ~7 days of day/night periods; pass hourly=true for an hour-by-hour forecast. Each period gives the temperature + unit, wind speed/direction, chance of precipitation, and a short + detailed forecast, plus the resolved city/state and issuing office. Source: US National Weather Service (api.weather.gov), public domain. For active warnings use weather.alerts.
/api/weather/forecastPAYMENT-SIGNATURE.The weather forecast API returns the official US National Weather Service forecast for any coordinate — the same authoritative source that powers weather.gov, served as clean JSON for agents.
Pass a latitude and longitude and get back a list of forecast periods: by default about seven days of day/night periods, or set hourly=true for an hour-by-hour forecast. Each period includes temperature and unit, wind speed and direction, chance of precipitation, and a short and detailed forecast, plus the resolved city/state and the issuing NWS office. The data is US public domain, and there is no API key — an agent signs a sub-cent USDC payment per call and gets the forecast back. For active warnings and watches, pair it with the weather alerts endpoint.
| Name | Type | Description |
|---|---|---|
latrequired | number | min -90 · max 90 |
lonrequired | number | min -180 · max 180 |
hourly | boolean | |
limit | integer | min 1 · max 156 |
# 1. Probe with no auth → 402 envelope with PaymentRequirements curl -sS 'https://2s.io/api/weather/forecast?lat=-90&lon=-180&hourly=false&limit=1' # 2. Sign + retry with PAYMENT-SIGNATURE: curl -sS 'https://2s.io/api/weather/forecast?lat=-90&lon=-180&hourly=false&limit=1' \ -H 'PAYMENT-SIGNATURE: <base64-json-payload>' # Or use the canonical runner (handles probe → sign → retry): # EVM_PRIVATE_KEY=0x... node --env-file=.env.local \ # --experimental-strip-types scripts/x402-pay.ts \ # 'https://2s.io/api/weather/forecast?lat=-90&lon=-180&hourly=false&limit=1'
import { TwoS } from '@2sio/sdk'
const client = new TwoS({
privateKey: process.env.EVM_PRIVATE_KEY as `0x${string}`,
})
const result = await client.weather.forecast({
"lat": -90,
"lon": -180,
"hourly": false,
"limit": 1
})
console.log('endpoint:', result.endpoint)
console.log('cost:', result.costUsd, 'USDC')
console.log('tx:', result.settlement?.txHash)
console.log('data:', result.data)import os
from twosio import TwoS
client = TwoS(private_key=os.environ["EVM_PRIVATE_KEY"])
result = client.weather.forecast(lat=-90, lon=-180, hourly=False, limit=1)
print("endpoint:", result.endpoint)
print("cost:", result.cost_usd, "USDC")
print("tx:", (result.settlement or {}).get("tx_hash"))
print("data:", result.data)// 1. Add @2sio/mcp to your MCP host config (Claude Desktop example below).
// EVM_PRIVATE_KEY funds x402 payments per call.
// claude_desktop_config.json
{
"mcpServers": {
"2sio": {
"command": "npx",
"args": ["-y", "@2sio/mcp"],
"env": { "EVM_PRIVATE_KEY": "0x..." }
}
}
}
// 2. Once the server is running, agents call this tool via standard MCP:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "weather.forecast",
"arguments": {
"lat": -90,
"lon": -180,
"hourly": false,
"limit": 1
}
}
}| Field | Type | Description |
|---|---|---|
ok | boolean | one of: true |
items | array | |
total | integer | Total matching rows upstream; null when unknown. |
source | object | |
meta | object |
{
"ok": true,
"items": [
{
"name": "example",
"startTime": "example",
"endTime": "example",
"isDaytime": false,
"temperature": 1,
"temperatureUnit": "example",
"windSpeed": "example",
"windDirection": "example",
"precipProbabilityPct": 1,
"shortForecast": "example",
"detailedForecast": "example"
}
],
"total": 1,
"source": {
"provider": "example",
"url": "example",
"license": "example"
},
"meta": {
"location": "example",
"forecastOffice": "example",
"updated": "example",
"periods": 1
}
}