# StableTravel API

> Pay-per-request access to flights, hotels, activities, and transfers via the Amadeus API. No auth, no API keys, no subscriptions. Powered by x402 micropayments (USDC on Base).

## How It Works

Send a standard HTTP request to any endpoint. Payment is handled automatically via x402 protocol headers. No signup, no tokens, no OAuth.

## Quick Start

```bash
# Search flights from NYC to LA (GET — simple search)
npx agentcash fetch "https://stabletravel.dev/api/flights/search?originLocationCode=JFK&destinationLocationCode=LAX&departureDate=2025-06-15&adults=1&max=5"

# Search flights (POST — advanced multi-city)
npx agentcash fetch -X POST -H "Content-Type: application/json" \
  -d '{"originDestinations":[{"id":"1","originLocationCode":"JFK","destinationLocationCode":"LAX","departureDateTimeRange":{"date":"2025-06-15"}}],"travelers":[{"id":"1","travelerType":"ADULT"}],"sources":["GDS"],"searchCriteria":{"maxFlightOffers":5}}' \
  "https://stabletravel.dev/api/flights/search"
```

## Endpoints

### Flights

| Endpoint | Method | Price | Description |
|---|---|---|---|
| /api/flights/search | GET, POST | $0.05 | Search flight offers (GET for simple, POST for advanced multi-city) |
| /api/flights/price | POST | $0.03 | Confirm pricing for a flight offer |
| /api/flights/book | POST | $0.09 | Book a flight (create flight order) |
| /api/flights/orders | GET | $0.005 | Retrieve a flight order by ID |
| /api/flights/orders/cancel | DELETE | $0.005 | Cancel a flight order |
| /api/flights/seatmap | GET, POST | $0.03 | Get seat maps for a flight |
| /api/flights/upsell | POST | $0.03 | Get upsell offers for a flight |
| /api/flights/availability | POST | $0.03 | Check flight availability |
| /api/flights/status | GET | $0.005 | Get flight status by carrier, number, and date |
| /api/flights/checkin-links | GET | $0.005 | Get airline check-in page URLs |

### Hotels

| Endpoint | Method | Price | Description |
|---|---|---|---|
| /api/hotels/list | GET | $0.03 | List hotels by city code (default max 100) |
| /api/hotels/list/by-geocode | GET | $0.03 | List hotels by latitude/longitude (default max 100) |
| /api/hotels/search | GET | $0.03 | Search hotel offers by hotel IDs (use /hotels/list first to get IDs) |
| /api/hotels/search/by-hotel | GET | $0.03 | Search offers for a specific hotel ID |
| /api/hotels/offer | GET | $0.03 | Get details for a specific hotel offer |
| /api/hotels/book | POST | $0.002 | Book a hotel offer |
| /api/hotels/autocomplete | GET | $0.005 | Autocomplete hotel names |
| /api/hotels/ratings | GET | $0.05 | Get hotel sentiment ratings and reviews |

### Activities

| Endpoint | Method | Price | Description |
|---|---|---|---|
| /api/activities/search | GET | $0.05 | Search tours & activities by lat/lng (default max 50) |
| /api/activities/by-square | GET | $0.05 | Search activities within a geographic square (default max 50) |
| /api/activities/details | GET | $0.05 | Get activity details by ID |

### Transfers

| Endpoint | Method | Price | Description |
|---|---|---|---|
| /api/transfers/search | POST | $0.003 | Search airport transfer options |
| /api/transfers/book | POST | $0.002 | Book a transfer |
| /api/transfers/cancel | POST | $0.002 | Cancel a transfer booking |

### Reference Data

| Endpoint | Method | Price | Description |
|---|---|---|---|
| /api/reference/locations | GET | $0.005 | Search locations (airports, cities) by keyword |
| /api/reference/airports | GET | $0.005 | Find nearby airports by latitude/longitude |
| /api/reference/airlines | GET | $0.005 | Look up airline by IATA code |
| /api/reference/airline-routes | GET | $0.005 | Get routes for an airline from an airport (default max 50) |
| /api/reference/airport-routes | GET | $0.005 | Get direct destinations from an airport (default max 50) |
| /api/reference/cities | GET | $0.005 | Search cities by keyword |

## Common Parameters

