Skip to content
Back to search

letsfg

"LetsFG — Agent-native flight and hotel search and booking API. Every airline in the world plus the major booking sites (Google Flights, Skyscanner, Kiwi, Kayak, Momondo), with per-flight reliability history and instant booking. Plus real bookable hotel rates, refundable and non-refundable: the price is held on the connected card and charged only once the hotel confirms. letsfg.co"

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/LetsFG/LetsFG with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/LetsFG/LetsFG'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/letsfg--letsfg/badge.svg)](/listings/letsfg--letsfg)

HTML

<a href="/listings/letsfg--letsfg"><img src="/api/listings/letsfg--letsfg/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

| Package | Command | What you get | |---------|---------|--------------| | **Remote MCP** | `https://letsfg.co/mcp` | No install. Approve the connection at letsfg.co/connect (one tap, no card), search and book | | **Python SDK + CLI** | `pip install letsfg` | SDK + CLI (token from the connect flow in `LETSFG_BEARER_TOKEN`) | | **MCP Server (stdio)** | `npx letsfg-mcp` | Local server for clients without remote MCP support; needs `LETSFG_BEARER_TOKEN` | | **JS/TS SDK** | `npm install -g letsfg` | SDK + CLI + open-source ranking engine | | **Agent Skill** | `npx skills add LetsFG/LetsFG` | Install flight search skill for any AI agent ([skills.sh](https://skills.sh)) | | **Smithery** | [smithery.ai/servers/letsfg](https://smithery.ai/servers/letsfg) | One-click MCP install | | **Omarchy plugin** | `omarchy plugin add https://github.com/LetsFG/LetsFG.git --enable` | Flight search in the Omarchy bar ([details](OMARCHY-PLUGIN.md)) |

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 521 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ---
  2. name: letsfg
  3. description: "LetsFG — Agent-native flight and hotel search and booking API. Every airline in the world plus the major booking sites (Google Flights, Skyscanner, Kiwi, Kayak, Momondo), with per-flight reliability history and instant booking. Plus real bookable hotel rates, refundable and non-refundable: the price is held on the connected card and charged only once the hotel confirms. letsfg.co"
  4. ---
  5. # SKILL.md — LetsFG Capabilities
  6. > **MPP:** a card-free *enrolment* lane for agents holding a Tempo wallet is
  7. > offered only when the `402` from `POST /api/agent-access/request` carries an
  8. > `mpp` object. It costs **$0.01 once**, as verification only. Search stays free
  9. > and booking costs the price on the offer. Earlier revisions of this page
  10. > described an MPP charge at *unlock* time; that never shipped. See
  11. > <https://letsfg.co/for-agents>.
  12. > ### ⚠️ Agents: do not create a Developer API account
  13. >
  14. > Do **NOT** call `/developers/api/v1/agents/register` or
  15. > `/developers/api/v1/agents/connect-payment`, and do **NOT** run
  16. > `letsfg register` or `letsfg connect-payment`. Those belong to a separate,
  17. > paid, prepaid-balance product for high-volume commercial integrations and
  18. > create a billing account you almost certainly do not want.
  19. >
  20. > To search and book flights, connect LetsFG as an MCP server at
  21. > `https://letsfg.co/mcp` and approve it — the consent at
  22. > <https://letsfg.co/connect> is one tap and needs no card. Then search and book.
  23. > See <https://letsfg.co/for-agents>.
  24. > Machine-readable skill manifest for AI agents and documentation indexers.
  25. ## Identity
  26. - **Name:** LetsFG
  27. - **Type:** API + SDK + MCP Server + CLI
  28. - **Purpose:** Agent-native flight and hotel search and booking
  29. - **Compatible agents:** OpenClaw, Perplexity Computer, Claude Desktop, Cursor, Windsurf, and any MCP-compatible client
  30. - **API Base URL:** `https://letsfg.co/developers/api/v1`
  31. - **MCP Endpoint:** `https://letsfg.co/mcp` (Streamable HTTP)
  32. - **Packages:** PyPI `letsfg` · npm `letsfg` · npm `letsfg-mcp`
  33. - **License:** MIT
  34. ## Access Modes
  35. | Mode | Best for | Speed | Cost |
  36. |------|----------|-------|------|
  37. | **MCP / SDK / CLI** (PFS token) | **Almost every agent.** Search + booking | 8–10 s to first results | Free auth, free search, booking at the price on the offer |
  38. | **Developer API** (`https://letsfg.co/developers`) | Business / commercial / high-volume (hotels work on either credential) | 2–5 s (discover) · 8–10 s to first results (full search) | Look-to-book: 200 searches free after every booking, then $0.01. Booking via `POST /flights/book`, no booking fee, no transaction fee |
  39. ## Skills
  40. ### search_flights
  41. Search every airline in the world AND the major booking sites (Google Flights, Skyscanner, Kiwi, Kayak, Momondo) in one call. Returns real-time prices plus per-flight reliability history.
  42. - **Cost:** FREE (10 per 10 min, 30/hour, 100/day)
  43. - **Input:** origin (IATA), destination (IATA), date_from, optional: date_to, return_from, return_to, adults, children, infants, cabin_class (M/W/C/F), max_stopovers, currency, sort, limit
  44. - **Output:** List of flight offers with price, airlines, times, segments, conditions, passenger_ids
  45. - **Note:** On PFS (Bearer token), call `book_flight` directly — no unlock step — then poll `get_flight_booking`. The Developer API has no unlock step either: book with `POST /flights/book` and poll `GET /flights/bookings/{id}`.
  46. - **Rate limit (PFS):** 10 searches per 10 min, 30 per hour, 100 per day, per account (per card once one is added). Polling results never counts.
  47. ### resolve_hotel_city
  48. Resolve a place name to the supplier city id that hotel search needs.
  49. - **Cost:** FREE (a card must still be on file)
  50. - **Endpoint:** `POST /api/v1/hotels/destinations`
  51. - **Input:** text (place name, e.g. "Warsaw")
  52. - **Output:** Matches, best first. Use `Id` as city_id and `Name` as city_name.
  53. ### search_hotels
  54. Search real, bookable hotel inventory.
  55. - **Cost:** FREE. Searching needs no card; an account with no card on file gets a daily number of
  56. hotel searches. Booking needs a payment method on file and returns HTTP 402 without one.
  57. - **Auth:** Either a Developer API key (`X-API-Key`) or the PFS token from the connect flow. The same card authorises flights and hotels.
  58. - **Endpoint:** `POST /api/v1/hotels/search`
  59. - **Input:** city_id, city_name, check_in, check_out, adults, children, child_ages, nationality, currency (USD by default), limit
  60. - **Output:** hotels[] each with offers[] carrying `price` (the all-in total the guest pays, in
  61. `currency`), `fx_rate`, `expected_cost`, `refundable`, `free_cancellation_until` (refundable
  62. rates only), `cancellation_policy`, `combination_id_v2` and `session_id`
  63. - **Note:** Every rate type is sold, refundable and non-refundable — show `refundable` and
  64. `free_cancellation_until` before booking. Keep the chosen offer's `session_id` and
  65. `combination_id_v2`; booking needs both. `price` is what the guest pays.
  66. - **Allowance:** 1,000 hotel searches free after every hotel booking, then blocks of 1,000 for
  67. $5.00 from prepaid balance.
  68. ### search_transfers
  69. Search ground transfers — private cars, taxis, shared shuttles, airport express.
  70. - **Cost:** FREE
  71. - **Input:** origin, destination, date, passengers
  72. - **Output:** Transfer options with prices and vehicle types
  73. ### search_activities
  74. Search activities — tours, tickets, day trips (limited supplier coverage).
  75. - **Cost:** FREE
  76. - **Input:** location, date_from, date_to
  77. - **Output:** Activity options with prices, descriptions, availability
  78. ### resolve_location
  79. Resolve city names to IATA airport/city codes.
  80. - **Cost:** FREE
  81. - **Input:** query (city name, e.g. "London")
  82. - **Output:** List of matching IATA codes (e.g. LON, LHR, LGW, STN, LTN, LCY)
  83. ### unlock_flight_offer
  84. **RETIRED 2026-09-08 — the route answers `410 Gone`.**
  85. - There is no unlock step on either lane. Booking holds the fare and captures only against a real PNR, which is what unlock existed to protect against. Call `/api/agent-book` (PFS) or `POST /flights/book` (Developer API) instead.
  86. - **Endpoint:** `POST /api/v1/bookings/unlock` — answers `410 Gone`, and the SDKs' `unlock()` fails the same way.
  87. ### book_flight
  88. Book an offer.
  89. - **PFS (Bearer token):** `POST /api/agent-book`. No unlock step — search, then book directly.
  90. Works for every offer in the results, whichever seller it came from. Exactly what the website
  91. checkout does: the price shown is **held** on the connected card (not taken), a
  92. LetsFG booking agent buys the ticket from the seller, and the hold is captured only once a real
  93. airline PNR exists. If the booking fails the hold is released and nothing is charged.
  94. - **Input:** `search_id` + `offer_id` exactly as search returned them (offers expire ~15 min),
  95. `contact_email`, and ONE `passenger` per call: given_name, family_name, born_on, gender (m/f),
  96. nationality (ISO-2), phone_number + phone_country, address_line1, address_city,
  97. address_postal, address_country; passport_number/country/expiry optional.
  98. - **Output (seconds):** `{"state": "booking_in_progress", "booking_ref": "eyJ...",
  99. "held": {"amount": 93, "currency": "EUR", "card": "visa ending 5709"}, "charged": 0}`.
  100. The booking itself takes 4–11 minutes — poll `get_flight_booking`.
  101. - **Nothing charged on:** `{"error": "missing_details", "missing_fields": [...]}` (ask, call again),
  102. `payment_method_required` and `payment_declined` (both carry `add_card_url`: https://letsfg.co/connect).
  103. - Never call it twice for the same trip while one is in progress — that places a second hold.
  104. - **CLI:** `letsfg book ws_off_xxx --search-id ws_xxx --passenger '{...}' --email you@example.com`
  105. - **Python:** `bt.book(offer_id=..., passengers=[{...}], contact_email=..., search_id=...)`
  106. - **Developer API:** `POST /api/v1/flights/book`. The same flow with no unlock step: the fare is held
  107. on the connected Revolut method, a LetsFG booking agent buys the ticket, and the hold is captured
  108. only against a real airline PNR. No booking fee, no transaction fee.
  109. - **Prerequisite:** a Revolut method connected with `POST /api/v1/agents/connect-payment` (nothing is charged to connect).
  110. - **Input:** search_id, offer_id, passengers (given_name, family_name, born_on, gender, email, phone_number, nationality, ...), contact_email, idempotency_key
  111. - **Output:** `202` with `booking_id`, `held`, `charged: 0` and `poll_url`. Poll `GET /api/v1/flights/bookings/{booking_id}` until `terminal`: `completed` (`pnr`, `charged_amount`) | `failed` (hold released, nothing charged) | `needs_attention`.
  112. - **CRITICAL (both paths):** Use real passenger names (must match passport/ID) and real email (airline sends e-ticket there).
  113. ### get_flight_booking
  114. Where a booking started by `book_flight` has got to (PFS). `POST /api/agent-book/status {"booking_ref": "eyJ..."}`.
  115. - **Cost:** FREE. Poll every 20–30 s.
  116. - **States:** `booking_in_progress` (the agent is at the seller's checkout — keep waiting) →
  117. `completed` (`pnr`, `charged_amount`, `currency` — booked) | `failed` (`failure_reason`; the hold was
  118. released, nothing charged) | `needs_attention` (a human at LetsFG is checking it — do NOT book again;
  119. the traveller will be emailed). `updated_at_ms` says when it last moved.
  120. - Only `completed` with a PNR means booked.
  121. ### book_hotel
  122. Start a hotel booking. Returns a job, NOT a booking.
  123. - **Cost:** the offer's `price`. It is **held** on the connected card (not taken), LetsFG books the
  124. room and pays the supplier, and the hold is captured only once the hotel confirms. A failed
  125. booking releases the hold. No reservation fee, no deposit, no pay link.
  126. - **Endpoint:** `POST /api/v1/hotels/book`
  127. - **Input:** session_id (the chosen offer's), hotel_code, combination_id_v2, expected_price,
  128. expected_cost, currency, fx_rate, city_id, city_name, check_in, check_out, adults,
  129. guests[{title, first_name, last_name}], email, phone; optional phone_country_code,
  130. special_requests, idempotency_key
  131. - **Output:** booking_job_id, booking_id, status "in_progress", the amount held, poll URL
  132. - **Asynchronous:** a real booking takes minutes — the rate is re-blocked at the supplier, the room
  133. committed and paid. Poll `get_hotel_booking` until status is `succeeded`, `failed` or `attention`.
  134. - **CRITICAL:** send `expected_price`, `expected_cost`, `currency` and `fx_rate` back exactly as the
  135. chosen offer returned them, or the booking is refused as `price_mismatch` — a guest is never
  136. charged a price they did not agree to. There is no `expected_balance`.
  137. - **Local packages:** hotel booking needs `letsfg-mcp` 2026.5.77+, `letsfg` 2026.5.101+ (Python) or
  138. `letsfg` 2026.5.74+ (npm). Earlier releases send the retired `expected_balance` contract and every
  139. hotel booking they make is refused. The hosted MCP needs no update.
  140. - **CRITICAL:** never call this again while its job is running — poll the job. A retry with the same
  141. `idempotency_key` returns the existing job instead of booking twice.
  142. - **Note:** guest names, phone and e-mail are checked before anything is held (`400 invalid_details`).
  143. - **CRITICAL:** `guests` needs a name for every person in the room, children included: adults first,
  144. then children in `child_ages` order. Fewer names than the searched party fails the booking before
  145. anything reaches the hotel, and the hold is released.
  146. ### get_hotel_booking
  147. Collect the result of a booking started with `book_hotel`.
  148. - **Cost:** FREE
  149. - **Endpoint:** `GET /api/v1/hotels/booking/{booking_job_id}`
  150. - **Output:** status — `in_progress`, then `succeeded` (confirmation, total_price + currency = what
  151. the guest is charged, refundable, free_cancellation_until, terms with the full cancellation
  152. ladder) | `failed` (`error`; the hold was released, nothing charged) | `attention` (`error`; a
  153. person at LetsFG is confirming the outcome with the supplier, the hold is kept — do NOT book again)
  154. - **Note:** the guest is e-mailed however the booking ends.
  155. ### cancel_hotel_booking
  156. Release a hotel reservation.
  157. - **Cost:** Free on a refundable rate before `free_cancellation_until` — the charge is refunded in
  158. full. A cancellation the hotel would charge for (a non-refundable rate, or past that date) is
  159. refused with `409`; the hotel's own ladder is in the booking's `terms`.
  160. - **Endpoint:** `POST /api/v1/hotels/cancel`
  161. - **Input:** confirmation (only your own bookings)
  162. - **Output:** confirmation, charge, refund
  163. - **Note:** drives a browser at the supplier and takes over a minute. If it times out, do NOT
  164. assume it failed — re-check before retrying.
  165. ### register
  166. Register a new AI agent.
  167. - **Cost:** FREE
  168. - **Input:** agent_name, email
  169. - **Output:** api_key (permanent credential)
  170. ### connect_payment
  171. **Developer API only.** `POST /api/v1/agents/connect-payment` returns a one-time `connect_url`; a
  172. person opens it in a browser and saves a card or Revolut Pay. Agents on the PFS lane do not call
  173. this — connecting at <https://letsfg.co/connect> needs no card, and the card is asked
  174. for at their first booking.
  175. - **Cost:** FREE — nothing is charged to connect
  176. - **Output:** `connect_url` (valid for one hour)
  177. - **Note:** `setup_payment` (`POST /agents/setup-payment`) was retired with Stripe on 2026-09-08
  178. and answers `410 Gone`.
  179. ### get_agent_profile
  180. Get current agent's profile, usage stats, and payment status.
  181. - **Cost:** FREE
  182. - **Output:** Agent details, search count, booking count, payment status
  183. ## Authentication
  184. **PFS (recommended — almost every agent):** a Bearer token from the connect flow.
  185. Connecting needs no card and nothing is charged. The card is asked for at the
  186. first booking, in a 0.00 Revolut setup at <https://letsfg.co/connect> (any card, or Revolut Pay / Google Pay; no Revolut
  187. account needed; card details never touch LetsFG). Search, flight booking and
  188. hotels all work with it.
  189. ```
  190. Authorization: Bearer eyJ...
  191. ```
  192. Get a token — the one way in:
  193. 1. Add LetsFG as a remote MCP server: `https://letsfg.co/mcp`.
  194. 2. Approve the connection. The OAuth consent step opens
  195. <https://letsfg.co/connect>: one tap, no card.
  196. 3. Over the MCP the OAuth token is carried for you; over raw HTTP send it as
  197. `Authorization: Bearer <token>`.
  198. `POST /api/agent-access/request` answers `402` with these steps as JSON
  199. (`add_card_url`, `how`). The Stripe enrolment lanes (`setup_url`, `setup_intent`,
  200. `card_token`) were retired on 2026-09-02 and every token they issued was revoked
  201. (`401 TOKEN_REVOKED`; `/api/agent-access/verify` answers `410` for a Stripe
  202. credential) — reconnect at letsfg.co/connect. `letsfg auth` (npm or PyPI) now
  203. drives that connect flow from the terminal and stores the token; the CLI and
  204. SDKs otherwise read it from `LETSFG_BEARER_TOKEN`. One card = one account; quotas are per account, and per card once one is added. Full flow:
  205. <https://letsfg.co/for-agents>.
  206. **Developer API (business / high-volume):** every endpoint except `register`
  207. requires an `X-API-Key` header.
  208. ```
  209. X-API-Key: letsfg_...
  210. ```
  211. Get your key by calling `POST /api/v1/agents/register` with agent_name and email. The key is permanent — save it once.
  212. Then connect a payment method with `POST /api/v1/agents/connect-payment` and open the returned `connect_url` once (nothing is charged).
  213. ## Complete Workflow
  214. ### Flight Booking — PFS (3 API calls)
  215. ```
  216. 1. POST /api/search → Search flights (FREE), returns search_id; poll GET /api/results/{search_id}
  217. 2. POST /api/agent-book → Book directly — no unlock step. Holds the fare on the connected card, returns booking_ref in seconds
  218. 3. POST /api/agent-book/status → Poll every 20–30 s (4–11 min) → completed (PNR) | failed (hold released) | needs_attention
  219. ```
  220. ### Flight Booking — Developer API (5 API calls)
  221. ```
  222. 1. POST /api/v1/agents/register → Get API key (once)
  223. 2. POST /api/v1/agents/connect-payment → Open the connect_url once to save a card (nothing charged)
  224. 3. POST /api/v1/flights/search → Search flights (look-to-book: 200 free after every booking)
  225. 4. POST /api/v1/flights/book → Hold the fare, dispatch the booking agent → booking_id (202)
  226. 5. GET /api/v1/flights/bookings/{id} → Poll until terminal → completed (PNR) | failed (hold released) | needs_attention
  227. ```
  228. ### Hotel Booking (PFS Bearer token or Developer API key — the same card authorises both)
  229. ```
  230. 1. Card on file (to book; search needs none) → PFS: asked for at the first booking; Developer API: POST /api/v1/agents/connect-payment
  231. 2. POST /api/v1/hotels/destinations → Place name → city_id
  232. 3. POST /api/v1/hotels/search → Bookable rates (card required; 1,000 free after every hotel booking)
  233. 4. POST /api/v1/hotels/book → Holds the price; returns booking_job_id — NOT a booking
  234. 5. GET /api/v1/hotels/booking/{job_id} → Poll ~20s until succeeded / failed / attention
  235. → confirmation + total_price + currency
  236. 6. POST /api/v1/hotels/cancel → Optional; free on a refundable rate before free_cancellation_until
  237. ```
  238. The full price is held on the card at step 4 and captured only once the hotel confirms; a failed
  239. booking releases the hold. There is no reservation fee, no deposit and no pay link. Never repeat
  240. step 4 while its job is running — poll it.
  241. ## CLI Usage
  242. ```bash
  243. pip install -U letsfg # 2026.5.101 or later books hotels
  244. export LETSFG_BEARER_TOKEN=eyJ... # token from the connect flow (see Authentication)
  245. # Search flights — prints search_id, needed for book
  246. letsfg search LHR JFK 2026-04-15
  247. letsfg search LON BCN 2026-04-01 --return 2026-04-08 --cabin C --sort price
  248. letsfg search GDN BER 2026-05-10 --adults 2 --children 1
  249. # Resolve locations
  250. letsfg locations "New York"
  251. # Book — price shown on the offer, no unlock step. Holds the fare on the connected
  252. # card and prints a booking_ref; poll POST /api/agent-book/status every 20–30 s
  253. letsfg book ws_off_xxx --search-id ws_xxx \
  254. --passenger '{"given_name":"John","family_name":"Doe","born_on":"1990-01-15","gender":"m","nationality":"GB","phone_number":"+447123456789","phone_country":"GB","address_line1":"1 High St","address_city":"London","address_postal":"N1 9GU","address_country":"GB"}' \
  255. --email john.doe@example.com
  256. # Machine-readable output
  257. letsfg search GDN BER 2026-03-03 --json
  258. ```
  259. Developer API instead? `letsfg register` + `letsfg connect-payment` once (open the link it
  260. prints), then `letsfg search ... --api-key letsfg_...` and
  261. `letsfg book off_xxx --search-id <search_id> --api-key letsfg_... --passenger '{...}' --email ...`.
  262. No unlock step.
  263. ## Python SDK Usage
  264. ```python
  265. from letsfg import LetsFG
  266. bt = LetsFG() # reads LETSFG_BEARER_TOKEN — the token from the connect flow
  267. # Search
  268. results = bt.search("LHR", "JFK", "2026-04-15")
  269. for offer in results.offers:
  270. print(f"{offer.price} {offer.currency} — {', '.join(offer.airlines)}")
  271. # Book — price shown on the offer, no unlock step. Holds the fare on the
  272. # connected card; a LetsFG agent buys the ticket; captured only on a real PNR.
  273. result = bt.book(
  274. offer_id=results.offers[0].id,
  275. passengers=[{
  276. "given_name": "John", "family_name": "Doe",
  277. "born_on": "1990-01-15", "gender": "m", "nationality": "GB",
  278. "phone_number": "+447123456789", "phone_country": "GB",
  279. "address_line1": "1 High St", "address_city": "London",
  280. "address_postal": "N1 9GU", "address_country": "GB",
  281. }],
  282. contact_email="john@example.com",
  283. search_id=results.search_id,
  284. )
  285. if "missing_fields" in result:
  286. print("Nothing charged — ask for:", result["missing_fields"])
  287. else:
  288. print("Started:", result["booking_ref"], result["held"])
  289. # poll POST /api/agent-book/status {"booking_ref": ...} every 20–30 s
  290. # until state is completed (pnr) | failed (hold released) | needs_attention
  291. ```
  292. Developer API instead? `LetsFG(api_key="letsfg_...")`, then `bt.book(offer_id, passengers,
  293. contact_email, search_id=..., idempotency_key=...)` — no unlock step. It starts the booking; poll
  294. it with `bt.get_booking(booking_id)`, or call `bt.book_and_wait(...)` to block until it settles.
  295. ## MCP Server Setup
  296. **Remote (Streamable HTTP) — the way in for agents:**
  297. ```json
  298. {
  299. "mcpServers": {
  300. "letsfg": { "url": "https://letsfg.co/mcp" }
  301. }
  302. }
  303. ```
  304. Claude Code: `claude mcp add --transport http letsfg https://letsfg.co/mcp`.
  305. Claude: add it from Claude's official connector directory, <https://claude.ai/directory/letsfg> - no URL to paste (once added, it works in Claude Desktop and the Claude phone app too).
  306. ChatGPT: at chatgpt.com in a browser (the ChatGPT phone app has no way to add one), Plugins > Add >
  307. Add custom MCP server, that URL, authentication OAuth; once added it works in the phone app too. Windsurf uses
  308. `"serverUrl"` instead of `"url"`. The client runs OAuth; the consent step opens
  309. <https://letsfg.co/connect>: one tap, no card. The token the client receives can
  310. search at once, and the card is asked for at the first booking.
  311. Developer API accounts can use the same URL with
  312. `"headers": {"X-API-Key": "letsfg_..."}` instead of OAuth.
  313. **Local (stdio) — needs a token you already hold:**
  314. ```bash
  315. npm install -g letsfg-mcp@latest # 2026.5.77 or later books hotels
  316. LETSFG_BEARER_TOKEN=eyJ... letsfg-mcp # token from the connect flow
  317. ```
  318. The local server also accepts `LETSFG_API_KEY` instead, for the Developer API.
  319. `book_flight` dispatches automatically based on which one is set. Its
  320. `authenticate` tool returns the current connect instructions (`add_card_url`,
  321. `how`); run `letsfg auth` to mint a token from the terminal.
  322. ## MCP Tools
  323. | Tool | Description | Cost |
  324. |------|-------------|------|
  325. | `search_flights` | Search every airline in the world via server-side engine | FREE |
  326. | `resolve_location` | City name → IATA code | FREE |
  327. | `book_flight` | Start a booking. PFS: direct, no unlock step — holds the fare on the connected card, returns `booking_ref`. Developer API key: the same call, no unlock step | Price shown on the offer, no separate LetsFG fee (PFS) |
  328. | `get_flight_booking` | Poll a PFS booking every 20–30 s: `booking_in_progress` → `completed` (PNR) / `failed` (hold released) / `needs_attention` | FREE |
  329. | `unlock_flight_offer` | **RETIRED 2026-09-08** — answers `410 Gone`. Call `book_flight` directly | — |
  330. | `connect_payment` | **[Developer API only]** Mint a one-time link to connect a card to the paid account (nothing charged). PFS agents connect at letsfg.co/connect instead | FREE |
  331. | `resolve_hotel_city` | Place name → supplier city id for `search_hotels` | FREE |
  332. | `search_hotels` | Bookable hotel rates, refundable and non-refundable | FREE (1,000 per hotel booking) |
  333. | `book_hotel` | Start a hotel booking: the price is held, captured once the hotel confirms. Returns `booking_job_id` | The price on the offer |
  334. | `get_hotel_booking` | Poll until `succeeded` / `failed` / `attention` | FREE |
  335. | `cancel_hotel_booking` | Cancel a refundable booking before `free_cancellation_until` (98% refunded, 2% fee) | FREE |
  336. | `get_agent_profile` | View usage stats | FREE |
  337. ## Search Flags Reference
  338. | Flag | API Field | Values | Default |
  339. |------|-----------|--------|---------|
  340. | `--adults` | `adults` | 1–9 | 1 |
  341. | `--children` | `children` | 0–9 | 0 |
  342. | `--infants` | `infants` | 0–9 | 0 |
  343. | `--cabin` | `cabin_class` | M (economy), W (premium), C (business), F (first) | _(any)_ |
  344. | `--return` | `return_from` | YYYY-MM-DD | — |
  345. | `--max-stops` | `max_stopovers` | 0–4 | 2 |
  346. | `--sort` | `sort` | price, duration | price |
  347. | `--limit` | `limit` | 1–100 | 20 |
  348. | `--currency` | `currency` | EUR, USD, GBP, etc. | EUR |
  349. ### Cabin Class Codes Explained
  350. | Code | Class | Description | Typical Use Case |
  351. |------|-------|-------------|------------------|
  352. | `M` | Economy | Standard seating | Budget travel, most bookings |
  353. | `W` | Premium Economy | Extra legroom, priority boarding | Long-haul comfort without business price |
  354. | `C` | Business | Lie-flat on long-haul, lounge access | Corporate travel, 6+ hour flights |
  355. | `F` | First | Private suites, premium dining | Ultra-premium routes (limited airlines) |
  356. | `--json` | — | Output as JSON | — |
  357. ## Error Handling
  358. | Exception | HTTP Code | When |
  359. |-----------|-----------|------|
  360. | `AuthenticationError` | 401 | Invalid or missing API key |
  361. | `PaymentRequiredError` | 402 | No payment method connected, or the search allowance is used up |
  362. | `OfferExpiredError` | 410 | Offer no longer available |
  363. | `LetsFGError` | 422 | Invalid request parameters |
  364. | `LetsFGError` | 429 | Too many requests (retry with backoff) |
  365. | `LetsFGError` | 502 | Upstream airline/hotel API error |
  366. ### Authentication Failure Recovery
  367. ```python
  368. from letsfg import LetsFG
  369. from letsfg.connectors.auth import BearerTokenError
  370. try:
  371. bt = LetsFG() # reads LETSFG_BEARER_TOKEN — the token from the connect flow
  372. flights = bt.search("LHR", "JFK", "2026-04-15")
  373. except BearerTokenError:
  374. print("Token expired, revoked or missing — reconnect at https://letsfg.co/connect")
  375. ```
  376. Developer API:
  377. ```python
  378. from letsfg import LetsFG, AuthenticationError
  379. try:
  380. bt = LetsFG(api_key="letsfg_...")
  381. flights = bt.search("LHR", "JFK", "2026-04-15")
  382. except AuthenticationError:
  383. # API key invalid or expired — re-register, then connect a payment method on the new key
  384. creds = LetsFG.register("my-agent", "agent@example.com")
  385. bt = LetsFG(api_key=creds["api_key"])
  386. print("Open once to connect a card:", bt.connect_payment()["connect_url"]) # nothing is charged
  387. ```
  388. ### Rate Limit and Timeout Handling
  389. ```python
  390. import time
  391. from letsfg import LetsFG, LetsFGError
  392. def search_with_retry(bt, origin, dest, date, max_retries=3):
  393. for attempt in range(max_retries):
  394. try:
  395. return bt.search(origin, dest, date)
  396. except LetsFGError as e:
  397. if "429" in str(e) or "rate limit" in str(e).lower():
  398. time.sleep(2 ** attempt) # exponential backoff
  399. elif "timeout" in str(e).lower() or "504" in str(e):
  400. time.sleep(1)
  401. else:
  402. raise
  403. raise LetsFGError("Max retries exceeded")
  404. ```
  405. ## Rate Limits
  406. | Endpoint | Rate Limit | Typical Latency |
  407. |----------|-----------|------------------|
  408. | Search flights | No hard limit (billing is the natural governor) | 2–5 s (discover) · 8–10 s to first results (full search) |
  409. | Resolve location | 120 req/min | <1s |
  410. | Book | 10 req/min | 3-10s |
  411. | Search hotels | 30 req/min | 3-10s |
  412. | Register | 5 req/min | <1s |
  413. ## Pricing Summary
  414. | Action | Cost |
  415. |--------|------|
  416. | Search (flights, transfers, activities) | **Free** |
  417. | Resolve locations | **Free** |
  418. | Register agent | **Free** |
  419. | Connect a payment method | **Free** — nothing is charged to connect |
  420. | View profile | **Free** |
  421. | Book flight (PFS, no unlock needed) | **The price shown on the offer** — held on the connected card, captured only on a real PNR; no separate LetsFG fee |
  422. | Book flight (Developer API) | **The price shown on the offer** — held, captured only on a real PNR; no booking fee, no transaction fee |
  423. | Hotel search | Free up to 1,000 searches after every hotel booking, then 1,000 for $5.00 |
  424. | Hotel booking | **The price shown on the offer** — held on the connected card, captured only once the hotel confirms. No reservation fee |
  425. | Hotel cancellation | 98% refunded on a refundable rate before `free_cancellation_until` (2% fee); otherwise refused |
  426. ## Key Facts
  427. - Every airline in the world via server-side engine
  428. - Hotels via a wholesale hotel partner
  429. - No cookie tracking — the same search returns the same prices
  430. - Typically cheaper than booking through a single OTA, because it compares airlines and the major booking sites in one pass
  431. - Real airline PNR codes and hotel confirmations
  432. - E-tickets sent directly to passenger email
  433. - Search is free (10 per 10 min, 30/hour, 100/day)
  434. - PFS (Bearer token): book directly, no unlock step — the fare is held on the connected card, a LetsFG booking agent buys the ticket, captured only once a real PNR exists; failed booking = hold released, nothing charged
  435. - Developer API: `POST /flights/book` — the same hold-then-capture flow, then poll `GET /flights/bookings/{id}`. Search there is look-to-book (200 free after every booking) and there is no booking or transaction fee
  436. - API designed for machines, not browsers
README.md · README · 811 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <a href="https://github.com/LetsFG/LetsFG">
  3. <img src="assets/banner.png" alt="LetsFG" width="600">
  4. </a>
  5. <br>
  6. # We're LetsFG — a community of travelers.
  7. Finding a flight or hotel shouldn't mean checking 47 tabs. Or 3 hours of searching.<br>
  8. Or having that feeling you could've got a better deal if you'd just waited a little longer.<br>
  9. **So we built something about it.**<br>
  10. One total price. No tracking. No price that goes up because you looked twice.
  11. <br>
  12. [<img src="https://img.shields.io/badge/Add_to_Claude-D97757?style=for-the-badge&logo=claude&logoColor=white" alt="Add to Claude">](https://claude.ai/directory/letsfg)
  13. &nbsp;&nbsp;
  14. [<img src="https://img.shields.io/badge/⭐_Star_to_show_love-FFD700?style=for-the-badge&logoColor=black" alt="Star to show love">](https://github.com/LetsFG/LetsFG)
  15. &nbsp;&nbsp;
  16. [<img src="https://img.shields.io/badge/🌐_Try_on_letsfg.co-4CAF50?style=for-the-badge&logoColor=white" alt="Try on letsfg.co">](https://letsfg.co/en)
  17. &nbsp;&nbsp;
  18. [<img src="https://img.shields.io/badge/📦_pip_install_letsfg-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="pip install">](https://pypi.org/project/letsfg/)
  19. <br>
  20. [<img src="assets/badge-instagram.svg" alt="Follow on Instagram">](https://www.instagram.com/letsfg_)
  21. &nbsp;&nbsp;
  22. [<img src="assets/badge-tiktok.svg" alt="Follow on TikTok">](https://www.tiktok.com/@letsfg_)
  23. &nbsp;&nbsp;
  24. [<img src="assets/badge-x.svg" alt="Follow on X">](https://x.com/LetsFG_)
  25. <br>
  26. ### Join the community. Help others find cheaper flights. Spread the word.<br>⭐ Star the repo. Share with a friend ✈️
  27. <a href="https://twitter.com/intent/tweet?text=Found%20this.%20Real%20flight%20prices%2C%20one%20total%20price.%20Your%20AI%20agent%20can%20search%20%26%20book%20flights%20now.&url=https%3A%2F%2Fgithub.com%2FLetsFG%2FLetsFG"><img src="https://img.shields.io/badge/Share_on_𝕏-000000?style=flat-square&logo=x&logoColor=white" alt="Share on X"></a>
  28. &nbsp;
  29. <a href="https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fgithub.com%2FLetsFG%2FLetsFG"><img src="https://img.shields.io/badge/Share_on_LinkedIn-0A66C2?style=flat-square&logo=linkedin&logoColor=white" alt="Share on LinkedIn"></a>
  30. &nbsp;
  31. <a href="https://reddit.com/submit?url=https%3A%2F%2Fgithub.com%2FLetsFG%2FLetsFG&title=LetsFG%20-%20AI%20flight%20search%20for%20agents.%20Real%20prices%2C%20one%20total%20price."><img src="https://img.shields.io/badge/Share_on_Reddit-FF4500?style=flat-square&logo=reddit&logoColor=white" alt="Share on Reddit"></a>
  32. &nbsp;
  33. <a href="https://wa.me/?text=Check%20this%20out!%20LetsFG%20searches%20every%20airline%20and%20gives%20you%20one%20total%20price.%20https%3A%2F%2Fgithub.com%2FLetsFG%2FLetsFG"><img src="https://img.shields.io/badge/Share_on_WhatsApp-25D366?style=flat-square&logo=whatsapp&logoColor=white" alt="Share on WhatsApp"></a>
  34. &nbsp;
  35. <a href="https://t.me/share/url?url=https%3A%2F%2Fgithub.com%2FLetsFG%2FLetsFG&text=LetsFG%20-%20AI%20flight%20search%20for%20agents.%20Real%20prices%2C%20one%20total%20price."><img src="https://img.shields.io/badge/Share_on_Telegram-26A5E4?style=flat-square&logo=telegram&logoColor=white" alt="Share on Telegram"></a>
  36. &nbsp;
  37. <a href="mailto:?subject=Check%20out%20LetsFG&body=Found%20this.%20Real%20flight%20prices%2C%20one%20total%20price.%20Your%20AI%20agent%20can%20search%20%26%20book%20flights%20now.%0A%0Ahttps%3A%2F%2Fgithub.com%2FLetsFG%2FLetsFG"><img src="https://img.shields.io/badge/Send_via_Email-EA4335?style=flat-square&logo=gmail&logoColor=white" alt="Send via Email"></a>
  38. ---
  39. # Flights and hotels. Both live.
  40. **Every airline in the world. Real prices. One function call.**
  41. LetsFG gives your AI agent flight **and hotel** search and booking superpowers. Our server-side engine scans the entire world for the cheapest price. Search is free. Booking is real: the fare is held on your card, a LetsFG booking agent buys the ticket, and you get the airline's PNR.
  42. **The same flight costs $20–$50 less** because you skip OTA inflation, cookie tracking, and surge pricing.
  43. **Claude:** LetsFG is in [Claude's connector directory](https://claude.ai/directory/letsfg): add it there, no URL to paste. **Other agents:** add `https://letsfg.co/mcp` as an MCP server. Approving the connection opens letsfg.co/connect: one tap, no card. The card is asked for at your first booking, in a 0.00 Revolut setup (nothing is charged, no Revolut account needed). That token searches for free and books. **Scripts:** send the same token as `Authorization: Bearer` to the PFS endpoints. **Developer API:** a separate paid product for high-volume commercial use; most agents do not need it. → [Get started](#get-started)
  44. <br>
  45. [![GitHub stars](https://letsfg.co/api/stars/badge)](https://github.com/LetsFG/LetsFG)
  46. [![PyPI](https://img.shields.io/pypi/v/letsfg)](https://pypi.org/project/letsfg/)
  47. [![npm](https://img.shields.io/npm/v/letsfg-mcp?label=npm%20%28MCP%29)](https://www.npmjs.com/package/letsfg-mcp)
  48. [![Connector Health](https://letsfg.co/developers/api/v1/analytics/connectors/health/badge)](https://letsfg.co/developers/connectors/health)
  49. [![MCPVault: claimed](https://mcpvault.io/badge/letsfg.svg)](https://mcpvault.io/servers/letsfg/health?utm_source=external_badge&utm_medium=referral&utm_campaign=mcp_health_report)
  50. [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  51. <br>
  52. ### Supporters
  53. <a href="https://evomi.com/?utm_source=letsfg&utm_medium=banner">
  54. <img src="assets/sponsor-evomi.png" alt="Evomi - Residential Proxies $0.49/GB" width="220">
  55. </a>
  56. </div>
  57. ---
  58. ## Real prices: LetsFG vs Google Flights
  59. We searched 5 routes on Google Flights and LetsFG on the same day (2026-08-05), for flights departing 2026-09-16. Same airline, same number of stops — LetsFG was cheaper every time:
  60. | Route | Airline | Google Flights | LetsFG | You Save |
  61. |-------|---------|---------------|--------|----------|
  62. | LAX → Paris (CDG) | JetBlue, 1 stop | $363 | **$334** | **$29** |
  63. | SFO → London (LHR) | JetBlue, 1 stop | $349 | **$333** | **$16** |
  64. | LA → New York (JFK) | JetBlue, nonstop | $174 | **$157** | **$17** |
  65. | London → Singapore (SIN) | Shenzhen Airlines, 1 stop | $395 | **$380** | **$15** |
  66. | Chicago → Dubai (DXB) | Air Canada + Emirates, 2 stops | $517 | **$461** | **$56** |
  67. > **$133 cheaper across 5 routes** in a verified comparison (2026-08-05). LetsFG returns the same prices however often you run the search, because it doesn't track you.
  68. **Why the difference?** LetsFG compares the same flight across many sellers — Skyscanner, Kayak, Momondo, plus airline websites (Ryanair, United, Southwest, EasyJet, Spirit, Norwegian, AirAsia, and more) — and shows the cheapest. No cookie tracking: the same search returns the same prices however often you run it.
  69. ---
  70. ## Real hotel prices: LetsFG vs Booking.com
  71. Same hotel, same room type, same 2-night stay, same free-cancellation policy — checked on the same day (2026-08-05) for a 2026-09-16 check-in:
  72. | Hotel | Booking.com | LetsFG | You Save |
  73. |-------|------------|--------|----------|
  74. | Hotel Boss, Warsaw | $206 | **$169** | **$37** |
  75. | ibis Styles Paris Gare de l'Est | $663 | **$525** | **$138** |
  76. | Copthorne Tara Hotel, London Kensington | $379 | **$347** | **$32** |
  77. > **$207 cheaper across 3 hotels** in a verified comparison (2026-08-05), matching each property's own free-cancellation rate against Booking.com's free-cancellation rate for the identical dates and room type. Prices quoted in PLN at booking, converted to USD at that day's rate.
  78. **Why the difference?** LetsFG's price does not rise with demand or with who is searching, and there is no loyalty-program cross-subsidy. At booking the price is held on your card, not taken, and it is charged only once the hotel confirms. The comparison above uses free-cancellation rates on both sides; LetsFG also sells non-refundable rates, and every offer says which it is.
  79. ---
  80. ## Try it right now — no install needed
  81. **Human users:** Use [letsfg.co](https://letsfg.co) and search flights instantly in your browser:
  82. <div align="center">
  83. ### 🌐 [**Search on letsfg.co**](https://letsfg.co)
  84. </div>
  85. Search any route, compare live results, and book the flights you want — no installation needed.
  86. **Agents / scripts (free server-side):** Get a Bearer token by putting a payment method on file (nothing is charged) → use `POST /api/search` and `POST /api/agent-book`. This is **PFS — Programmatic Flight Search** powered by the letsfg.co engine. Search is free; the token is short-lived and refreshes itself. See [letsfg.co/for-agents](https://letsfg.co/for-agents) for the full guide.
  87. When you're ready to integrate it into your own agent, keep reading.
  88. ---
  89. ## Three ways to use LetsFG
  90. | | **Path 1 — MCP / CLI / SDK** | **Path 2 — PFS** (Programmatic Flight Search via letsfg.co) | **Path 3 — Developer API** |
  91. |---|---|---|---|
  92. | **Best for** | AI agents (Claude, ChatGPT, Cursor, Windsurf), personal use — easiest way in | Scripts/agents calling the API directly with a Bearer token | High-volume commercial integrations that want prepaid billing. **Most agents should not use this** |
  93. | **Speed** | 8–10 s to first results | 8–10 s to first results | 2–5 s (discover) · 8–10 s to first results (full search) |
  94. | **Search cost** | Free (connect once: one tap, no card) | Free (connect once: one tap, no card) | Look-to-book: 200 free after every booking, then $0.01 |
  95. | **Booking** | `book_flight` — fare held on your card, agent buys the ticket, real PNR | `POST /api/agent-book` — same flow | `POST /flights/book` — same flow, no booking fee |
  96. | **Setup** | Add `https://letsfg.co/mcp` as an MCP server and approve (one tap, no card) | Same token, sent as `Authorization: Bearer` — see below | [letsfg.co/developers](https://letsfg.co/developers) |
  97. | **Runs where** | Our servers (ranking local in the SDK) | Our servers | Our servers |
  98. - **MCP / CLI / SDK (Path 1):** add `https://letsfg.co/mcp` as an MCP server in Claude, ChatGPT, Cursor or Windsurf and approve the connection. The consent step opens **letsfg.co/connect**: one tap, no card. The card is asked for at the first booking (any card, or Revolut Pay / Google Pay) in a 0.00 Revolut setup: nothing is charged, no Revolut account is needed, and card details go to Revolut, never to LetsFG. The token you get back searches for free, and once the card is added the same token books. The Python and JS SDKs read that token from `LETSFG_BEARER_TOKEN` or `~/.letsfg/config.json` and apply the open-source ranking algorithm locally. (`letsfg auth` runs this same connect flow from the terminal: it registers itself as an OAuth client, opens letsfg.co/connect in a browser for a person to approve, and stores the token.)
  99. - **PFS — Programmatic Flight Search (Path 2):** For scripts and agents that call the API directly. letsfg.co is human-only by default (Cloudflare Turnstile + bot protection), so the token from the connect flow is the only programmatic way in. Send it on every request:
  100. 1. Search: `POST https://letsfg.co/api/search` with `Authorization: Bearer <token>` → `{ search_id }`
  101. 2. Poll: `GET https://letsfg.co/api/results/<search_id>` (never counts against the rate limit)
  102. 3. Book: `POST https://letsfg.co/api/agent-book` → `{ booking_ref }` within seconds
  103. 4. Wait: `POST https://letsfg.co/api/agent-book/status` with `{ booking_ref }` every 20–30 s until `completed` (PNR), `failed` (hold released, nothing charged) or `needs_attention`
  104. `POST /api/agent-access/request` still answers `402` with `add_card_url` and these steps as JSON, so an agent that starts from the endpoint lands in the same place. The MPP lane (a wallet, no card) is unchanged: answer the `WWW-Authenticate: Payment` challenge ($0.01 once) and verify with `Authorization: Payment`. The Stripe `setup_url` / SetupIntent lanes were retired on 2026-09-02 and every token they issued was revoked; reconnect at letsfg.co/connect. Full guide and response schema: [letsfg.co/for-agents](https://letsfg.co/for-agents).
  105. - **Developer API (Path 3):** Server-side search and booking at [letsfg.co/developers](https://letsfg.co/developers). Look-to-book search (200 free after every booking, then $0.01), real booking through `POST /flights/book` on a connected Revolut method, full NL query parsing, a `/discover` endpoint that checks 20 destinations in one call (2–5 s), hotels, and a free sandbox at `/sandbox/flights/*` that simulates booking end to end (states, questions, failures, real timings). Full docs: [letsfg.co/developers/api/docs](https://letsfg.co/developers/api/docs).
  106. > **Free server-side search:** Use Path 1 or PFS — connect once at letsfg.co/connect (one tap, no card) and searches run free on our servers. No Playwright, no local install beyond the SDK.<br>
  107. > **Booking from your own product:** Use the Developer API (Path 3) — look-to-book search, `POST /flights/book`, and no booking or transaction fee. Hotels work on both the token from the connect flow and a Developer API key.
  108. ---
  109. ## Pricing
  110. | How you use it | Search | Flight booking | Hotel booking | Runs where? |
  111. |----------------|--------|----------------|----------------|-------------|
  112. | **MCP Server** | ✅ Free (connect once at letsfg.co/connect, no card) | Price held, captured on a real PNR. No separate fee | Price held, captured once the hotel confirms. No reservation fee | Our servers |
  113. | **CLI / Python SDK / npm** | ✅ Free (same token) | Same | Same | Our servers |
  114. | **PFS** (raw API via letsfg.co) | ✅ Free (same token, or $0.01 once via MPP) | Same | Price held, captured once the hotel confirms. No reservation fee | Our servers |
  115. | **Developer API** | 200 free per booking, then $0.01 | Price held, captured on a real PNR. No booking fee, no transaction fee | Price held, captured once the hotel confirms. No reservation fee | Our servers |
  116. **MCP / CLI / SDK / PFS = free search, real booking, no separate fee.** Connect once (one tap, no card) and searching is free. The card is asked for at the first booking, in a 0.00 Revolut setup (nothing is charged). No credits, no unlock step. Booking works exactly like the website checkout: `book_flight` / `POST /api/agent-book` **holds** the price shown on your card, a LetsFG booking agent buys the ticket from the seller, and the hold is captured only once a real airline PNR exists. If the booking fails the hold is released and nothing is charged. The price you see is the price you pay; nothing is added at booking.
  117. **Hotels = the price on the offer, held then captured, on every path.** Booking holds the full price on your card, LetsFG books and pays the hotel, and the hold is captured only once the hotel confirms; a failed booking releases it. There is no reservation fee, no deposit and no pay link. Every rate type is sold, and each offer says whether it is refundable and until when. See [Hotels](#-hotels--new-and-live) below.
  118. **Developer API = business use, look-to-book.** [letsfg.co/developers](https://letsfg.co/developers) books flights itself — `POST /flights/book` holds the fare on your connected Revolut method and a LetsFG booking agent buys the ticket, exactly like the other paths. Search is **not** priced per call: you get **200 free searches after every booking you make**, and booking resets the counter. Past that, blocks of 500 for $5.00 ($0.01 each). **No booking fee, no transaction fee** on top: the amount the search returned is the amount charged. Minimum top-up: $5.
  119. > The monthly per-search tiers ($0.50 / $0.20 / $0.10) were retired on 2026-09-08 along with Stripe. Payments are Revolut: `POST /agents/connect-payment` returns a one-time link that saves a card, and nothing is charged to connect.
  120. > 💡 **Know someone who travels?** The more people discover LetsFG, the more airlines we cover — and the better it gets for everyone. **[⭐ Star](https://github.com/LetsFG/LetsFG)** · **[Share with a friend](#-join-the-community-)**
  121. ---
  122. ## Why developers star this repo
  123. | | Google Flights / Expedia | **LetsFG** |
  124. |---|---|---|
  125. | Price | Varies by site and search | **Stable across repeat searches. $133 cheaper across 5 routes, verified 2026-08-05.** |
  126. | Coverage | One site's sources | **Every airline in the world — OTAs, budget carriers, full-service** |
  127. | Speed | 30 s+ (page loads, ads, redirects) | **CLI/PFS: 8–10 s to first results · API discover: 2–5 s** |
  128. | Repeat search raises price? | Yes | **Never** |
  129. | Works in AI agents? | No API | **MCP · CLI · PFS (connect once, free) · Developer API (prepaid)** |
  130. | Booking | Redirects to OTA checkout | **Real airline PNR, e-ticket to inbox** |
  131. | Cabin class filter | No | **Economy, premium, business, first** |
  132. | Cost to you | Varies by site | **CLI/PFS: free search; no booking fee and no transaction fee. Developer API: 200 free searches after every booking, then $0.01/search; no booking fee, no transaction fee.** |
  133. ---
  134. ## Get started
  135. Everything runs on our servers. One connection covers the MCP, the SDKs and the raw API.
  136. ### 🔌 MCP — connect once, search and book
  137. Add the remote server and approve the connection. The consent step opens letsfg.co/connect: one tap, no card, and you are in. The card is asked for at the first booking (0.00 setup, nothing charged).
  138. ```bash
  139. # Claude Code
  140. claude mcp add --transport http letsfg https://letsfg.co/mcp
  141. ```
  142. ```json
  143. // Cursor (~/.cursor/mcp.json) — Windsurf uses "serverUrl" instead of "url"
  144. { "mcpServers": { "letsfg": { "url": "https://letsfg.co/mcp" } } }
  145. ```
  146. Claude: LetsFG is in Claude's official connector directory. Open **[claude.ai/directory/letsfg](https://claude.ai/directory/letsfg)**, add it and approve the connection. No URL to paste. Once added, it works in Claude Desktop and the Claude phone app too.
  147. ChatGPT: add it at chatgpt.com in a browser (the ChatGPT phone app has no way to add one): Plugins > Add > Add custom MCP server, URL `https://letsfg.co/mcp`, authentication OAuth, tick I understand, Create as a plugin. Once added, it works in the ChatGPT phone app too.
  148. Then, in the chat: *"find me the cheapest flight from London to Barcelona on June 15 and book it"*. `search_flights` returns offers; `book_flight` holds the fare on your card and starts a LetsFG booking agent; `get_flight_booking` reports the PNR when it lands (4–11 minutes).
  149. ### 🖥️ CLI / SDK — same token, ranking runs locally
  150. ```bash
  151. pip install letsfg
  152. export LETSFG_BEARER_TOKEN=<token from the connect flow>
  153. letsfg search LHR BCN 2026-06-15
  154. letsfg search LHR JFK 2026-06-15 --cabin C # cabin class: M economy, W premium, C business, F first
  155. ```
  156. The SDKs read the token from `LETSFG_BEARER_TOKEN` or `~/.letsfg/config.json`. `letsfg auth` performs that connect flow itself: it registers as an OAuth client, opens https://letsfg.co/connect for a person to approve, and writes the token to `~/.letsfg/config.json`. Add `--no-browser` to print the URL instead of opening one. Where letsfg.co offers its code hand-off, the CLI picks the approval up from letsfg.co (it works from a sandbox or another machine); otherwise it listens on 127.0.0.1. If it stopped waiting before you approved, run `letsfg auth --finish '<the address your browser landed on>'` within 10 minutes of approving.
  157. ### 🔌 PFS — Programmatic Flight Search (free, server-side)
  158. Run LetsFG's full search on our servers from any script. **Access requires the token from the connect flow:** letsfg.co is human-only (Cloudflare Turnstile), so that token is the only programmatic way in. Connecting is one tap and needs no card; the card is asked for at the first booking.
  159. ```bash
  160. # 1. Search with the token
  161. curl -X POST https://letsfg.co/api/search \
  162. -H "Authorization: Bearer <token>" \
  163. -H "Content-Type: application/json" \
  164. -d '{"origin":"LHR","destination":"BCN","date_from":"2026-06-15"}'
  165. # → {"search_id":"ws_abc123","status":"searching"}
  166. # 2. Poll until done (keep going while split_ticket_pending is true)
  167. curl https://letsfg.co/api/results/ws_abc123 -H "Authorization: Bearer <token>"
  168. # 3. Book — the fare is HELD on the card, a LetsFG agent buys the ticket
  169. curl -X POST https://letsfg.co/api/agent-book \
  170. -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  171. -d '{"search_id":"ws_abc123","offer_id":"wo_abc123","contact_email":"ada@example.com",
  172. "passenger":{"given_name":"Ada","family_name":"Lovelace","born_on":"1990-04-01","gender":"f",
  173. "nationality":"GB","phone_number":"+447700900000","phone_country":"GB",
  174. "address_line1":"1 Analytical Way","address_city":"London","address_postal":"N1 9GU","address_country":"GB"}}'
  175. # → {"booking_ref":"eyJ..."} within seconds
  176. # 4. Wait for the PNR (every 20–30 s; a booking takes 4–11 minutes)
  177. curl -X POST https://letsfg.co/api/agent-book/status \
  178. -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  179. -d '{"booking_ref":"eyJ..."}'
  180. # → {"state":"completed","pnr":"ABC123","charged_amount":93,"currency":"EUR"}
  181. ```
  182. `failed` means the hold was released and nothing was charged; `needs_attention` means a human at LetsFG is checking it, do not book again. A missing passenger detail returns `missing_fields` and charges nothing. Without a card the endpoint answers `payment_method_required` with `add_card_url`. Full guide and response schema: [letsfg.co/for-agents](https://letsfg.co/for-agents).
  183. ### ⚡ Developer API — server-side search, booking and hotels
  184. A **separate product** for high-volume commercial integrations; most agents should not use it. Look-to-book search, results in seconds, and real booking through `POST /flights/book` — plus `/discover` (20 destinations in one call), async polling, NL query parsing, hotels, and a free sandbox where booking works end to end (same responses, states, questions and timings as production, no money) - [build your booking flow there first](https://letsfg.co/developers/docs/api-sandbox#booking-in-the-sandbox).
  185. ```bash
  186. # Register, then search with your API key
  187. curl -X POST https://letsfg.co/developers/api/v1/agents/register \
  188. -H "Content-Type: application/json" \
  189. -d '{"agent_name":"my-agent","email":"you@example.com"}'
  190. curl -X POST https://letsfg.co/developers/api/v1/flights/search \
  191. -H "X-API-Key: letsfg_..." \
  192. -H "Content-Type: application/json" \
  193. -d '{"origin":"LHR","destination":"BCN","date_from":"2026-06-15"}'
  194. ```
  195. Pricing: 200 searches free after every booking, then blocks of 500 for $5.00 ($0.01 each). No booking fee, no transaction fee. Minimum top-up $5. Test for free in the sandbox first, booking included. Full docs: [letsfg.co/developers/api/docs](https://letsfg.co/developers/api/docs).
  196. <details>
  197. <summary><strong>Full search → book flow (MCP / PFS agent path, no unlock step)</strong></summary>
  198. ```
  199. search_flights LON → BCN, 2026-04-01, return 2026-04-08
  200. get_flight_results (while more offers are still landing)
  201. book_flight search_id + offer_id + one traveller's real details + contact_email
  202. → booking_ref in seconds; price HELD on the connected card
  203. get_flight_booking every 20–30 s → completed (PNR, charged_amount) | failed (hold released) | needs_attention
  204. ```
  205. Over raw HTTP the same four steps are `POST /api/search`, `GET /api/results/<id>`, `POST /api/agent-book`, `POST /api/agent-book/status`.
  206. `letsfg unlock` was **retired on 2026-09-08** and its route answers `410 Gone`.
  207. There is no unlock step on either lane: booking holds the fare and captures only
  208. against a real PNR, which is what unlock existed to protect against. See
  209. [CLI Commands](#cli-commands).
  210. </details>
  211. > 💡 **Like what you see?** Support us — **[⭐ Star](https://github.com/LetsFG/LetsFG)** · **[Share with a friend](#-join-the-community-)**
  212. ---
  213. ## Works everywhere your agent runs
  214. ### MCP Server (Claude / ChatGPT / Cursor / Windsurf / OpenClaw)
  215. Use the hosted server. It carries your token for you, and `book_flight` books for real.
  216. ```json
  217. {
  218. "mcpServers": {
  219. "letsfg": {
  220. "url": "https://letsfg.co/mcp"
  221. }
  222. }
  223. }
  224. ```
  225. Approve the connection when your client asks; the consent step opens letsfg.co/connect: one tap, no card. The card is asked for at the first booking (0.00 setup, nothing charged). Tools: `search_flights`, `get_flight_results`, `book_flight`, `get_flight_booking`, plus the hotel tools.
  226. The stdio package (`npx -y letsfg-mcp`) works too if you give it a token in `LETSFG_BEARER_TOKEN`; its `authenticate` tool returns the current connect instructions.
  227. <details>
  228. <summary>Optional: use the Developer API instead (look-to-book search, POST /flights/book, hotels)</summary>
  229. ```json
  230. {
  231. "mcpServers": {
  232. "letsfg": {
  233. "command": "npx",
  234. "args": ["-y", "letsfg-mcp"],
  235. "env": {
  236. "LETSFG_API_KEY": "letsfg_your_api_key"
  237. }
  238. }
  239. }
  240. }
  241. ```
  242. This is a **separate paid product** for high-volume commercial use — most agents should stick with the free connect flow above and skip this. A human setting this up deliberately gets a key at [letsfg.co/developers](https://letsfg.co/developers).
  243. </details>
  244. **5-minute quickstarts:** [Claude](docs/quickstart-claude.md) · [Cursor](docs/quickstart-cursor.md) · [Windsurf](docs/quickstart-windsurf.md)
  245. ### Python SDK
  246. ```python
  247. from letsfg import LetsFG
  248. bt = LetsFG() # reads LETSFG_API_KEY from env
  249. flights = bt.search("LHR", "JFK", "2026-04-15")
  250. print(f"{flights.total_results} offers, cheapest: {flights.cheapest.summary()}")
  251. ```
  252. ### JavaScript SDK
  253. ```typescript
  254. import { LetsFG } from 'letsfg';
  255. const bt = new LetsFG({ apiKey: 'letsfg_...' });
  256. const flights = await bt.search('LHR', 'JFK', '2026-04-15');
  257. console.log(`${flights.totalResults} offers`);
  258. ```
  259. ### Python SDK (cloud search)
  260. ```python
  261. from letsfg.local import search_local
  262. # Reads LETSFG_BEARER_TOKEN env var or ~/.letsfg/config.json (the token from the connect flow)
  263. result = await search_local("GDN", "BCN", "2026-06-15")
  264. for offer in result.offers[:5]:
  265. print(f"{offer.airlines[0]}: {offer.currency} {offer.price}")
  266. ```
  267. ---
  268. ## ⇄ Split tickets — two tickets, one trip
  269. A long-haul searched as one journey comes back as one through-fare, because
  270. everyone is reselling the same ticket. Searched as two independent legs through
  271. a hub, each leg is booked from whatever is cheapest for that hop — whichever
  272. airline, whichever seller. Usually that lands on two different airlines (often a
  273. low-cost carrier for the short leg and a separate airline for the long one), but
  274. the only rule is "cheapest for each leg". Nobody sells the combination as one
  275. ticket, so nobody quotes it — which is exactly why it is cheaper.
  276. LetsFG builds that itinerary for you and returns it alongside the through-fares.
  277. Split offers are flagged, never disguised:
  278. | Field | Value on a split offer |
  279. |---|---|
  280. | `split_ticket` | `"true"` |
  281. | `combo_type` | `"virtual_interlining"` |
  282. | `self_transfer` | `"unprotected"` |
  283. ```python
  284. for o in offers:
  285. if o.get("split_ticket") == "true":
  286. print(o["price"], "— two separate tickets, self-transfer not protected")
  287. ```
  288. **Read `self_transfer` before you present the price.** `unprotected` means the
  289. two tickets are not linked: if the first flight is late and the connection is
  290. missed, the second airline owes nothing — no rebooking, no refund, no
  291. duty of care. That is the trade you are being offered in exchange for the
  292. saving, and it has to reach the traveller. We only build a split when the
  293. connection has a real buffer, and we say so on the offer — but an
  294. agent that relays the price without the condition is misrepresenting it.
  295. **The probe is gated.** Two extra connector fan-outs cost real money, so a
  296. split is only attempted when the through-fare is expensive enough, the journey
  297. long enough, and the market has somewhere to break the trip. Most searches
  298. never fire it, and a search that fires it does not always find a saving.
  299. **It lands after `completed`.** See
  300. [Polling: `completed` is not the end](#polling-completed-is-not-the-end).
  301. **Where it runs.** letsfg.co, and the agent lane behind it — the CLI,
  302. the Python and JS SDKs, and the MCP server. The paid Developer API is served by
  303. a different backend; `self_transfer` is returned there, but split-ticket offers
  304. are not part of that contract.
  305. ### What it actually saves
  306. <!-- SPLIT-TABLE:START — generated by tools/split-comparison.py, do not hand-edit -->
  307. | Route | Cheapest single ticket | Split — two tickets | You save | Connect via | Two airlines | Layover |
  308. |---|---|---|---|---|---|---|
  309. | Stuttgart → Shanghai | $552 | **$461** | **$91 (16%)** | Budapest | Wizz Air + Qatar Airways | 6 h |
  310. | Katowice → Dubai | $283 | **$216** | **$67 (24%)** | Istanbul | Wizz Air + Pegasus | 15 h |
  311. | Chongqing → Gdansk | $429 | **$387** | **$42 (10%)** | Stockholm | China Eastern + Ryanair | 10 h |
  312. | Vilnius → Bangkok | $370 | **$337** | **$33 (9%)** | Athens | Ryanair + Air Arabia | 5 h |
  313. | Shanghai → Vilnius | $406 | **$377** | **$29 (7%)** | London | Shenzhen Airlines + Wizz Air | 12 h |
  314. <sub>Measured August 2026 on live searches (one adult, one way, ~2 months out). Each split is <strong>two separate tickets</strong> (here, two different airlines) with an <strong>unprotected self-transfer</strong> — if the first flight is late, the second airline owes you nothing. Prices move constantly; these won't reproduce exactly. 5 of 26 long-haul routes searched produced a split cheaper than the best single ticket — the win shows up at secondary cities with no cheap direct long-haul. Regenerate with <code>tools/split-comparison.py</code>.</sub>
  315. <!-- SPLIT-TABLE:END -->
  316. The numbers above come from real searches and are reproducible: the script runs
  317. the same public search anyone can run, compares the cheapest split against the
  318. cheapest single ticket **in the same result set**, and writes the raw offers to
  319. `split-comparison.json` so any row can be checked. Routes that produced no split
  320. are reported too rather than dropped quietly — most searches never fire
  321. a split probe, and a table that hid that would misrepresent how often this
  322. happens.
  323. ## ✦ Starlink Wi-Fi on results
  324. Offers tell you whether the flight has Starlink, in two honest tiers. A solid
  325. verdict (`confirmed_all`) means the airline has fitted **every** aircraft of that
  326. type. A hedged one (`likely_all`) means the rollout on that type is real but
  327. incomplete — as of August 2026 United was ~29% of its fleet — so it is reported
  328. as a signal, never a promise. An absent field means no information, not an
  329. absence of Wi-Fi.
  330. ```python
  331. for o in offers:
  332. if o.get("starlink") == "confirmed_all":
  333. print(f"{o['owner_airline']} {o['price']} — Starlink on every leg")
  334. ```
  335. Full semantics: [docs/api-search.md](docs/api-search.md#starlink-wi-fi).
  336. ## 🏨 Hotels — new, and live
  337. Your agent can now book hotels, not just flights. Same credential, same card on file.
  338. > **Update your SDK before booking hotels.** Hotel booking needs **letsfg 2026.5.101** or later (Python),
  339. > **letsfg 2026.5.74** or later (JavaScript/TypeScript) or **letsfg-mcp 2026.5.77** or later. Earlier releases send
  340. > the reservation-fee fields retired on 2026-09-11 (`expected_balance`, no `expected_cost`), and the API refuses
  341. > every hotel booking they make. Update with `pip install -U letsfg`, `npm install letsfg@latest` or
  342. > `npx -y letsfg-mcp@latest`. The hosted MCP at `https://letsfg.co/mcp` needs no update.
  343. ```python
  344. from letsfg import LetsFG
  345. lfg = LetsFG() # reads LETSFG_API_KEY — the SDK's hotel methods take a Developer API key
  346. city = lfg.hotel_destinations("Warsaw")[0]
  347. stays = lfg.search_hotels(
  348. city_id=city["Id"], city_name=city["Name"],
  349. check_in="2026-11-10", check_out="2026-11-12", adults=2,
  350. )
  351. hotel = stays["hotels"][0]
  352. offer = hotel["offers"][0]
  353. print(hotel["name"], offer["price"], offer["currency"],
  354. "refundable" if offer["refundable"] else "non-refundable")
  355. booking = lfg.book_hotel_and_wait(
  356. session_id=offer["session_id"],
  357. hotel_code=hotel["hotel_code"],
  358. combination_id_v2=offer["combination_id_v2"],
  359. expected_price=offer["price"],
  360. expected_cost=offer["expected_cost"],
  361. currency=offer["currency"],
  362. fx_rate=offer["fx_rate"],
  363. city_id=city["Id"], city_name=city["Name"],
  364. check_in="2026-11-10", check_out="2026-11-12",
  365. guests=[{"title": "Mr", "first_name": "Jan", "last_name": "Kowalski"}, # one entry per guest:
  366. {"title": "Ms", "first_name": "Anna", "last_name": "Kowalska"}], # adults=2 -> two names
  367. email="guest@example.com", phone="512345678",
  368. )
  369. print(booking["status"], booking.get("confirmation"), booking.get("total_price"), booking.get("currency"))
  370. ```
  371. ### How you pay
  372. **Held at booking, charged when the hotel confirms.** Booking holds the full
  373. `price` on your card — it is not taken. LetsFG books the room and pays the
  374. supplier itself, and the hold is captured only once the hotel has confirmed. If
  375. the booking fails for any reason (the rate is gone, the price moved, the supplier
  376. declined) the hold is released and nothing is charged. There is no reservation
  377. fee, no deposit and no pay link.
  378. `price` is the all-in total, in the `currency` you searched in (USD by default).
  379. A refundable booking cancelled before its `free_cancellation_until` is refunded
  380. in full. The endpoint refuses a cancellation that would cost money; the hotel's
  381. own ladder ships in the booking's `terms`, so you can always see the cost first.
  382. ### Things worth knowing before you build
  383. - **Searching hotels needs no card; booking one does.** A hotel search opens a
  384. real session at the supplier, so an account with no card on file gets a daily
  385. number of hotel searches. Booking asks for the card before anything is held:
  386. `book_hotel` returns a link to add it, as `book_flight` does. The same card
  387. that authorises flight booking authorises hotels — there is no separate hotel
  388. signup.
  389. - **Every rate type is sold, refundable and non-refundable.** Each offer carries
  390. `refundable` and `free_cancellation_until`; show them to the guest before
  391. booking a non-refundable rate.
  392. - **Booking is asynchronous.** `book_hotel` returns a `booking_job_id`, not a
  393. booking — the real thing takes minutes. Poll `hotel_booking(job_id)` until
  394. `status` is `succeeded`, `failed` or `attention`, or call `book_hotel_and_wait`.
  395. `attention` means a person at LetsFG is confirming the outcome with the
  396. supplier: the hold is kept, nothing is charged, and you must not book again.
  397. - **Copy the offer back verbatim.** Send `expected_price`, `expected_cost`,
  398. `currency` and `fx_rate` exactly as the offer returned them; anything else is
  399. refused as `price_mismatch` before anything is held.
  400. - **Name every guest.** `guests` needs one entry per person in the room,
  401. children included: adults first, then children in `child_ages` order. Fewer
  402. names than the searched party fails the booking before anything reaches the
  403. hotel, and the hold is released.
  404. - **Do not re-book while a job is running.** Poll it. A retry with the same
  405. `idempotency_key` returns the existing job instead of booking twice.
  406. - **The guest hears from us either way.** The guest's e-mail gets the
  407. confirmation, or a message if the booking fails or needs checking.
  408. - `price` is what the guest pays. `expected_cost` is the supplier's own figure,
  409. there only to be sent back — never quote it.
  410. ### JavaScript
  411. ```javascript
  412. import { LetsFG } from 'letsfg';
  413. const lfg = new LetsFG({ apiKey: process.env.LETSFG_API_KEY });
  414. const [city] = await lfg.hotelDestinations('Warsaw');
  415. const stays = await lfg.searchHotels({
  416. cityId: city.Id, cityName: city.Name,
  417. checkIn: '2026-11-10', checkOut: '2026-11-12', adults: 2,
  418. });
  419. const booking = await lfg.bookHotelAndWait({ /* ...offer + guest details... */ });
  420. console.log(booking.status, booking.confirmation, booking.total_price, booking.currency);
  421. ```
  422. ### MCP
  423. Five new tools, in the order you call them: `resolve_hotel_city` →
  424. `search_hotels` → `book_hotel` → `get_hotel_booking` → `cancel_hotel_booking`.
  425. ---
  426. ## 🖥️ Omarchy desktop plugin
  427. Search every airline in the world from the [Omarchy](https://omarchy.org) bar. Type
  428. two airport codes and a date, press Search, click an offer to open it. The
  429. panel lives in this repo — `manifest.json`, `BarWidget.qml`, `Panel.qml` and
  430. `Model.js` at the root — and runs on the same engine as the CLI and the MCP
  431. server, ordered by the same open-source ranking algorithm in `sdk/js/src/ranking.ts`.
  432. <p align="center"><img src="preview.png" alt="LetsFG Flights panel in the Omarchy bar" width="820"></p>
  433. **Install**
  434. ```bash
  435. omarchy plugin add https://github.com/LetsFG/LetsFG.git --enable
  436. ```
  437. Then add **LetsFG Flights** to a bar section in the Omarchy bar settings. The
  438. panel reads your LetsFG token from `~/.letsfg/config.json` (what `letsfg auth`
  439. writes) and renews it itself, or connects from the panel via
  440. letsfg.co/connect — one tap, no card. See
  441. [OMARCHY-PLUGIN.md](OMARCHY-PLUGIN.md).
  442. **Remove**
  443. ```bash
  444. omarchy plugin remove io.github.letsfg.flights
  445. ```
  446. That removes the plugin only. Your token is yours — delete
  447. `~/.letsfg/config.json` yourself if you want it gone.
  448. **The plugin bundles no API keys.** It authenticates with a token you create
  449. and can revoke, it never asks for card details, and it never starts a search on
  450. its own — no background poll, no price watch, no refresh timer. Every host it
  451. can contact, every file it reads or writes, and the anonymous installation id
  452. it sends so we can tell whether anyone is using it, are documented in full in
  453. **[OMARCHY-PLUGIN.md](OMARCHY-PLUGIN.md)**.
  454. Requires the Omarchy Quattro shell. MIT, like the rest of this repo. Not
  455. affiliated with, sponsored by, or endorsed by Omarchy or 37signals.
  456. ---
  457. ## Install
  458. | Package | Command | What you get |
  459. |---------|---------|--------------|
  460. | **Remote MCP** | `https://letsfg.co/mcp` | No install. Approve the connection at letsfg.co/connect (one tap, no card), search and book |
  461. | **Python SDK + CLI** | `pip install letsfg` | SDK + CLI (token from the connect flow in `LETSFG_BEARER_TOKEN`) |
  462. | **MCP Server (stdio)** | `npx letsfg-mcp` | Local server for clients without remote MCP support; needs `LETSFG_BEARER_TOKEN` |
  463. | **JS/TS SDK** | `npm install -g letsfg` | SDK + CLI + open-source ranking engine |
  464. | **Agent Skill** | `npx skills add LetsFG/LetsFG` | Install flight search skill for any AI agent ([skills.sh](https://skills.sh)) |
  465. | **Smithery** | [smithery.ai/servers/letsfg](https://smithery.ai/servers/letsfg) | One-click MCP install |
  466. | **Omarchy plugin** | `omarchy plugin add https://github.com/LetsFG/LetsFG.git --enable` | Flight search in the Omarchy bar ([details](OMARCHY-PLUGIN.md)) |
  467. ---
  468. ## CLI Commands
  469. | Command | Description |
  470. |---------|-------------|
  471. | `letsfg auth` | Connect at letsfg.co/connect (one tap, no card) and store the token (self-registers, PKCE + letsfg.co hand-off or loopback redirect, opens a browser). `--no-browser` prints the URL; `--finish '<address>'` ends a sign-in whose terminal stopped waiting |
  472. | `letsfg search <origin> <dest> <date>` | Search flights (free with the token from the connect flow) |
  473. | `letsfg register` | **[Developer API only]** Register an account for the paid, prepaid-credit product — not part of the agent flow |
  474. | `letsfg connect-payment` | **[Developer API only]** Print a one-time link to connect a card to the paid account; nothing is charged. `letsfg setup-payment` is kept as an alias — the Stripe route it once called was retired on 2026-09-08 and answers `410 Gone` |
  475. | `letsfg recover --email <email>` | Recover lost API key via email |
  476. | `letsfg locations <query>` | Resolve city/airport to IATA codes |
  477. | `letsfg unlock <offer_id>` | **RETIRED 2026-09-08** — the route answers `410 Gone`. There is no unlock step on either lane; use `letsfg book` |
  478. | `letsfg book <offer_id>` | Book the flight: holds the fare on the connected card, a LetsFG agent buys the ticket, returns a `booking_ref` to poll |
  479. | `letsfg me` | View profile & usage stats |
  480. All commands accept `--json` for structured output and `--api-key` to override the env variable.
  481. ---
  482. ## How it works
  483. ### CLI / SDK / MCP (free, cloud-backed)
  484. ```
  485. Connect the MCP (once, one tap at letsfg.co/connect) → token → Search (free) → Book (card asked for at the first booking; hold → agent → PNR)
  486. ```
  487. 1. **Auth** — add `https://letsfg.co/mcp` as an MCP server and approve it. The OAuth consent step opens letsfg.co/connect: one tap, no card. The card is asked for at the first booking, in a 0.00 Revolut setup. Nothing is charged to connect. The SDKs read that token from `LETSFG_BEARER_TOKEN` or `~/.letsfg/config.json`.
  488. 2. **Search** — `letsfg search LHR BCN 2026-06-15` calls `POST https://letsfg.co/api/search`, polls until done (8–10 s to first results), and applies the open-source ranking algorithm locally.
  489. 3. **Book** — `POST /api/agent-book` holds the price shown on the card and starts a LetsFG booking agent; `POST /api/agent-book/status` reports `completed` with the PNR (4–11 minutes), or `failed` with the hold released. Nothing extra is added at booking.
  490. ### Polling: `completed` is not the end
  491. A search returns in 8–10 s to first results. Poll `GET /api/results/<search_id>`
  492. **immediately** and then every 2 s — a loop that sleeps first puts a
  493. floor under a search that is already faster than the sleep.
  494. When `status` leaves `searching`, the connector fan-out is done — but
  495. the offer set may still be growing. The split-ticket probe is dispatched after
  496. the fan-out and merges its result in late, so the cheapest itinerary on the
  497. search is routinely one that does not exist yet at the moment the status turns
  498. terminal. The response says so:
  499. | Flag | Meaning while `true` |
  500. |---|---|
  501. | `split_ticket_pending` | a split-ticket probe is still running |
  502. | `gf_enrich_pending` | the Google Flights enrich has not merged yet |
  503. Keep polling while either is true, and **bound the wait** — a flag
  504. that never clears must not hang your agent. Take whatever has landed when the
  505. bound expires.
  506. The Python and JS SDKs and the MCP server already do this, with a 90 s ceiling
  507. — the same window the server uses to decide a result has settled.
  508. So a search that fires a split probe can take meaningfully longer than the
  509. 8–10 s to first results fast path, and it is the split offer you are waiting for.
  510. Set `LETSFG_WAIT_FOR_SPLIT=0` if you would rather have the fast answer.
  511. Most searches never fire the probe, so both flags are usually already false on
  512. the first poll and this costs nothing.
  513. ### PFS — raw API (same as CLI, without the wrapper)
  514. ```
  515. Connected at letsfg.co/connect -> Bearer token -> POST /api/search -> poll GET /api/results/<id> -> POST /api/agent-book -> poll POST /api/agent-book/status
  516. ```
  517. 1. **Get a Bearer token** — connect through the MCP OAuth flow; the consent step is letsfg.co/connect (one tap, no card; the card or Revolut Pay is asked for at the first booking, 0.00, nothing charged). `POST /api/agent-access/request` answers `402` with `add_card_url` and the steps. The MPP wallet lane ($0.01 once) verifies at `POST /api/agent-access/verify` with `Authorization: Payment`.
  518. 2. **Search** — `POST https://letsfg.co/api/search` with `Authorization: Bearer <token>`. Returns `{ search_id }`. Poll `GET /api/results/<search_id>` immediately, then every 2 s, until `status` leaves `searching`. Then keep polling while `split_ticket_pending` or `gf_enrich_pending` is true — the split-ticket offer merges in after the status turns terminal.
  519. 3. **Book** — `POST /api/agent-book` → `booking_ref`; poll `POST /api/agent-book/status` until `completed` (PNR) or `failed` (hold released, nothing charged).
  520. ### Developer API — server-side search and booking
  521. ```
  522. Register → Connect a Revolut method → Search (200 free per booking) → POST /flights/book → poll to a PNR
  523. ```
  524. 1. **Discover** — `POST /flights/discover` with up to 20 destinations, get indicative prices sorted cheapest-first. 1 credit, 2–5 s. Use to rank options before committing to a full search.
  525. 2. **Full search** — `POST /flights/search` (blocking) or `/flights/search/async` (non-blocking + poll). 1 credit, 8–10 s to first results.
  526. 3. **Book** — each offer includes a direct airline `booking_url`. No LetsFG fee, no checkout step.
  527. <details>
  528. <summary><strong>Virtual interlining</strong></summary>
  529. The server-side engine builds cross-airline round-trips by combining one-way fares from different carriers. A Ryanair outbound + Wizz Air return can save 30-50% vs booking a round-trip on either airline alone.
  530. </details>
  531. <details>
  532. <summary><strong>City-wide airport expansion</strong></summary>
  533. Search a city code and LetsFG automatically searches all airports in that city. `LON` expands to LHR, LGW, STN, LTN, SEN, LCY. `NYC` expands to JFK, EWR, LGA. Works for 25+ major cities worldwide.
  534. </details>
  535. ---
  536. ## Architecture
  537. **CLI / SDK / MCP / PFS**
  538. ```
  539. CLI / SDK / MCP / AI Agent
  540. │ Connected at letsfg.co/connect (one tap) -> Bearer token
  541. ▼
  542. POST letsfg.co/api/search (bot-protected, token required)
  543. │
  544. ▼
  545. letsfg.co server-side search engine
  546. │
  547. ▼
  548. GET /api/results/<search_id> (poll every 2 s; keep going while split_ticket_pending)
  549. │
  550. ▼
  551. Ranking applied locally (sdk/js/src/ranking.ts, open-source)
  552. │
  553. ▼
  554. Results + booking via POST /api/agent-book (hold on card -> LetsFG agent -> PNR)
  555. ```
  556. **Developer API**
  557. ```
  558. Product / Team / Agent
  559. │ API key + a connected Revolut method
  560. ▼
  561. letsfg.co/developers/api/v1
  562. ├─ /flights/discover (indicative prices, 20 dest, 2–5 s)
  563. ├─ /flights/search (full search, 8–10 s to first results)
  564. ├─ /flights/search/async (non-blocking + poll)
  565. ├─ /flights/parse-query (Gemini NL parsing, free)
  566. ├─ /flights/book (holds the fare on the connected method)
  567. ├─ /flights/bookings/{id} (poll to a real PNR, 4–11 min)
  568. └─ /sandbox/flights/* (free: search + simulated booking, same schema)
  569. │
  570. ▼
  571. Real airline PNR - the hold is captured only once it exists
  572. ```
  573. <details>
  574. <summary><strong>Airlines covered</strong></summary>
  575. | Region | Airlines |
  576. |--------|----------|
  577. | **Europe** | Ryanair, Wizz Air, EasyJet, Norwegian, Vueling, Eurowings, Transavia, Pegasus, Turkish Airlines, Condor, SunExpress, Volotea, Smartwings, Jet2, LOT Polish Airlines, Finnair, SAS, Aegean, Aer Lingus, ITA Airways, TAP Portugal, Icelandair, PLAY |
  578. | **Middle East & Africa** | Emirates, Etihad, Qatar Airways, flydubai, Air Arabia, flynas, Salam Air, Air Peace, FlySafair, EgyptAir, Ethiopian Airlines, Kenya Airways, Royal Air Maroc, South African Airways |
  579. | **Asia-Pacific** | AirAsia, AirAsia X, IndiGo, SpiceJet, Akasa Air, Air India, Air India Express, Alliance Air, Star Air, EaseMyTrip OTA, VietJet, Cebu Pacific, Scoot, Jetstar, Peach, Spring Airlines, Lucky Air, 9 Air, Nok Air, Batik Air, Jeju Air, T'way Air, ZIPAIR, Skymark, H.I.S. Travel OTA, Singapore Airlines, Cathay Pacific, Malaysian Airlines, Thai Airways, Korean Air, ANA, JAL, Qantas, Virgin Australia, Bangkok Airways, Air New Zealand, Garuda Indonesia, Philippine Airlines, US-Bangla, Biman Bangladesh |
  580. | **Americas** | Southwest, JetBlue, Frontier, Spirit, Allegiant, Avelo, Breeze, Sun Country, Flair, Porter, WestJet, Volaris, VivaAerobus, GOL, Azul, LATAM, JetSmart, Flybondi, Arajet, Wingo, Sky Airline, Copa, Avianca |
  581. | **Oceania** | Rex, Bonza, Link Airways, Air Vanuatu, Fiji Airways |
  582. </details>
  583. ---
  584. ## Star History
  585. <a href="https://www.star-history.com/?repos=LetsFG%2FLetsFG&type=date&legend=top-left">
  586. <picture>
  587. <source media="(prefers-color-scheme: dark)" srcset="https://letsfg.co/api/stars/history?theme=dark" />
  588. <source media="(prefers-color-scheme: light)" srcset="https://letsfg.co/api/stars/history?theme=light" />
  589. <img alt="Star History Chart" src="https://letsfg.co/api/stars/history?theme=light" />
  590. </picture>
  591. </a>
  592. ---
  593. <div align="center">
  594. **[letsfg.co](https://letsfg.co)** · **[API Docs](https://letsfg.co/developers/api/docs)** · **[Connector Health](https://letsfg.co/developers/api/v1/analytics/connectors/health)** · **[PyPI](https://pypi.org/project/letsfg/)** · **[npm](https://www.npmjs.com/package/letsfg-mcp)** · **[Smithery](https://smithery.ai/servers/letsfg)** · **[Instagram](https://www.instagram.com/letsfg_)** · **[TikTok](https://www.tiktok.com/@letsfg_)** · **[X](https://x.com/LetsFG_)**
  595. *Open source · MIT License · Made with ❤️ by travelers, for travelers*
  596. Want updates? Click **Watch** above, or follow [LetsFG on Instagram](https://www.instagram.com/letsfg_), [@letsfg_ on TikTok](https://www.tiktok.com/@letsfg_), or [@LetsFG_ on X](https://x.com/LetsFG_).
  597. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.