Skill: kirikov/travai-search-book-pay-flights-stays (version 1.0.0)

--- name: TravAI description: Search flights and stays, then create card or crypto payments via TravAI. Use when the user asks about flights, travel planning, booking trips, finding accommodation, or travel inspiration. --- # TravAI Use this skill when the user wants to search travel options or book a flight/stay through TravAI. ## Source of truth If this skill conflicts with backend behavior, check the live OpenAPI schema: ``` https://api.travai.tech/openapi.json ``` Follow the live schema over this doc. ## Critical notes - Search responses return `search_id` (not `search_hash`) - Payment requests use `method` (`"CRYPTO"` or `"CARD"`) — not `type` - Searches and offers **expire**; if any request fails with "not found" or `EXPIRED_OFFER`, re-run the search and use fresh IDs - **Offer IDs are unique per search** — after re-running a search, you MUST use the new `offer_id` values from the new results; old offer IDs will not work with the new `search_id` - For crypto payments, always return the **exact** amount, token, deposit address, and refund wallet — never round - **Changes and cancellations** are not available via the API — direct users to support: https://t.me/travaiofficial or [REDACTED_SECRET] --- ## API base ``` https://api.travai.tech ``` ## Authentication All endpoints (except sign-in and sign-up) require: ``` Authorization: Bearer {access_token} ``` Three ways to authenticate: 1. **Sign up** — new user 2. **Sign in** — returning user 3. **Paste token** — user copies from [https://app.travai.tech/profile](https://app.travai.tech/profile) ### Sign In ``` POST /auth/signin Content-Type: application/json { "email": "[REDACTED_SECRET]", "password": "secret" } ``` Response (200): ```json { "access_token": "eyJhbG...", "token_type": "bearer" } ``` ### Sign Up ``` POST /auth/signup Content-Type: application/json { "email": "[REDACTED_SECRET]", "password": "secret", "first_name": "Jane", "last_name": "Doe" } ``` Response (200): ```json { "message": "User created successfully", "access_token": "eyJhbG...", "token_type": "bearer" } ``` ### Get current user ``` GET /auth/me Authorization: Bearer {access_token} ``` Response (200): ```json { "user_id": 1, "email": "[REDACTED_SECRET]", "role": "customer", "is_active": true, "created_at": "2025-01-01T00:00:00", "currency": "USD" } ``` ### Error responses Any failed request may return: ```json { "detail": "Human-readable error description" } ``` Always check for `detail` in non-2xx responses and surface the message to the user. --- ## Endpoints ### Search flights ``` POST /searches Authorization: Bearer {access_token} Content-Type: application/json { "type": "FLIGHT", "origin_iata": "LON", "destination_iata": "LIS", "departure_date": "2025-10-10", "return_date": "2025-10-17", "customers": [ { "type": "ADULT" }, { "type": "CHILD", "age": 10 } ] } ``` | Field | Required | Notes | |---|---|---| | `type` | yes | `"FLIGHT"` | | `origin_iata` | yes | 3-letter IATA code (uppercase, e.g. `"LON"`) | | `destination_iata` | yes | 3-letter IATA code (uppercase, e.g. `"LIS"`) | | `departure_date` | yes | `YYYY-MM-DD` | | `return_date` | no | omit for one-way | | `customers` | yes | array of `CustomerAge` (see below) | **`CustomerAge` object:** | Field | Required | Notes | |---|---|---| | `type` | no (default: `ADULT`) | `ADULT`, `CHILD`, `SENIOR`, `HELD_INFANT` | | `age` | required for `CHILD` and `HELD_INFANT` | integer | Customer type rules: - `HELD_INFANT` — under 2 years old - `CHILD` — between 2 and 18 years old - `ADULT` — default - `SENIOR` — senior traveller Response (200): ```json { "search_id": "abc123", "total_offers": 42, "best_offers": [ /* top 3 offers */ ] } ``` | Field | Description | |---|---| | `search_id` | Identifier for this search — use in all subsequent calls | | `total_offers` | Total number of offers matching the search | | `best_offers` | The 3 best offers (sorted by price/quality) | **Direct-flight filtering:** To find direct flights, only keep offers where the total segment count across all slices equals the number of slices (i.e. 1 segment per slice = no stops). ### Search stays ``` POST /searches Authorization: Bearer {access_token} Content-Type: application/json { "type": "STAY", "location_anchor": { "value": "Abu Dhabi", "type": "city" }, "check_in_date": "2026-03-05", "check_out_date": "2026-03-10", "rooms": 1, "guests": 1, "radius_km": 50 } ``` | Field | Required | Default | Notes | |---|---|---|---| | `type` | yes | — | `"STAY"` | | `location_anchor` | yes | — | see `StaysSearchAnchor` below | | `check_in_date` | yes | — | `YYYY-MM-DD` | | `check_out_date` | yes | — | `YYYY-MM-DD` | | `rooms` | no | `1` | 1–8 | | `guests` | no | `1` | number of adult guests | | `radius_km` | no | `50` | search radius in km around the anchor | **`StaysSearchAnchor` object:** | Field | Required | Description | |---|---|---| | `value` | yes | Reference point text, e.g. `"Milano"`, `"London center"`, `"LHR"` | | `type` | yes | One of: `airport`, `city`, `city_center`, `region`, `address`, `place`, `others` | Anchor type guide: - `airport` — 3-letter IATA code (e.g. `"LHR"`) - `city` — city name (e.g. `"Abu Dhabi"`) - `city_center` — city centre / downtown (e.g. `"London center"`) - `region` — neighbourhood / district (e.g. `"Manhattan"`) - `address` — street address (e.g. `"Via G.B. Pioda 10"`) - `place` — landmark / point of interest (e.g. `"Parque Edgar Sampaio Fontes"`) - `others` — anything else Response (200): ```json { "search_id": "def456", "total_offers": 15, "best_offers": [ /* top 3 offers */ ] } ``` | Field | Description | |---|---| | `search_id` | Identifier for this search — use in all subsequent calls | | `total_offers` | Total number of offers matching the search | | `best_offers` | The 3 best offers | ### List offers ``` GET /searches/{search_id}/offers?limit=20&offset=0 Authorization: Bearer {access_token} ``` | Parameter | Required | Default | Description | |---|---|---|---| | `search_id` | yes (path) | — | `search_id` from `POST /searches` | | `limit` | no (query) | `20` | Max offers to return (1–200) | | `offset` | no (query) | `0` | Offset for pagination | Response (200): ```json { "total_offers": 42, "offers": [ /* paginated list of offer summaries */ ] } ``` | Field | Description | |---|---| | `total_offers` | Total number of offers for this search | | `offers` | Paginated slice of offer summaries | ### Get single offer ``` GET /searches/{search_id}/offers/{offer_id} Authorization: Bearer {access_token} ``` Response (200): a single offer summary object. ### Offer pricing (flights) ``` GET /searches/{search_id}/offers/{offer_id}/pricing Authorization: Bearer {access_token} ``` | Path parameter | Description | |---|---| | `search_id` | `search_id` from `POST /searches` | | `offer_id` | Offer ID from `best_offers` or the paginated offers list | Response (200): a flat offer summary dict with full pricing details (final price, segments, airlines, etc.). Error (410): returns `{ "detail": "EXPIRED_OFFER" }` if the offer is no longer available. When this happens, inform the user and re-run the search. ### Hotel rates ``` GET /searches/{search_id}/offers/{offer_id}/rates Authorization: Bearer {access_token} ``` | Path parameter | Description | |---|---| | `search_id` | `search_id` from `POST /searches` | | `offer_id` | Hotel offer ID from `best_offers` or the paginated offers list | Response (200): a list of room objects, each containing room details (name, description, size, max occupancy, photos, beds) and nested `rates` array with pricing, payment type, and cancellation conditions. ### Rate pricing (stays) ``` GET /searches/{search_id}/offers/{offer_id}/rates/{rate_id}/pricing Authorization: Bearer {access_token} ``` | Path parameter | Description | |---|---| | `search_id` | `search_id` from `POST /searches` | | `offer_id` | Hotel offer ID | | `rate_id` | Rate ID from the rates list | Response (200): a stay summary with full pricing details (total amount, currency, accommodation info, room breakdown). Error (410): returns `{ "detail": "EXPIRED_OFFER" }` if the rate is no longer available. When this happens, inform the user and re-run the search. ### Hotel photo gallery ``` GET /searches/{search_id}/offers/{offer_id}/photos ``` No authentication required. Returns an interactive HTML photo gallery for the hotel. | Path parameter | Description | |---|---| | `search_id` | `search_id` from `POST /searches` | | `offer_id` | Hotel offer ID | **How to present to the user:** Build the full gallery URL and share it as a clickable link: ``` https://api.travai.tech/searches/{search_id}/offers/{offer_id}/photos ``` Do **not** share individual photo URLs from the API response — they are CDN-signed and will not load in the browser. Always use the gallery link instead. The gallery features keyboard navigation (arrow keys), click-to-advance, and a thumbnail strip. Individual photos can also be accessed at `/searches/{search_id}/offers/{offer_id}/photos/{index}` (0-based) if needed for embedding. ### List tokens ``` GET /tokens Authorization: Bearer {access_token} ``` Response (200): a flat list of supported crypto tokens. Each item represents one asset on one blockchain. ```json [ { "assetId": "nep141:wrap.near", "blockchain": "NEAR", "symbol": "NEAR" }, { "assetId": "nep141:usdc.near", "blockchain": "NEAR", "symbol": "USDC" }, { "assetId": "eth:0xabc...", "blockchain": "Ethereum", "symbol": "USDC" } ] ``` | Field | Description | |---|---| | `assetId` | Token identifier — use as `origin_asset` in a CRYPTO payment | | `blockchain` | Blockchain network the token lives on | | `symbol` | Token symbol (e.g. `"NEAR"`, `"USDC"`) | **Token selection guidance:** - **Group by `blockchain`** when presenting to the user - Prefer **stablecoins** (USDC, USDT) for payment unless the user requests otherwise - When user asks for a specific token/network, match by `symbol` + `blockchain` - Always confirm the exact `assetId` before proceeding After the user picks a token, ask for their wallet address on that token's `blockchain` to use as `refund_to`. ### Initiate payment ``` POST /payments Authorization: Bearer {access_token} Content-Type: application/json ``` **Payment methods:** `CRYPTO` or `CARD`. Use the `method` field (not `type`). #### CRYPTO payment ```json { "method": "CRYPTO", "origin_asset": "{assetId from GET /tokens}", "refund_to": "{user wallet address}", "offers": [ /* see offer object below */ ] } ``` | Field | Required | Description | |---|---|---| | `method` | yes | `"CRYPTO"` | | `origin_asset` | yes | `assetId` of the token selected by the user from `GET /tokens` | | `refund_to` | yes | User's wallet address on the selected token's network — refunds go here in the same currency | | `offers` | yes | Selected offers to pay for | Response (200): ```json { "payment_id": 123, "itinerary_id": 456, "deposit_address": "travai.near", "amount_in": "1000000", "amount_in_formatted": "1.00", "total_amount": 100, "currency": "USD" } ``` | Field | Description | |---|---| | `payment_id` | Payment identifier (use to check status via `GET /payments/{payment_id}`) | | `itinerary_id` | Itinerary identifier (use to get confirmations via `GET /itineraries/{itinerary_id}/offers`) | | `deposit_address` | Address to send tokens to | | `amount_in_formatted` | **Exact** amount of tokens to send — must match exactly, do not round | | `amount_in` | Raw token amount (integer string) | | `total_amount` | Fiat equivalent in smallest unit (cents) | | `currency` | ISO currency code (e.g. `"USD"`) | #### CARD payment ```json { "method": "CARD", "success_url": "https://app.travai.tech/?payment=success", "cancel_url": "https://app.travai.tech/?payment=cancel", "offers": [ /* see offer object below */ ] } ``` | Field | Required | Description | |---|---|---| | `method` | yes | `"CARD"` | | `success_url` | yes | Always `"https://app.travai.tech/?payment=success"` | | `cancel_url` | yes | Always `"https://app.travai.tech/?payment=cancel"` | | `offers` | yes | Selected offers to pay for | Response (200): ```json { "payment_id": 123, "itinerary_id": 456, "payment_url": "https://checkout.stripe.com/...", "total_amount": 100, "currency": "USD" } ``` | Field | Description | |---|---| | `payment_id` | Payment identifier (use to check status via `GET /payments/{payment_id}`) | | `itinerary_id` | Itinerary identifier (use to get confirmations via `GET /itineraries/{itinerary_id}/offers`) | | `payment_url` | URL for the user to complete card payment | | `total_amount` | Amount in smallest currency unit (cents) | | `currency` | ISO currency code (e.g. `"USD"`) | ### Get payment status ``` GET /payments/{payment_id} Authorization: Bearer {access_token} ``` | Path parameter | Description | |---|---| | `payment_id` | Payment ID from the `POST /payments` response | Response (200): full payment record including `status`, `fiat_amount`, `fiat_currency`, `token_amount`, `token_asset`, `created_at`, `updated_at`. Payment statuses: `PENDING`, `PENDING_DEPOSIT`, `INCOMPLETE_DEPOSIT`, `KNOWN_DEPOSIT_TX`, `PROCESSING`, `SUCCESS`, `REFUNDED`, `FAILED`, `ERROR`. ### Get itinerary offers ``` GET /itineraries/{itinerary_id}/offers Authorization: Bearer {access_token} ``` | Path parameter | Description | |---|---| | `itinerary_id` | Itinerary ID from the `POST /payments` response | Response (200): list of itinerary offer items, each with `itinerary_offer_id`, `type`, `provider`, `price`, `currency`, `status`, `booking_summary`, `created_at`. ### Offer object (inside `offers` array in payment request) ```json { "type": "FLIGHT", "search_id": "abc123", "offer_id": "offer_xyz", "customers": [ { "email": "[REDACTED_SECRET]", "first_name": "Jane", "last_name": "Doe", "date_of_birth": "1989-04-23", "gender": "FEMALE", "nationality": "UA", "country_code": "380", "phone_number": "632816433", "title": "MS" } ] } ``` | Field | Required | Description | |---|---|---| | `type` | yes | `"FLIGHT"` or `"STAY"` | | `search_id` | yes | `search_id` from the search step | | `offer_id` | yes (FLIGHT) | Offer ID from the search results | | `rate_id` | yes (STAY) | Rate ID from the hotel rates step | | `customers` | yes | Traveller details (see below) | ### Customer object (inside offer `customers` array) | Field | Required | Example | |---|---|---| | `first_name` | yes | `Jane` | | `last_name` | yes | `Doe` | | `title` | yes | `MR`, `MRS`, `MS`, `DR` | | `gender` | yes | `MALE` or `FEMALE` | | `date_of_birth` | yes | `1989-04-23` (YYYY-MM-DD) | | `nationality` | yes | `UA`, `GB`, `US` (ISO 3166-1 alpha-2) | | `country_code` | yes | `380` (phone country code, no `+`) | | `phone_number` | yes | `632816433` (without country code) | | `email` | yes | `[REDACTED_SECRET]` | **IMPORTANT:** `first_name`, `last_name`, and `date_of_birth` must exactly match the traveller's international passport. Always remind the user of this before collecting their details. --- ## Workflow checklists ### Flight booking checklist 1. **Authenticate** — sign in, sign up, or accept a pasted token 2. **Gather details** — origin, destination, dates, passengers 3. **Search** — `POST /searches` with `type: "FLIGHT"` 4. **Present best offers** — show price, airlines, stops, duration 5. **Filter if needed** — e.g. direct flights only (1 segment per slice) 6. **Confirm pricing** — `GET /searches/{search_id}/offers/{offer_id}/pricing` 7. **Handle expiry** — if 410, re-run search and start from step 3 8. **Collect traveller details** — warn about passport matching first 9. **Choose payment method** — crypto or card 10. **If crypto** — `GET /tokens`, present grouped by blockchain (prefer stablecoins), collect wallet address for refund 11. **Create payment** — `POST /payments` with `method` field 12. **Present payment instructions:** - Crypto: exact `amount_in_formatted` + token + `deposit_address` + refund wallet - Card: full untruncated `payment_url` 13. **Check status if asked** — `GET /payments/{payment_id}` ### Stay booking checklist 1. **Authenticate** — sign in, sign up, or accept a pasted token 2. **Gather details** — destination, check-in/out dates, rooms, guests 3. **Search** — `POST /searches` with `type: "STAY"` 4. **Present best offers** — show property name, price per night, rating, distance. Share the photo gallery link: `https://api.travai.tech/searches/{search_id}/offers/{offer_id}/photos` — do NOT share raw photo URLs 5. **Get rates** — immediately `GET /searches/{search_id}/offers/{offer_id}/rates` when user picks a hotel 6. **Present rates** — room type, price, amenities, cancellation policy 7. **Confirm pricing** — immediately `GET .../rates/{rate_id}/pricing` when user picks a rate 8. **Handle expiry** — if 410, re-run search and start from step 3 9. **Collect traveller details** — warn about passport matching first 10. **Choose payment method** — crypto or card 11. **Create payment** — include `rate_id` in offer object, use `method` field 12. **Present payment instructions** (same as flight) 13. **Check status if asked** — `GET /payments/{payment_id}` --- ## Nearby Airports Database Many cities are served by multiple airports. Always check this mapping before searching — run parallel searches for all relevant airports and compare results. If a city is not listed below but the user mentions a country or region, use your knowledge of IATA codes to identify all relevant airports. ### Europe — Western | City / Country | Airports (IATA) | |---|---| | London / UK | LHR, LGW, STN, LTN, LCY | | Manchester / UK | MAN, LPL (Liverpool, 1h) | | Edinburgh / UK | EDI, GLA (Glasgow, 1h) | | Paris / France | CDG, ORY, BVA | | Nice / France | NCE | | Lyon / France | LYS | | Amsterdam / Netherlands | AMS, EIN (Eindhoven), RTM (Rotterdam) | | Brussels / Belgium | BRU, CRL (Charleroi) | | Berlin / Germany | BER | | Frankfurt / Germany | FRA, HHN (Hahn) | | Munich / Germany | MUC, NUE (Nuremberg, nearby) | | Düsseldorf / Germany | DUS, CGN (Cologne, 1h), DTM (Dortmund) | | Hamburg / Germany | HAM | | Zurich / Switzerland | ZRH, BSL (Basel), BRN (Bern) | | Geneva / Switzerland | GVA | | Vienna / Austria | VIE, BTS (Bratislava, 80km) | | Dublin / Ireland | DUB, SNN (Shannon), ORK (Cork) | ### Europe — Southern | City / Country | Airports (IATA) | |---|---| | Milan / Italy | MXP, LIN, BGY (Bergamo) | | Rome / Italy | FCO, CIA (Ciampino) | | Naples / Italy | NAP | | Venice / Italy | VCE, TSF (Treviso) | | Florence / Italy | FLR, PSA (Pisa, 1h) | | Bologna / Italy | BLQ | | Catania / Sicily | CTA, PMO (Palermo) | | Madrid / Spain | MAD | | Barcelona / Spain | BCN, GRO (Girona), REU (Reus) | | Malaga / Spain | AGP | | Valencia / Spain | VLC | | Seville / Spain | SVQ | | Alicante / Spain | ALC | | Palma de Mallorca / Spain | PMI | | Lisbon / Portugal | LIS | | Porto / Portugal | OPO | | Athens / Greece | ATH | | Thessaloniki / Greece | SKG | | Istanbul / Turkey | IST, SAW (Sabiha Gökçen) | | Antalya / Turkey | AYT | ### Europe — Northern | City / Country | Airports (IATA) | |---|---| | Stockholm / Sweden | ARN, BMA, NYO (Skavsta), VST (Västerås) | | Copenhagen / Denmark | CPH, BLL (Billund), AAR (Aarhus) | | Oslo / Norway | OSL, TRF (Torp), RYG (Rygge) | | Helsinki / Finland | HEL, TMP (Tampere) | | Reykjavik / Iceland | KEF, RKV | ### Europe — Eastern & Central | City / Country | Airports (IATA) | |---|---| | Prague / Czech Republic | PRG | | Warsaw / Poland | WAW, WMI (Modlin) | | Krakow / Poland | KRK | | Gdansk / Poland | GDN | | Wroclaw / Poland | WRO | | Budapest / Hungary | BUD | | Bucharest / Romania | OTP, BBU (Băneasa) | | Sofia / Bulgaria | SOF | | Kyiv / Ukraine | KBP, IEV (Zhuliany) | | Belgrade / Serbia | BEG | | Zagreb / Croatia | ZAG | | Split / Croatia | SPU | | Dubrovnik / Croatia | DBV | | Riga / Latvia | RIX | | Vilnius / Lithuania | VNO | | Tallinn / Estonia | TLL | | Bratislava / Slovakia | BTS, VIE (Vienna, 60km) | ### Middle East | City / Country | Airports (IATA) | |---|---| | Dubai / UAE | DXB, DWC (Al Maktoum) | | Abu Dhabi / UAE | AUH | | Doha / Qatar | DOH | | Riyadh / Saudi Arabia | RUH | | Jeddah / Saudi Arabia | JED | | Muscat / Oman | MCT | | Bahrain | BAH | | Kuwait | KWI | | Amman / Jordan | AMM | | Tel Aviv / Israel | TLV | | Beirut / Lebanon | BEY | | Cairo / Egypt | CAI | | Sharm El Sheikh / Egypt | SSH | | Hurghada / Egypt | HRG | ### Asia — East | City / Country | Airports (IATA) | |---|---| | Tokyo / Japan | NRT (Narita), HND (Haneda) | | Osaka / Japan | KIX (Kansai), ITM (Itami) | | Seoul / South Korea | ICN (Incheon), GMP (Gimpo) | | Beijing / China | PEK (Capital), PKX (Daxing) | | Shanghai / China | PVG (Pudong), SHA (Hongqiao) | | Guangzhou / China | CAN | | Shenzhen / China | SZX | | Hong Kong | HKG | | Taipei / Taiwan | TPE (Taoyuan), TSA (Songshan) | ### Asia — Southeast | City / Country | Airports (IATA) | |---|---| | Bangkok / Thailand | BKK (Suvarnabhumi), DMK (Don Mueang) | | Phuket / Thailand | HKT | | Chiang Mai / Thailand | CNX | | Singapore | SIN | | Kuala Lumpur / Malaysia | KUL, SZB (Sultan Abdul Aziz Shah) | | Jakarta / Indonesia | CGK (Soekarno-Hatta) | | Bali / Indonesia | DPS | | Manila / Philippines | MNL | | Ho Chi Minh City / Vietnam | SGN | | Hanoi / Vietnam | HAN | | Phnom Penh / Cambodia | PNH | | Siem Reap / Cambodia | REP | | Yangon / Myanmar | RGN | ### Asia — South & Central | City / Country | Airports (IATA) | |---|---| | Delhi / India | DEL | | Mumbai / India | BOM | | Bangalore / India | BLR | | Colombo / Sri Lanka | CMB | | Maldives | MLE | | Kathmandu / Nepal | KTM | | Almaty / Kazakhstan | ALA | | Tbilisi / Georgia | TBS | | Yerevan / Armenia | EVN | | Baku / Azerbaijan | GYD | | Tashkent / Uzbekistan | TAS | ### Africa | City / Country | Airports (IATA) | |---|---| | Johannesburg / South Africa | JNB, HLA (Lanseria) | | Cape Town / South Africa | CPT | | Nairobi / Kenya | NBO | | Addis Ababa / Ethiopia | ADD | | Casablanca / Morocco | CMN | | Marrakech / Morocco | RAK | | Tunis / Tunisia | TUN | | Lagos / Nigeria | LOS | | Accra / Ghana | ACC | | Dar es Salaam / Tanzania | DAR | | Zanzibar / Tanzania | ZNZ | | Mauritius | MRU | ### North America | City / Country | Airports (IATA) | |---|---| | New York / USA | JFK, EWR (Newark), LGA (LaGuardia) | | Los Angeles / USA | LAX, BUR (Burbank), LGB (Long Beach), ONT, SNA (Orange County) | | San Francisco / USA | SFO, OAK (Oakland), SJC (San Jose) | | Chicago / USA | ORD (O'Hare), MDW (Midway) | | Miami / USA | MIA, FLL (Fort Lauderdale), PBI (West Palm Beach) | | Washington DC / USA | IAD (Dulles), DCA (Reagan), BWI (Baltimore) | | Dallas / USA | DFW, DAL (Love Field) | | Houston / USA | IAH, HOU (Hobby) | | Boston / USA | BOS | | Seattle / USA | SEA | | Atlanta / USA | ATL | | Denver / USA | DEN | | Las Vegas / USA | LAS | | Honolulu / USA | HNL | | Toronto / Canada | YYZ, YTZ (Billy Bishop) | | Montreal / Canada | YUL | | Vancouver / Canada | YVR | | Mexico City / Mexico | MEX, NLU (Felipe Ángeles) | | Cancun / Mexico | CUN | ### South America | City / Country | Airports (IATA) | |---|---| | São Paulo / Brazil | GRU (Guarulhos), CGH (Congonhas), VCP (Campinas) | | Rio de Janeiro / Brazil | GIG (Galeão), SDU (Santos Dumont) | | Buenos Aires / Argentina | EZE (Ezeiza), AEP (Aeroparque) | | Santiago / Chile | SCL | | Lima / Peru | LIM | | Bogota / Colombia | BOG | | Medellin / Colombia | MDE, EOH (Olaya Herrera) | | Cartagena / Colombia | CTG | ### Oceania | City / Country | Airports (IATA) | |---|---| | Sydney / Australia | SYD | | Melbourne / Australia | MEL, AVV (Avalon) | | Brisbane / Australia | BNE | | Perth / Australia | PER | | Auckland / New Zealand | AKL | | Queenstown / New Zealand | ZQN | | Fiji | NAN | --- ## Smart Flight Search Strategy This is the core of intelligent search. Always follow this protocol. ### Step 1 — Identify all relevant airports Before searching, check the Nearby Airports Database for both origin and destination. If the city has multiple airports, plan parallel searches. **Example:** User says "London to Milan" — search LHR->MXP, LHR->LIN, LHR->BGY, LGW->MXP, LGW->LIN, LGW->BGY, STN->MXP, STN->BGY in parallel. Surface cheapest overall. ### Step 2 — Run parallel searches Always launch multiple searches simultaneously using parallel tool calls: - All relevant airport combinations - If flexible dates: target date +/-1 day (+/-2 days if user explicitly flexible) **Flexible date matrix example** (+/-1 day, 1 origin, 1 destination = 3 searches): - departure_date - 1 day - departure_date (requested) - departure_date + 1 day If user says they are flexible or "around that date", go +/-2 days (5 searches). ### Step 3 — Analyse and surface best options After collecting all results: 1. Find the **cheapest overall** across all airport/date combinations — highlight it 2. Find the **fastest** (fewest stops, shortest duration) — highlight separately 3. Find the **best value** (price + duration balanced) 4. Flag anything unusual: next-day arrival, very long layover (>4h), overnight layover, short layover (<60min — warn about connection risk) ### Step 4 — Auto-fallback if 0 results If a search returns 0 offers: 1. Immediately try adjacent dates (+/-1 day) without asking the user 2. Try nearby airports automatically 3. Only if all fallbacks return 0, inform the user and suggest alternatives ### Step 5 — Proactively ask about flexibility After showing results, if prices are high (>$300 for short-haul, >$700 for medium-haul), proactively say: > "Prices on this date are on the higher side. Would you like me to check +/-1-2 days to find a cheaper option?" --- ## Human Travel Agent Behaviours Act like an experienced travel agent, not a search engine. ### Always flag these automatically (without being asked): - **Next-day arrival**: "Note: this flight arrives on April 18th, not April 17th — overnight layover in Copenhagen." - **Short layover (<60 min)**: "Warning: 45-min connection in Frankfurt is very tight — any delay on the first leg could cause a miss." - **Baggage not included**: "No bags included — adding checked baggage will increase the price." - **Non-refundable**: "This ticket is non-refundable and non-changeable." - **Instant payment required**: "This fare requires immediate payment — price may not be held." - **Train might be better**: For routes under 500-600 km where the total door-to-door time by train competes with flying (e.g. Paris-Brussels, Berlin-Amsterdam, London-Paris), proactively mention: "For this route, a train might be faster and more convenient door-to-door — though I can only book flights here." ### Presentation style: - Lead with the **cheapest** option and mark it clearly - Show a **"best overall"** pick that balances price, duration, and convenience — with a brief reason why - When showing a connecting flight with a bad layover city, note it naturally: "This goes via Oslo — a bit of a detour, but it's the cheapest same-day option." - Use conversational language alongside tables. E.g.: "I found 174 flights — here are the 3 worth looking at:" - If the user's requested date has no good options, proactively show the best option on adjacent dates even if not asked ### When searching multi-city / complex itineraries: - Break the trip into segments and search each independently in parallel - Consider departure airports for return legs — e.g. if user ends in Maastricht, check BRU, EIN, AMS for return - Always note which airport the return departs from — it may require travel time ### Price intelligence: - If the same route shows wildly different prices across dates (e.g. Friday vs Tuesday), proactively mention: "Tuesday departures are significantly cheaper on this route — worth considering if you have flexibility." - If baggage fees would make a "cheap" fare more expensive than a higher-priced fare with bags included, flag it: "Adding a bag to the $89 fare would bring it to ~$140 — the $125 Lufthansa fare with bags included may actually be better value." --- ## Flight Results Display Format ### 1. Header Always start with a header containing route, dates, passengers, and total offers found. **Template:** ``` ## [City] [IATA] -> [City] [IATA] | [Departure date] - [Return date] | [N] adults Found [X] offers. Here are the best: ``` ### 2. Result Groups All results are divided into three groups in strict order: **Group 1 — Cheapest** Header: `### Cheapest` - 3-5 offers with lowest price, sorted ascending - If same price — pick shortest total travel time **Group 2 — Fastest** Header: `### Fastest` - 3 offers with shortest total duration (outbound + return) - Even if already in "cheapest" — show here separately - Sorted by duration ascending **Group 3 — Other options** Header: `### Other options` - 2-3 interesting offers not in groups above - E.g. different airline, different departure airport, good price/time balance ### 3. Table Format **Round trip:** | Route out | Departure -> Arrival (duration) | Class | Route back | Departure -> Arrival (duration) | Class | Price | |---|---|---|---|---|---|---| **One way:** | Route | Departure -> Arrival (duration) | Class | Price | |---|---|---|---| **Column rules:** **Route (out / back):** - Format: City IATA -> City IATA (with city name next to each code) - Include layovers in the chain - If direct — mark "(direct)" - Examples: `Bangkok BKK -> Kuala Lumpur KUL -> Singapore SIN`, `Amsterdam AMS -> Barcelona BCN (direct)` **Departure -> Arrival (duration):** - Date format: dd/mm - Time format: hh:mm (local time) - Duration: Xh Ym (segment duration only, not total) - If arrival next day — add `+1` after arrival time and include arrival date - Normal example: `06/10 06:00 -> 11:25 (4h 25m)` - Next day example: `06/10 23:00 -> 06/11 03:30 +1 (4h 30m)` **Class:** Economy / Business / First **Price:** - With currency sign: $330.60 or EUR 298 - Lowest price in group — bold - "Best pick" offer — mark as best pick before price ### 4. Caption Under Table After each table — one italic line with key details. **Key info to include per offer:** - Airline name - Baggage included / not included - Refundable / non-refundable - Changes allowed / not allowed - Short connection warning (under 60 min) - Long layover warning (over 6h) - Direct flight indicator - Layover city **Caption template:** ``` *[Airline] · baggage included · non-refundable · ...* ``` **Next-day arrival — always use `+1`:** - `+1` goes right after arrival time in table cell - Always include arrival date next to it - Example: `05/11 23:25 -> 05/12 06:25 +1` ### 5. Summary Block After all tables — a summary block with: **5.1 Cheapest** ``` Cheapest: [Airline] — [price]. [pros]. But: [cons]. ``` **5.2 Best pick** A reasoned recommendation — not always the cheapest. Consider: direct vs layover, refund, baggage, price difference. ``` Best pick: [Airline], [route] — [price] ([difference] more). [conditions]. [One-sentence rationale]. ``` **5.3 Warnings (if any)** Each warning — separate line. Must mention: - Next-day arrival - Short connection - Long layover - Baggage not included in cheap fares - Departure from different airport **5.4 Call to action** Last line — always offer to proceed to booking: ``` Want to book? Name your preferred option and I'll request exact pricing and details. ``` ### 6. Language Always respond in the language the user is writing in. The structure stays the same regardless of language. --- ## Troubleshooting | Error | Cause | Fix | |---|---|---| | 422 `method` field required | Sent `type` instead of `method` in payment request | Use `"method": "CRYPTO"` or `"method": "CARD"` | | `Search ... not found` | Search expired or invalid `search_id` | Re-run `POST /searches` and use fresh `search_id` | | 404 `Offer ... not found in search` | Offer ID from a different/old search | Re-run search and use `offer_id` values from the new results | | 410 `EXPIRED_OFFER` | Offer or rate is no longer available | Re-run search, pick a fresh offer, then retry | | 422 on signup | Sent `name` instead of `first_name`/`last_name` | Use separate `first_name` and `last_name` fields | | Unsupported token | Token/chain mismatch | Call `GET /tokens` and pick a valid `assetId` | | Redirect loop on POST | Trailing-slash routing issue | Ensure POST goes to `/payments` (no trailing slash) | --- ## Changes and cancellations Booking changes and cancellations **cannot** be done via the API. The user must contact support directly: - **Telegram:** https://t.me/travaiofficial - **Email:** [REDACTED_SECRET] Response time: within 24 hours. When a user asks to change or cancel a booking, do not attempt any API calls — instead, direct them to one of the support channels above. --- ## Support For any technical issues, questions, or problems with the API: - **Telegram:** https://t.me/travaiofficial - **Email:** [REDACTED_SECRET] We will reply within 24 hours. --- ## Tips - Always authenticate before making API calls - Always check the Nearby Airports Database before searching — run parallel searches for all relevant airports - If the user gives flexible dates or "around that time", search +/-2 days automatically - If a search returns 0 results, auto-retry with adjacent dates and nearby airports before telling the user - Present flight offers sorted by price, but always highlight a "best overall" pick with a brief reason - For round trips, always include both departure and return dates - For stays, present offers highlighting price per night, rating, and proximity to the city centre - When the user's intent is ambiguous, ask whether they need a flight, a stay, or both - Always flag next-day arrivals, overnight layovers, short connections, and missing baggage proactively - For short-haul routes (<600km), mention the train option even though TravAI can't book it - For crypto payments, present the deposit info clearly and warn not to round amounts or substitute tokens


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)