# PadelMaps x402 API

## Overview
Pay-per-request API for global padel club data and open matches.
Access 15,000+ clubs across 89+ countries with detailed information.

## Payment Protocol: x402

- **Payment Token**: USDC on Base Mainnet
- **Chain ID**: 8453
- **Price**: $0.01 USD per request
- **Receiving Address**: 0xd8bA61a0b0974db0EC8E325C7628470526558E9B
- **Facilitator**: PayAI Network (https://facilitator.payai.network)
- **Features**: Gasless transactions, 0% fees, ERC-3009 transferWithAuthorization

## How to Use

1. Make a POST request to any endpoint with JSON body (will return 402 Payment Required)
2. Payment client reads the 402 response with payment requirements
3. User signs a gasless USDC transfer (ERC-3009)
4. Client retries POST request with X-PAYMENT header containing the signature
5. API validates payment and returns data

## Testing Tools

- x402scan.com - Web interface for testing x402 APIs
- x402 CLI - Command-line tool for x402 requests
- Custom integration - Use official x402 SDK

## API Endpoints

All endpoints require $0.01 USDC payment except /docs

All endpoints use POST with JSON body parameters.

---

### Countries

#### POST /api/x402/countries
**Price**: $0.01 USD
**Description**: Get list of countries with padel clubs

**Body Parameters**:
- None required (empty JSON object `{}`)

**Response Example**:
```json
{
  "count": 89,
  "countries": [
    {"country_slug": "spain", "club_count": 4852},
    {"country_slug": "italy", "club_count": 1375}
  ]
}
```

**Refundable variant**: `POST /api/x402r/countries` ($0.02, commerce scheme with 10-minute refund window). Uses `scheme: "commerce"` on Base mainnet. Requires `@x402r/evm` client SDK with commerce scheme registered.

**All escrow endpoints**: 36 external-API endpoints have refundable variants. Replace `x402-` with `x402r-` in the URL (e.g., `/api/x402r-crypto/token-metadata`). See full list at `/api/x402-expat/`.

---

### Clubs in City

#### POST /api/x402/clubs
**Body Parameters**:
- city (string, required): City name, e.g., "barcelona"
- country (string, optional): Country name to disambiguate cities with same name (e.g., "spain", "mexico")
- limit (integer, optional): Max results (default: 50, max: 100)

**Price**: $0.01 USD
**Description**: Get all clubs in a city

**Example Body**:
```json
{"city": "barcelona", "limit": 50}
```
or with country disambiguation:
```json
{"city": "salamanca", "country": "mexico", "limit": 50}
```

**Response Example**:
```json
{
  "city": "barcelona",
  "count": 87,
  "clubs": [{
    "id": 123,
    "name": "Padel Barcelona",
    "address": "Carrer de Provença, 123, Barcelona",
    "latitude": 41.3851,
    "longitude": 2.1734,
    "google_rating": 4.5,
    "slug": "/spain/barcelona/padel-barcelona"
  }]
}
```

---

### Club Details

#### POST /api/x402/club
**Body Parameters** (use club_id OR name):
- club_id (integer): Club ID, e.g., 1238
- name (string): Club name to search for, e.g., "La Moraleja Padel Club"
- city (string, optional): City to narrow name search, e.g., "Madrid"
- country (string, optional): Country to narrow name search, e.g., "spain"

**Price**: $0.01 USD
**Description**: Get detailed club information including courts, pricing, amenities, and match counts

**Example Body** (by ID):
```json
{"club_id": 1238}
```

**Example Body** (by name):
```json
{"name": "La Moraleja Padel Club", "city": "Madrid"}
```

**Response Example**:
```json
{
  "id": 1238,
  "name": "TEMPO Padel & Pickleball Club",
  "address": "123 Court Street",
  "latitude": 54.5169954,
  "longitude": -1.3182519,
  "google_rating": 4.8,
  "website": "https://tempo-padel.com",
  "phone": "+44 1234 567890",
  "photo_count": 14,
  "total_matches_count": 200,
  "open_matches_count": 62,
  "indoor_courts": 3,
  "outdoor_courts": 2,
  "peak_hour_price": "38.0",
  "currency": "GBP",
  "has_parking": true,
  "has_restaurant": true
}
```

---

### Club Photos

#### POST /api/x402/club/photos
**Body Parameters** (use club_id OR name):
- club_id (integer): Club ID, e.g., 8624
- name (string): Club name to search for, e.g., "AC PADEL LUGO"
- city (string, optional): City to narrow name search
- country (string, optional): Country to narrow name search

**Price**: $0.01 USD
**Description**: Get all photos for a club with URLs and metadata

**Example Body** (by ID):
```json
{"club_id": 8624}
```

**Response Example**:
```json
{
  "club_id": 8624,
  "club_name": "AC PADEL LUGO",
  "photo_count": 14,
  "photos": [{
    "id": 82807,
    "url": "https://padelmaps.org/uploads/club_photos/8624/photo.jpg",
    "photo_type": "google",
    "width": 1600,
    "height": 1200,
    "is_primary": true
  }]
}
```

---

### Open Matches

#### POST /api/x402/matches
**Body Parameters**:
- city (string, required): City name, e.g., "barcelona"
- limit (integer, optional): Max results (default: 50, max: 100)

**Price**: $0.01 USD
**Description**: Get open matches in a city (all platforms: Playtomic, Raketo, etc.)

**Example Body**:
```json
{"city": "madrid", "limit": 50}
```

**Response Example**:
```json
{
  "city": "barcelona",
  "count": 157,
  "matches": [{
    "id": "abc123",
    "club_name": "Padel Barcelona",
    "start_time": "2025-11-23T10:00:00Z",
    "end_time": "2025-11-23T11:30:00Z",
    "available_spots": 2,
    "price": "19.00",
    "currency": "EUR",
    "min_level": 2.5,
    "max_level": 4.0
  }]
}
```

---

## Data Coverage

- **Countries**: 89+ countries worldwide
- **Clubs**: 15,000+ padel clubs
- **Photos**: 87,000+ club photos
- **Matches**: Active open matches from Playtomic and Raketo platforms

## Rate Limits

No artificial rate limiting - pay $0.01 USDC per request. Use as much or as little as you need.

## Other x402 APIs
- **Cloud Browser**: /api/x402-browser/docs — Rendered HTML, screenshots, text extraction, PDFs
- **Residential Proxy**: /api/x402-proxy/docs — Fetch URLs through residential IPs
- **Agent Tools**: /api/x402-tools/docs — Weather, crypto, news, geocoding
- **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

## Support & Resources

- Website: https://padelmaps.org
- GitHub: https://github.com/onchainexpat/padelclublist
- x402 Documentation: https://x402.org/docs
- Test Tool: https://x402scan.com
- Getting Started Guide: https://padelmaps.org/api/x402/getting-started

---

Generated for LLMs and AI agents. For human-readable docs, visit https://padelmaps.org/api/x402/docs