name: letsfg description: "LetsFG — Agent-native flight search and booking API. Hundreds of airlines plus the major booking sites (Google Flights, Skyscanner, Kiwi, Kayak, Momondo). Per-flight reliability history and instant booking. letsfg.co"

SKILL.md — LetsFG Capabilities

MPP (updated 2026-07-30): the MPP (Machine Payments Protocol) 402 challenge is live, as a card-free enrolment lane for agents holding a Tempo wallet. It costs $0.01 once, as verification only — MPP has no zero-amount intent, so a card-free rail has to settle something. Search and booking stay free. Earlier revisions of this page described an MPP charge at unlock time; that never shipped. See https://letsfg.co/for-agents.

⚠️ Agents: do not create a Developer API account

Do NOT call /developers/api/v1/agents/register or /developers/api/v1/agents/setup-payment, and do NOT run letsfg register or letsfg setup-payment. Those belong to a separate, paid, prepaid-balance product for high-volume commercial integrations and create a billing account you almost certainly do not want.

To search and book flights, run letsfg auth — a zero-amount card setup (nothing charged), then search and book. See https://letsfg.co/for-agents.

Machine-readable skill manifest for AI agents and documentation indexers.

Identity

• Name: LetsFG
• Type: API + SDK + MCP Server + CLI
• Purpose: Agent-native flight and hotel search and booking
• Compatible agents: OpenClaw, Perplexity Computer, Claude Desktop, Cursor, Windsurf, and any MCP-compatible client
• API Base URL: https://letsfg.co/developers/api/v1
• MCP Endpoint: https://letsfg.co/developers/api/mcp (Streamable HTTP)
• Packages: PyPI letsfg · npm letsfg · npm letsfg-mcp
• License: MIT

Access Modes

Skills

search_flights

Search hundreds of airlines AND the major booking sites (Google Flights, Skyscanner, Kiwi, Kayak, Momondo) in one call. Returns real-time prices plus per-flight reliability history.

• Cost: FREE (unlimited)
• 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
• Output: List of flight offers with price, airlines, times, segments, conditions, passenger_ids
• Note: On PFS (Bearer token), call book_flight directly — no unlock step. On the Developer API, offers must be unlocked before booking.

resolve_hotel_city

Resolve a place name to the supplier city id that hotel search needs.

• Cost: FREE (a card must still be on file)
• Endpoint: POST /api/v1/hotels/destinations
• Input: text (place name, e.g. "Warsaw")
• Output: Matches, best first. Use Id as city_id and Name as city_name.

search_hotels

Search real, bookable hotel inventory.

• Cost: FREE, but a payment method on file is REQUIRED — for search, not just booking. A hotel search opens a real session at the supplier, so it returns HTTP 402 without a card.
• Auth: Developer API key (X-API-Key) only. The PFS Bearer token used for flights is rejected.
• Endpoint: POST /api/v1/hotels/search
• Input: city_id, city_name, check_in, check_out, adults, children, child_ages, nationality, limit
• Output: hotels[] each with offers[] carrying price (what the guest pays), reservation_fee_now (the 10%), balance_to_supplier, balance_due_by, free_cancellation_until, combination_id_v2
• Note: Only free-cancellation, pay-later rates are sold, so the result set is smaller than a metasearch and every rate returned can actually be booked. Keep session_id and the chosen offer's combination_id_v2 — booking needs both.

search_transfers

Search ground transfers — private cars, taxis, shared shuttles, airport express.

• Cost: FREE
• Input: origin, destination, date, passengers
• Output: Transfer options with prices and vehicle types

search_activities

Search activities — tours, museum tickets, day trips via direct APIs and aggregators.

• Cost: FREE
• Input: location, date_from, date_to
• Output: Activity options with prices, descriptions, availability

resolve_location

Resolve city names to IATA airport/city codes.

• Cost: FREE
• Input: query (city name, e.g. "London")
• Output: List of matching IATA codes (e.g. LON, LHR, LGW, STN, LTN, LCY)

unlock_flight_offer

Confirm live price with airline and reveal the direct booking URL. Reserves the offer for 30 minutes.

