# ForgeMesh Fare Intelligence — Agent Interface Description
# https://travel.forgemesh.io

## Purpose
Agent-payable travel fare intelligence service.
Returns flight price observations, historical medians, and buy/wait recommendations.
Payment via x402 protocol (EIP-compliant, USDC on Base).

## Discovery
x402 manifest: https://travel.forgemesh.io/.well-known/x402.json
OpenAPI spec:  https://travel.forgemesh.io/openapi.json

## Primary Endpoint
GET /api/fare-intelligence
Required params: origin (IATA), destination (IATA)
Optional params: departure_at (YYYY-MM or YYYY-MM-DD), return_at, currency (default: USD), market (default: us)

## Payment
Protocol: x402
Price: $0.10 per query (100000 USDC micro-units, 6 decimals)
Network: base
Asset: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 (USDC)
PayTo: 0x6B1aC7935DAD576b921af0E6EDC27319bc27AAdD

## Flow
1. Agent sends GET /api/fare-intelligence?origin=JFK&destination=LAX
2. Service returns HTTP 402 with x402 payment instructions
3. Agent pays via facilitator
4. Facilitator sets X-Payment-Validated: true and forwards request
5. Service returns fare data

## Rate Limits
Unpaid: 10 requests/minute per IP
Paid: 120 requests/minute per IP
Headers: x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset

## Response Shape
{ "data": [{ "origin", "destination", "price", "currency", "found_at", "historical_median", "recommendation", "confidence" }], "count": N, "provider": "..." }

## Recommendation Values
buy_now — price < 92% of historical median
wait    — price > 104% of historical median
flexible — price within expected range