### Flight Search (GET)
- **originLocationCode** (required): IATA origin airport code (e.g. JFK)
- **destinationLocationCode** (required): IATA destination airport code (e.g. LAX)
- **departureDate** (required): Departure date (YYYY-MM-DD)
- **adults** (required): Number of adult travelers (1-9)
- **returnDate**: Return date for round-trip (YYYY-MM-DD)
- **travelClass**: ECONOMY, PREMIUM_ECONOMY, BUSINESS, or FIRST
- **nonStop**: Filter non-stop flights only (true/false)
- **currencyCode**: Currency code (e.g. USD)
- **maxPrice**: Maximum price filter
- **max**: Maximum number of results

### Flight Search (POST)
The POST body requires `originDestinations` and `travelers` arrays:
```json
{
  "originDestinations": [{ "id": "1", "originLocationCode": "JFK", "destinationLocationCode": "LAX", "departureDateTimeRange": { "date": "2025-06-15" } }],
  "travelers": [{ "id": "1", "travelerType": "ADULT" }],
  "sources": ["GDS"],
  "searchCriteria": { "maxFlightOffers": 5 }
}
```

### Flight Price (POST)
Pass the full flight offer from a search result. Body must use `type: "flight-offers-pricing"`:
```json
{ "data": { "type": "flight-offers-pricing", "flightOffers": [ <flight-offer-object> ] } }
```

### Flight Upsell (POST)
Body must use `type: "flight-offers-upselling"`:
```json
{ "data": { "type": "flight-offers-upselling", "flightOffers": [ <flight-offer-object> ] } }
```

### Flight Seatmap (POST)
Body wraps flight offers in a `data` array:
```json
{ "data": [ <flight-offer-object> ] }
```

### Flight Status
- **carrierCode** (required): Airline IATA code (e.g. AA)
- **flightNumber** (required): Flight number (e.g. 100)
- **scheduledDepartureDate** (required): Date (YYYY-MM-DD)

### Hotel List
- **cityCode** (required): IATA city code (e.g. PAR, LON, NYC)
- **max**: Maximum results (default 100)
- **radius**: Search radius
- **ratings**: Comma-separated star ratings (1-5)

### Hotel List by Geocode
- **latitude** (required): Latitude coordinate
- **longitude** (required): Longitude coordinate
- **max**: Maximum results (default 100)

### Hotel Search
- **hotelIds** (required): Comma-separated Amadeus hotel IDs (get these from /hotels/list)
- **checkInDate**: Check-in date (YYYY-MM-DD)
- **checkOutDate**: Check-out date (YYYY-MM-DD)
- **adults**: Number of adults (default 1)

### Activities Search
- **latitude** (required): Latitude coordinate
- **longitude** (required): Longitude coordinate
- **radius**: Search radius in km (default 1)
- **max**: Maximum results (default 50)

### Activities by Square
- **north** (required): Northern latitude boundary
- **south** (required): Southern latitude boundary
- **east** (required): Eastern longitude boundary
- **west** (required): Western longitude boundary
- **max**: Maximum results (default 50)

### Transfers Search (POST)
```json
{
  "startLocationCode": "CDG",
  "endAddressLine": "Avenue des Champs-Elysees 1",
  "endCityName": "Paris",
  "endZipCode": "75008",
  "endCountryCode": "FR",
  "endGeoCode": "48.8566,2.3522",
  "transferType": "PRIVATE",
  "startDateTime": "2025-06-15T10:00:00",
  "passengers": 2
}
```
Note: Drop-off requires either full address fields (endAddressLine + endCityName + endCountryCode) or endGeoCode, or both.

### Reference Locations
- **keyword** (required): Search keyword (city or airport name)
- **subType** (required): AIRPORT, CITY, or AIRPORT,CITY

### Airline / Airport Routes
- **airlineCode** or **departureAirportCode** (required): IATA code
- **max**: Maximum results (default 50)

## Typical Workflows

1. **Book a flight**: search → price → book
2. **Book a hotel**: list (get hotel IDs) → search (get offer IDs) → offer (confirm details) → book
3. **Find activities**: search by lat/lng or by-square → details (by activity ID)
4. **Book a transfer**: search → book

## Authentication

No API keys needed. Payment via USDC on Base network (x402 protocol) serves as authentication. Use `npx agentcash fetch` for automatic payment handling.

## OpenAPI Spec

Full schema available at `/openapi.json`