• Cost: 1% of ticket price (min $3) — Developer API only. There is no unlock step on a PFS Bearer token: call /api/agent-book instead.
• Endpoint: POST /api/v1/bookings/unlock
• Input: offer_id from search results (only required parameter)
• Output: confirmed_price, confirmed_currency, booking_url, offer_expires_at
• Prerequisite: A payment method on file (setup_payment) for the Stripe path, or an MPP-capable client for the crypto path.
• HTTP 402: No card on file. With MPP support, response carries a WWW-Authenticate: Payment challenge — pay via Tempo USDC.e and retry. Otherwise add a card via setup_payment.
• HTTP 410: Offer expired — airline sold the seats, search again (OfferExpiredError)
• Note: confirmed_price may differ from search price (airline prices change in real-time). After unlock, you have 30 minutes to complete the booking. If the window expires, search again (free) and unlock again.
• Python: unlocked = bt.unlock(offer_id) → returns UnlockResult
• CLI: letsfg unlock off_xxx
• JS/TS: const unlocked = await bt.unlock(offerId)

book_flight

Book an offer.

• PFS (Bearer token): POST /api/agent-book. No unlock step — search, then book directly. One passenger per call. Returns either {"booked": true, "order_id": ...} or, when the booking genuinely could not complete, {"booked": false, "booking_url": ...} — nothing charged either way beyond the ticket price. Not a transient error; hand the user booking_url, don't retry. Requires search_id (from the search result) alongside offer_id.
  • CLI: letsfg book off_xxx --search-id srch_xxx --passenger '{...}' --email you@example.com
  • Python: bt.book(offer_id=..., passengers=[{...}], contact_email=..., search_id=...)
• Developer API: Requires unlock first. Creates a real airline reservation with PNR code, and charges ticket price via Stripe before booking.
  • Cost: Ticket price + Stripe processing fee (2.9% + 30¢). Zero markup — LetsFG does not add any margin.
  • Prerequisite: Payment method must be attached via setup_payment first.
  • Input: offer_id, passengers (id, given_name, family_name, born_on, gender, title, email, phone_number), contact_email
  • Output: booking_reference (airline PNR), status, flight_price, currency
  • Payment flow: Your Stripe card is charged the ticket price → LetsFG books via the airline → you get the PNR. If the airline booking fails, you are automatically refunded.
• CRITICAL (both paths): Use real passenger names (must match passport/ID) and real email (airline sends e-ticket there).

book_hotel

Start a hotel booking. Returns a job, NOT a booking.

• Cost: 10% of the price charged immediately to the card on file as a NON-REFUNDABLE reservation fee. The balance is paid directly to the supplier through the returned pay_link.
• Endpoint: POST /api/v1/hotels/book
• Input: session_id, hotel_code, combination_id_v2, expected_price, expected_balance, city_id, city_name, check_in, check_out, adults, guests[{title, first_name, last_name}], email, phone
• Output: booking_job_id, status "in_progress", poll URL
• Asynchronous: a real booking takes minutes — the rate is re-blocked at the supplier, the card charged, the room committed. Poll get_hotel_booking until status is succeeded or failed. This is what makes it impossible to charge a card and then lose the confirmation to a timeout.
• CRITICAL: send expected_price and expected_balance back exactly as search returned them, or the booking is refused as a price mismatch — a guest is never charged a price they did not agree to.
• CRITICAL: NOT idempotent. Calling this twice for the same rate books the room twice and charges two reservation fees. If a call times out, poll the job; do not re-book.
• Note: the fee is charged BEFORE the room is committed, so a declined card costs nothing — no reservation exists and nothing is charged.

get_hotel_booking

Collect the result of a booking started with book_hotel.

• Cost: FREE
• Endpoint: GET /api/v1/hotels/booking/{booking_job_id}
• Output: status, and on success confirmation, reservation_fee_charged, pay_link, balance_due, balance_due_by, terms (including the full cancellation ladder)
• Note: balance_due_by is the supplier's own auto-cancellation date, not advisory. Miss it and the room is released.

cancel_hotel_booking

Release a hotel reservation.

• Cost: Free until balance_due_by; after that the hotel's own ladder applies and can reach 100%. The 10% reservation fee is NOT refunded.
• Endpoint: POST /api/v1/hotels/cancel
• Input: confirmation
• Output: confirmation, charge
• Note: drives a browser at the supplier and takes over a minute. If it times out, do NOT assume it failed — re-check before retrying.

register

Register a new AI agent.

