# FishPulse — Full API Documentation
# https://fishpulse.waltsoft.net
# Real-time fishing & outdoor conditions scored 0-100.

## Service Overview
FishPulse scores fishing conditions 0-100 using real-time weather, water temperature, barometric pressure, and tide data. Includes species-specific intelligence for 12+ freshwater and saltwater species.

## Endpoints

### GET /v1/conditions?lat={lat}&lon={lon}&activity=fishing
Real-time fishing conditions with score, species intel, and optimal window.
- Price: $0.05/query (50000 atomic USDC)
- Required params: lat, lon
- Optional params: activity (default: fishing)

### GET /v1/forecast?lat={lat}&lon={lon}&days=7
Multi-day fishing forecast with daily scores and best windows.
- Price: $0.05/query (50000 atomic USDC)
- Required params: lat, lon
- Optional params: days (1-14, default: 7), activity

### GET /v1/compare?spots=lat1,lon1;lat2,lon2
Compare fishing conditions across multiple spots (up to 5).
- Price: $0.05/query (50000 atomic USDC)
- Required params: spots (semicolon-separated lat,lon pairs)
- Optional params: activity

### GET /v1/species/{name}
Species temperature and pressure preferences. FREE — no auth required.
- Price: Free
- Available: largemouth_bass, smallmouth_bass, trout, walleye, catfish, bluegill, crappie, pike, musky, striped_bass, redfish, snook

### GET /health
Service health check. No authentication required.

## Authentication

### x402 Protocol (AI Agents)
Pay per request with no signup. Include payment proof in X-PAYMENT or PAYMENT-SIGNATURE header.
- Chains: Solana USDC, Base USDC
- Solana payTo: GsKr5q9TmiJQcEgUpBp2X6SmvSg3dnXuw2uxYJxgPTk8
- Base payTo: 0x318A4B4764eb37c3FCBcE434713128143815FD57

### API Key
Header: Authorization: Bearer fi_live_*
Purchase at https://fishpulse.waltsoft.net (Stripe checkout).
Tiers: Starter (100 queries, $5), Pro (500 queries, $20), Enterprise (2000 queries, $75).

## Pricing
| Endpoint        | Price  | Atomic USDC |
|-----------------|--------|-------------|
| /v1/conditions  | $0.05  | 50000       |
| /v1/forecast    | $0.05  | 50000       |
| /v1/compare     | $0.05  | 50000       |
| /v1/species/*   | Free   | —           |

## Example Response (/v1/conditions)
```json
{
  "score": 78,
  "verdict": "Good — go fishing",
  "explanation": "Water temp 68°F (ideal for bass), wind 8mph SW, barometric falling",
  "conditions": {
    "water_temp_f": 68,
    "air_temp_f": 74,
    "wind_mph": 8,
    "wind_dir": "SW",
    "barometric_hpa": 1013,
    "pressure_trend": "falling",
    "tide_state": "incoming",
    "aqi": 42,
    "uv_index": 6
  },
  "species_intel": {
    "largemouth_bass": { "rating": "excellent", "reason": "65-75°F sweet spot" },
    "trout": { "rating": "fair", "reason": "water above 60°F threshold" }
  },
  "optimal_window": "Next 3 hours",
  "location": { "lat": 35.22, "lon": -80.84 },
  "timestamp": "2026-07-23T00:00:00.000Z"
}
```

## Data Sources
- NOAA National Data Buoy Center (NDBC) — water temperature, wave data
- USGS National Water Information System (NWIS) — stream flow, water levels
- National Weather Service (NWS) — forecasts, wind, pressure
- EPA — air quality index

## Rate Limits
- x402: No rate limit (pay per request)
- API key: 30 requests/minute
- Demo (/tryit): 3/day per IP

## Discovery Endpoints
- /llms.txt — Summary for LLMs
- /llms-full.txt — This document
- /agents.md — Agent briefing (Shopify 2026 standard)
- /robots.txt — Bot directives
- /.well-known/x402 — Payment discovery
- /.well-known/agent.json — Agent card