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 support@travai.tech

API base

https://api.travai.tech

Authentication

All endpoints (except sign-in and sign-up) require:

Authorization: Bearer {access_token}

Three ways to authenticate:

Sign up — new user
Sign in — returning user
Paste token — user copies from https://app.travai.tech/profile

Sign In

POST /auth/signin
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "secret"
}

Response (200):

{
  "access_token": "eyJhbG...",
  "token_type": "bearer"
}

Sign Up

POST /auth/signup
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "secret",
  "first_name": "Jane",
  "last_name": "Doe"
}

Response (200):

{
  "message": "User created successfully",
  "access_token": "eyJhbG...",
  "token_type": "bearer"
}

Get current user

GET /auth/me
Authorization: Bearer {access_token}

Response (200):

{
  "user_id": 1,
  "email": "user@example.com",
  "role": "customer",
  "is_active": true,
  "created_at": "2025-01-01T00:00:00",
  "currency": "USD"
}

Error responses

Any failed request may return:

{ "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):

{
  "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):

{
  "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):

{
  "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.

[
  { "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

{
  "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):

{
  "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

{
  "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):

{
  "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)

{
  "type": "FLIGHT",
  "search_id": "abc123",
  "offer_id": "offer_xyz",
  "customers": [
    {
      "email": "jane@example.com",
      "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	`jane@example.com`

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

Authenticate — sign in, sign up, or accept a pasted token
Gather details — origin, destination, dates, passengers
Search — POST /searches with type: "FLIGHT"
Present best offers — show price, airlines, stops, duration
Filter if needed — e.g. direct flights only (1 segment per slice)
Confirm pricing — GET /searches/{search_id}/offers/{offer_id}/pricing
Handle expiry — if 410, re-run search and start from step 3
Collect traveller details — warn about passport matching first
Choose payment method — crypto or card
If crypto — GET /tokens, present grouped by blockchain (prefer stablecoins), collect wallet address for refund
Create payment — POST /payments with method field
Present payment instructions:
- Crypto: exact amount_in_formatted + token + deposit_address + refund wallet
- Card: full untruncated payment_url
Check status if asked — GET /payments/{payment_id}

Stay booking checklist

Authenticate — sign in, sign up, or accept a pasted token
Gather details — destination, check-in/out dates, rooms, guests
Search — POST /searches with type: "STAY"
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
Get rates — immediately GET /searches/{search_id}/offers/{offer_id}/rates when user picks a hotel
Present rates — room type, price, amenities, cancellation policy
Confirm pricing — immediately GET .../rates/{rate_id}/pricing when user picks a rate
Handle expiry — if 410, re-run search and start from step 3
Collect traveller details — warn about passport matching first
Choose payment method — crypto or card
Create payment — include rate_id in offer object, use method field
Present payment instructions (same as flight)
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:

Find the cheapest overall across all airport/date combinations — highlight it
Find the fastest (fewest stops, shortest duration) — highlight separately
Find the best value (price + duration balanced)
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:

Immediately try adjacent dates (+/-1 day) without asking the user
Try nearby airports automatically
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: support@travai.tech

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: support@travai.tech

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

API base

Authentication

Sign In

Sign Up

Get current user

Error responses

Endpoints

Search flights

Search stays

List offers

Get single offer

Offer pricing (flights)

Hotel rates

Rate pricing (stays)

Hotel photo gallery

List tokens

Initiate payment

CRYPTO payment

CARD payment

Get payment status

Get itinerary offers

Offer object (inside offers array in payment request)

Customer object (inside offer customers array)

Workflow checklists

Flight booking checklist

Stay booking checklist

Nearby Airports Database

Europe — Western

Europe — Southern

Europe — Northern

Europe — Eastern & Central

Middle East

Asia — East

Asia — Southeast

Asia — South & Central

Africa

North America

South America

Oceania

Smart Flight Search Strategy

Step 1 — Identify all relevant airports

Step 2 — Run parallel searches

Step 3 — Analyse and surface best options

Step 4 — Auto-fallback if 0 results

Step 5 — Proactively ask about flexibility

Human Travel Agent Behaviours

Always flag these automatically (without being asked):

Presentation style:

When searching multi-city / complex itineraries:

Price intelligence:

Flight Results Display Format

1. Header

2. Result Groups

3. Table Format

4. Caption Under Table

5. Summary Block

6. Language

Troubleshooting

Changes and cancellations

Support

Tips

Offer object (inside `offers` array in payment request)

Customer object (inside offer `customers` array)

TravAI

TravAI

Source of truth

Critical notes