• Cost: FREE
• Input: agent_name, email
• Output: api_key (permanent credential)

setup_payment

Attach a payment card for booking. Required before booking flights.

• Cost: FREE (attaching the card is free; you are charged the ticket price when you book)
• Input: token (e.g. "tok_visa" for testing) or payment_method_id or card details
• Output: Payment status confirmation
• Note: Must be called once before your first booking. The card stays on file for future bookings.

get_agent_profile

Get current agent's profile, usage stats, and payment status.

• Cost: FREE
• Output: Agent details, search count, booking count, payment status

Authentication

PFS (recommended — almost every agent): a Bearer token from letsfg auth — a zero-amount card setup, nothing charged. Search and flight booking both work with it; hotels do not (see below).

Authorization: Bearer eyJ...

Get a token: POST /api/agent-access/request → present a card at the returned setup_url (or headlessly via a Stripe token) → POST /api/agent-access/verify → 90-day token. Full flow: https://letsfg.co/for-agents.

Developer API (business / high-volume): every endpoint except register requires an X-API-Key header.

X-API-Key: trav_...

Get your key by calling POST /api/v1/agents/register with agent_name and email. The key is permanent — save it once.

Before your first unlock, attach a payment method via POST /api/v1/agents/setup-payment (or use the MPP crypto path on the 402 challenge).

Complete Workflow

Flight Booking — PFS (2 API calls, free)

1. POST /api/search                    → Search flights (FREE), returns search_id
2. POST /api/agent-book                → Book directly — no unlock step, no LetsFG fee

Flight Booking — Developer API (5 API calls)

1. POST /api/v1/agents/register        → Get API key (once)
2. POST /api/v1/agents/setup-payment   → Attach payment card (once)
3. POST /api/v1/flights/search         → Search flights (FREE)
4. POST /api/v1/bookings/unlock        → Unlock offer (1% fee, min $3) → returns booking_url
5. POST /api/v1/bookings/book          → Book flight (ticket price charged via Stripe)

Hotel Booking (Developer API key required — the PFS Bearer token does not work here)

1. POST /api/v1/agents/setup-payment       → Card on file (required for SEARCH too)
2. POST /api/v1/hotels/destinations        → Place name → city_id
3. POST /api/v1/hotels/search              → Bookable rates (free, card still required)
4. POST /api/v1/hotels/book                → Returns booking_job_id — NOT a booking
5. GET  /api/v1/hotels/booking/{job_id}    → Poll ~20s until succeeded/failed
                                             → confirmation + pay_link + balance_due_by
6. POST /api/v1/hotels/cancel              → Optional; free until balance_due_by

10% is charged to the card at step 4 as a non-refundable reservation fee; the balance is paid directly to the supplier through pay_link by balance_due_by, which is the supplier's own auto-cancellation date. Never repeat step 4 for the same rate — that books the room twice.

CLI Usage

pip install letsfg

letsfg auth   # zero-amount card setup, nothing charged — 90-day Bearer token

# Search flights — prints search_id, needed for book
letsfg search LHR JFK 2026-04-15
letsfg search LON BCN 2026-04-01 --return 2026-04-08 --cabin C --sort price
letsfg search GDN BER 2026-05-10 --adults 2 --children 1

# Resolve locations
letsfg locations "New York"

# Book — free, ticket price only, no LetsFG fee, no unlock step
letsfg book off_xxx --search-id srch_xxx \
  --passenger '{"given_name":"John","family_name":"Doe","born_on":"1990-01-15","gender":"m"}' \
  --email john.doe@example.com

# Machine-readable output
letsfg search GDN BER 2026-03-03 --json

Developer API instead? letsfg register + letsfg setup-payment once, then letsfg search ... --api-key trav_..., letsfg unlock off_xxx --api-key trav_..., letsfg book off_xxx --api-key trav_... --passenger '{"id":"pas_0",...}' --email ....

Python SDK Usage

from letsfg import LetsFG

bt = LetsFG()  # reads the Bearer token from `letsfg auth`

# Search
results = bt.search("LHR", "JFK", "2026-04-15")
for offer in results.offers:
    print(f"{offer.price} {offer.currency} — {', '.join(offer.airlines)}")

