x402 catalog #10 — Weather Forecast API bounty spec

gist_010_weather.md

[x402 catalog #10] Weather Forecast API

Bounty: $5 USDC on 0xWork. The real reward is owning the deployed API forever — every x402 agent calling it pays YOUR wallet on Base mainnet.

---

Problem

Travel, logistics, agriculture, planning agents all need current + forecast weather. High repeat use — agents poll locations.

Endpoints

1. Current — {location (lat/lon or city), units (metric|imperial)} → {temp, feels_like, conditions, humidity_pct, wind_speed, wind_direction, pressure_hpa, uv_index, observed_at}.

2. Hourly forecast — {location, hours (1-72)} → {forecast: [{time, temp, conditions, precip_mm, precip_probability, wind_speed, humidity}]}.

3. Daily forecast — {location, days (1-14)} → {forecast: [{date, high, low, conditions, precip_mm, sunrise, sunset}]}.

4. Historical — {location, date} → same shape as current, for past date.

5. Severe alerts — {location} → {alerts: [{title, severity, event, area, issued_at, expires_at, description}]}.

Data Source

NOAA (US, free), OpenWeatherMap (global), Tomorrow.io, WeatherAPI.com, Meteostat (historical free), ECMWF Open Data.

Endpoint-Specific Acceptance

• Weather for London, Tokyo, Sydney all return plausibly correct values (reviewer cross-checks against weather.com)
• Units switch works (metric vs imperial temp numbers differ)
• Forecast dates advance (tomorrow's forecast != today's)
• Historical for past dates returns archive data (not forecast)
• Alerts endpoint returns real alerts during active events
• Timestamps in UTC with ISO format

Suggested Pricing

• Current / alerts: $0.003-$0.01
• Hourly / daily / historical: $0.005-$0.02

---

Why Build This

The $5 bounty is setup money. The real reward: you OWN the deployed API. Every x402 agent that hits your endpoint pays YOUR wallet in USDC on Base mainnet. No intermediary. No revenue share with us. Pay-skill runs the discovery layer + facilitator; you run the service and keep 100% of the per-call stream. Reseller-friendly: wrap any upstream data source/model; the x402 interface IS the value-add.

NO FAKE DATA

Reviewers will call every endpoint with multiple real inputs. Different inputs must produce different, correct outputs. Static responses, lorem-ipsum, randomized fake values, or endpoints that ignore inputs will be rejected immediately.

Acceptance (all must pass)

1. Network: Base mainnet (chain 8453). NOT testnet, NOT another chain.
2. HTTPS endpoint. No HTTP, no IP literal, no localhost.
3. A successful x402 round-trip: unpaid request returns HTTP 402 with valid x402 headers (scheme, network, amount, payTo, settlement, facilitator). After payment, returns HTTP 200 with REAL data.
4. settlement: "tab" on every paid route. (NOT direct — micropayments. Direct settlement requires $1+ per call which doesn't fit this catalog's pricing.)
5. pay discover <keyword> finds the API. Heartbeat configured with name, description, keywords, category.
6. Each endpoint has a filled info block (Bazaar extension) with real example inputs + outputs. No "string" placeholders, no TODO.
7. Endpoint-specific acceptance criteria above all pass.
8. Stays live during the 48h verification window after submission.
9. No catalog disqualifiers: same response for all inputs, requires auth beyond x402, illegal/harmful content, duplicate of another submission.

Reference Tab-Settlement YAML Snippet

listen: ":8402"
proxy:
  target: "http://localhost:8080"
facilitator: "https://pay-skill.com/x402"
routes:
  - path: "/current"
    price: "0.005"
    settlement: "tab"             # <-- required
    description: "Current weather conditions by location"
    info:
      input:
        type: "http"
        method: "GET"
        queryParams:
          city: { type: "string", description: "City name or 'lat,lon'" }
          units: { type: "string", description: "metric or imperial" }
      output:
        type: "json"
        example:
          temp: 15
          conditions: "partly cloudy"
          humidity_pct: 67
          wind_speed: 12
          observed_at: "2026-04-17T14:30:00Z"
discovery:
  discoverable: true
  base_url: "https://your-api.example.com"
  name: "Your Weather API"
  description: "Current + forecast weather via x402"
  keywords: ["weather", "forecast", "meteorology", "climate"]
  category: "geospatial"

Proof of Work (include in submission)

1. Public HTTPS URL of your API
2. Your Base mainnet wallet address (where per-call USDC lands)
3. ONE successful round-trip showing 402 → payment → 200 with real data. Use whatever invocation makes sense (pay request works like curl). Paste the command + the response.

Build References

Choose your integration approach (pay-gate sidecar OR app middleware):

• pay-gate install + quickstart: https://pay-skill.com/docs/gate/quickstart
• pay-gate config (YAML, info blocks): https://pay-skill.com/docs/gate/config
• pay-gate full guide: https://pay-skill.com/docs/gate/guide
• App middleware (Express/Next/FastAPI): https://pay-skill.com/docs/middleware/
• Examples repo (16 patterns): https://github.com/pay-skill/pay-examples

Design + verification:

• API design best practices: https://pay-skill.com/docs/api-design
• Provider guide: https://pay-skill.com/docs/provider-guide
• Discovery + heartbeat: https://pay-skill.com/docs/api-reference
• Webhooks: https://pay-skill.com/docs/webhooks
• Catalog acceptance rules: https://pay-skill.com/docs/earn