# x402 Agent Tools API

## Overview
Pay-per-request utility endpoints for AI agents. Instant API access via x402 micropayments without key management.

## Payment
- **Token**: USDC on Base Mainnet
- **Protocol**: x402

## Endpoints

### Cryptocurrency

#### POST /api/x402-tools/crypto/price
**Price**: $0.002
Get cryptocurrency price and market data. Accepts ticker symbols (BTC, ETH, SOL) or names (bitcoin, ethereum, solana).
**Body**: {"symbol": "BTC", "currency": "usd"} or {"symbol": "bitcoin", "currency": "usd"}

#### POST /api/x402-tools/crypto/prices
**Price**: $0.003
Get prices for multiple cryptocurrencies. Accepts ticker symbols or names.
**Body**: {"symbols": ["BTC", "ETH", "SOL"], "currency": "usd"}

### Weather

#### POST /api/x402-tools/weather/current
**Price**: $0.01
Get current weather for a location. Use country code to disambiguate cities with same name.
**Body**: {"location": "London", "units": "metric"} or {"location": "Salamanca", "country": "MX"}

### Geocoding

#### POST /api/x402-tools/geocode
**Price**: $0.002
Convert address to coordinates.
**Body**: {"address": "Eiffel Tower, Paris"}

#### POST /api/x402-tools/reverse-geocode
**Price**: $0.002
Convert coordinates to address.
**Body**: {"latitude": 48.8584, "longitude": 2.2945}

### Knowledge

#### POST /api/x402-tools/wiki/search
**Price**: $0.001
Search Wikipedia articles.
**Body**: {"query": "artificial intelligence", "limit": 10}

#### POST /api/x402-tools/wiki/summary
**Price**: $0.001
Get Wikipedia article summary.
**Body**: {"title": "Machine learning"}

### News

#### POST /api/x402-tools/news/search
**Price**: $0.005
Search news articles.
**Body**: {"query": "bitcoin", "limit": 10}

### Financial

#### POST /api/x402-tools/stocks/quote
**Price**: $0.01
Get stock quote.
**Body**: {"symbol": "AAPL"}

### Shipping

#### POST /api/x402-tools/shipping/track
**Price**: $0.02
Multi-carrier package tracking. Auto-detects carrier from tracking number format, or pass `carrier` explicitly. Returns normalized JSON across all carriers with status, full event timeline, shipper/recipient, and ETA.
**Body**: {"tracking_number": "391629465360"} or {"tracking_number": "...", "carrier": "fedex"}
**Live carriers** (return real tracking data): fedex, usps, dhl
**In rollout** (creds pending — return clean error+hint until enabled): ups
**Roadmap** (return polite "coming soon" — your paid request logs demand signal): canada_post, la_poste, royal_mail, australia_post, evri, deutsche_post, postnl, china_post, japan_post, india_post, correos, poste_italiane, aramex, yodel, swiss_post, correios, ems, ontrac, amazon_shipping
**Aliases**: hermes→evri, auspost→australia_post, dhl_express→dhl, postes_canada→canada_post, etc.

## Response Caching
Responses are cached to reduce costs:
- Crypto prices: 5 minutes
- Weather: 10 minutes
- Geocoding: 1 hour
- Wikipedia: 1 hour
- News: 15 minutes
- Stocks: 5 minutes
- Shipping tracking: 5 minutes (errors not cached)

Cached responses include `"cached": true` field.

## Other x402 APIs
- **Residential Proxy**: /api/x402-proxy/docs — Fetch URLs through residential IPs
- **Uncensored AI**: /api/x402-uncensored/docs — Chat, reasoning, code, image generation
- **Crypto Tools**: /api/x402-crypto/docs — Token analysis, wallet identity, contract decoder
- **Audio**: /api/x402-audio/docs — Text-to-speech, transcription, sound effects
- **PadelMaps Data**: /api/x402/docs — Global padel club directory

## Documentation
- HTML docs: https://padelmaps.org/api/x402-tools/docs
- LLM docs: https://padelmaps.org/api/x402-tools/llm.txt
- Getting started: https://padelmaps.org/api/x402/getting-started