# Book — free, ticket price only, no LetsFG fee, no unlock step
result = bt.book(
    offer_id=results.offers[0].id,
    passengers=[{
        "given_name": "John",
        "family_name": "Doe",
        "born_on": "1990-01-15",
        "gender": "m",
        "phone_number": "+447123456789",
    }],
    contact_email="john@example.com",
    search_id=results.search_id,
)
if result["booked"]:
    print(f"Order: {result['order_id']}")
else:
    print(f"Booking link (nothing charged): {result['booking_url']}")

Developer API instead? LetsFG(api_key="trav_..."), then bt.unlock(offer_id) before bt.book(...) — returns a BookingResult with booking_reference (PNR).

MCP Server Setup

Remote (Streamable HTTP) — Developer API only:

{
  "mcpServers": {
    "letsfg": {
      "url": "https://letsfg.co/developers/api/mcp",
      "headers": {
        "X-API-Key": "trav_..."
      }
    }
  }
}

Local (stdio) — free PFS path:

npm install -g letsfg-mcp
LETSFG_BEARER_TOKEN=eyJ...  letsfg-mcp   # token from `letsfg auth`

The local server also accepts LETSFG_API_KEY instead, for the Developer API. book_flight dispatches automatically based on which one is set.

MCP Tools

Search Flags Reference

Cabin Class Codes Explained

Error Handling

Authentication Failure Recovery

from letsfg import LetsFG
from letsfg.connectors.auth import BearerTokenError

try:
    bt = LetsFG()  # reads the Bearer token from `letsfg auth`
    flights = bt.search("LHR", "JFK", "2026-04-15")
except BearerTokenError:
    print("Token expired or missing — run `letsfg auth` again")

Developer API:

from letsfg import LetsFG, AuthenticationError

try:
    bt = LetsFG(api_key="trav_...")
    flights = bt.search("LHR", "JFK", "2026-04-15")
except AuthenticationError:
    # API key invalid or expired — re-register
    creds = LetsFG.register("my-agent", "agent@example.com")
    bt = LetsFG(api_key=creds["api_key"])
    bt.setup_payment(token="tok_visa")  # re-attach payment on the new key

Rate Limit and Timeout Handling

import time
from letsfg import LetsFG, LetsFGError

def search_with_retry(bt, origin, dest, date, max_retries=3):
    for attempt in range(max_retries):
        try:
            return bt.search(origin, dest, date)
        except LetsFGError as e:
            if "429" in str(e) or "rate limit" in str(e).lower():
                time.sleep(2 ** attempt)  # exponential backoff
            elif "timeout" in str(e).lower() or "504" in str(e):
                time.sleep(1)
            else:
                raise
    raise LetsFGError("Max retries exceeded")

Rate Limits

Pricing Summary

Key Facts

• Hundreds of airlines via server-side engine
• Hotels and activities via direct APIs
• Zero price bias — no demand inflation, no cookie tracking
• Typically cheaper than booking through a single OTA, because it compares airlines and the major booking sites in one pass
• Real airline PNR codes and hotel confirmations
• E-tickets sent directly to passenger email
• Search is always free and unlimited
• PFS (Bearer token): book directly, no unlock step, no LetsFG fee on booking
• Developer API: unlock reveals the direct booking URL for 1% of the ticket (min $3), then book
• API designed for machines, not browsers

MPP (updated 2026-07-30): the MPP (Machine Payments Protocol) 402 challenge is live, as a card-free enrolment lane for agents holding a Tempo wallet. It costs $0.01 once, as verification only — MPP has no zero-amount intent, so a card-free rail has to settle something. Search and booking stay free. Earlier revisions of this page described an MPP charge at unlock time; that never shipped. See https://letsfg.co/for-agents.

⚠️ Agents: do not create a Developer API account

Do NOT call /developers/api/v1/agents/register or /developers/api/v1/agents/setup-payment, and do NOT run letsfg register or letsfg setup-payment. Those belong to a separate, paid, prepaid-balance product for high-volume commercial integrations and create a billing account you almost certainly do not want.

To search and book flights, run letsfg auth — a zero-amount card setup (nothing charged), then search and book. See https://letsfg.co/for-agents.

We're LetsFG — a community of travelers.

Finding a flight or hotel shouldn't mean checking 47 tabs. Or 3 hours of searching. Or having that feeling you could've got a better deal if you'd just waited a little longer.

