# ShippingRates Shipping Intelligence API
# https://api.shippingrates.org
# x402 v2 Payment Protocol — USDC on Base Mainnet + Solana Mainnet

## Free Endpoints (no payment required)
GET /api/stats — Database statistics (record counts, shipping lines, countries)
GET /api/lines — List all 8 carriers with per-country breakdowns
GET /api/search?keyword=X — Search shipping data by keyword
GET /api/fx?from=USD&to=INR — Currency exchange rates

## Paid Endpoints (x402 — USDC on Base or Solana)
POST /api/dd/calculate — D&D cost calculation ($0.10/call)
POST /api/dd/compare — Cross-line D&D comparison ($0.25/call)
POST /api/local-charges — Port local charges ($0.05/call)
POST /api/inland-search — Inland transport route search ($0.03/call)
POST /api/cfs — CFS handling tariffs ($0.05/call)
POST /api/inland — Inland haulage rates ($0.05/call)
GET /api/port?code=INNSA — Port details ($0.01/call)
GET /api/transit?origin=INNSA&destination=AEJEA — Transit times ($0.02/call)
GET /api/rates?origin=INNSA&destination=AEJEA&container_type=40HC — Freight rates ($0.03/call)
GET /api/surcharges?line=maersk&country=IN — Surcharges ($0.02/call)
GET /api/congestion?port=INNSA — Port congestion ($0.02/call)
GET /api/reliability?line=maersk — Schedule reliability ($0.02/call)
GET /api/vessel-schedule?port=INNSA — Vessel schedule ($0.02/call)
GET /api/regulatory?country=IN — Regulatory updates ($0.01/call)
GET /api/total-cost?line=maersk&origin=INNSA&destination=AEJEA&container_type=40HC — Full landed cost ($0.15/call)
POST /api/transit-schedules — Transit schedules by carrier ($0.03/call)
POST /api/facilities — ICD/CFS facility directory ($0.02/call)
POST /api/congestion-news — Port congestion news alerts ($0.02/call)
POST /api/inland/compare — Compare inland haulage rates ($0.08/call)
POST /api/risk-score — Route risk score with chokepoint analysis ($0.10/call)

## Free Tier
25 free requests per month per IP across all paid endpoints. No signup required.
After 25 requests, pay-per-call via x402 (USDC on Base or Solana).
Headers: X-Free-Tier-Remaining, X-Free-Tier-Resets (included in responses).

## Payment Info
Protocol: x402 v2 (dual-chain)
Networks: Base Mainnet (eip155:8453) + Solana Mainnet (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp)
Asset: USDC
Base Pay To: 0x8c9e0882b4c6e6568fe76F16D59F7E080465E5C8
Solana Pay To: Gcv56hKWuEGmXheBpJxAwQxvX6QAMimZzzVrHaVCbNWE
Facilitator: https://facilitator.payai.network

## MCP Server
Connect AI agents: https://mcp.shippingrates.org/mcp
Config: { "mcpServers": { "shippingrates": { "url": "https://mcp.shippingrates.org/mcp" } } }

## Carriers Covered
maersk, msc, cma-cgm, hapag-lloyd, one, cosco, zim, evergreen

## Countries Covered (158)
Global coverage across 158 countries — full list at /api/lines

## Error Codes
200 — Success
402 — Payment Required (x402 settlement needed; your x402 client handles this automatically)
429 — Rate Limited (too many requests; check Retry-After header)
401 — Unauthorized (invalid or missing authentication)
400 — Bad Request (missing required parameters)
500 — Internal Server Error

## Sample Requests
curl https://api.shippingrates.org/api/stats
curl https://api.shippingrates.org/api/lines
curl "https://api.shippingrates.org/api/search?keyword=mumbai"

## Machine-Readable Discovery
OpenAPI Spec: https://api.shippingrates.org/openapi.json
Agent Discovery: https://api.shippingrates.org/.well-known/agents.json
x402 Discovery: https://api.shippingrates.org/.well-known/x402.json
AI Permissions: https://api.shippingrates.org/ai.txt
Full Documentation: https://api.shippingrates.org/llms-full.txt

## Terms of Service
https://shippingrates.org/terms