So we built something about it. No markup. No tracking. No price that goes up because you looked twice.

Join the community. Help others find cheaper flights. Spread the word.⭐ Star the repo. Share with a friend ✈️

Flights and hotels. Both live.

Hundreds of airlines. Real prices. One function call.

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. Real airline tickets, booked through us or handed to you as a direct link.

The same flight costs $20–$50 less because you skip OTA inflation, cookie tracking, and surge pricing.

CLI or scripts: Run letsfg auth once — it puts a payment method on file through a zero-amount Stripe setup (nothing is charged) and returns a 90-day token. Then letsfg search and letsfg book hit our cloud engine. Developer API: a separate paid product for high-volume commercial use; most agents do not need it. → Get started

Supporters

🏨 Hotels — new, and live

Your agent can now book hotels, not just flights. Same API key, same card on file.

from letsfg import LetsFG
lfg = LetsFG()

city = lfg.hotel_destinations("Warsaw")[0]
stays = lfg.search_hotels(
    city_id=city["Id"], city_name=city["Name"],
    check_in="2026-11-10", check_out="2026-11-12", adults=2,
)

hotel = stays["hotels"][0]
offer = hotel["offers"][0]
print(hotel["name"], offer["price"], stays["currency"])
# Hotel Gromada Warszawa Centrum 669.86 PLN

booking = lfg.book_hotel_and_wait(
    session_id=stays["session_id"],
    hotel_code=hotel["hotel_code"],
    combination_id_v2=offer["combination_id_v2"],
    expected_price=offer["price"],
    expected_balance=offer["balance_to_supplier"],
    city_id=city["Id"], city_name=city["Name"],
    check_in="2026-11-10", check_out="2026-11-12",
    guests=[{"title": "Mr", "first_name": "Jan", "last_name": "Kowalski"}],
    email="guest@example.com", phone="512345678",
)
print(booking["confirmation"], booking["pay_link"])

How you pay

10% now, the rest to the hotel later. At booking we charge 10% of the price to your card as a reservation fee. The remaining balance is paid directly to the supplier through a pay_link we return — we never hold it.

balance_due_by is the supplier's own auto-cancellation date, not a date we invent. Miss it and the room is released.

The 10% is non-refundable. Cancelling before balance_due_by costs nothing else; after it, the hotel's own cancellation ladder applies and can reach 100%. That ladder ships in the booking's terms, so you can always see the cost before you cancel.

Things worth knowing before you build

• A card on file is required for every hotel call, including search. That is unusual and it is deliberate: a hotel search opens a real session at the supplier, and booking blocks a real rate. We would rather refuse up front than let you reach the point of commitment and discover you cannot pay. The same card that authorises flight booking authorises hotels — there is no separate hotel signup.
• Only free-cancellation, pay-later rates are sold. Those are the rates where the balance can safely be settled with the supplier after booking, which is what makes 10%-now/rest-later work at all. You will see fewer results than a metasearch shows you. Every one of them can actually be booked.
• Booking is asynchronous. book_hotel returns a booking_job_id, not a booking — the real thing takes minutes. Poll hotel_booking(job_id) until status is succeeded or failed, or call book_hotel_and_wait and let the SDK do it. This is not ceremony: it is what makes it impossible to charge a card and then lose the confirmation to a timeout.
• The fee is charged before the room is committed. A declined card therefore costs nothing to unwind — no reservation exists and nothing is charged.
• Do not retry a booking blindly. Calling book_hotel twice for the same rate books the room twice and charges two reservation fees.
• price is what the guest pays. There is no wholesale figure in the response to quote by mistake.

JavaScript

import { LetsFG } from 'letsfg';
const lfg = new LetsFG({ apiKey: process.env.LETSFG_API_KEY });

const [city] = await lfg.hotelDestinations('Warsaw');
const stays = await lfg.searchHotels({
  cityId: city.Id, cityName: city.Name,
  checkIn: '2026-11-10', checkOut: '2026-11-12', adults: 2,
});

const booking = await lfg.bookHotelAndWait({ /* ...offer + guest details... */ });
console.log(booking.confirmation, booking.pay_link);

MCP

Five new tools, in the order you call them: resolve_hotel_city → search_hotels → book_hotel → get_hotel_booking → cancel_hotel_booking.

Three ways to use LetsFG