Getting Started¶

🎬 Watch the demo — see LetsFG in action vs default agent search (OpenClaw, Perplexity Computer).

One-Click Install (No API Key Needed)¶

pip install letsfg

That's it. Search flights immediately:

letsfg search LHR BCN 2026-04-15

This runs 180+ airline connectors locally on your machine — Ryanair, Wizz Air, EasyJet, Southwest, AirAsia, Norwegian, Qatar Airways, LATAM, Finnair, and more. Completely free, unlimited, zero configuration.

from letsfg.local import search_local

# Free, runs all relevant connectors on your machine
result = await search_local("GDN", "BCN", "2026-06-15")
for offer in result.offers[:5]:
    print(f"{offer.airlines[0]}: {offer.currency} {offer.price}")

API Key for Unlock & Book¶

Search is completely free and runs locally — no API key needed. An API key is required for unlocking offers and booking flights.

1. Register (one command, free, instant)¶

# CLI
letsfg register --name my-agent --email you@example.com

# cURL
curl -X POST https://api.letsfg.co/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{"agent_name": "my-agent", "email": "you@example.com"}'

# Response:
# { "agent_id": "ag_xxx", "api_key": "trav_xxxxx...", "message": "..." }

2. Use the API Key¶

# Set as environment variable (recommended)
export LETSFG_API_KEY=trav_...

# CLI reads it automatically
letsfg unlock off_xxx

# Or pass explicitly
letsfg unlock off_xxx --api-key trav_...

3. Python SDK¶

from letsfg import LetsFG

# Option A: Pass directly
bt = LetsFG(api_key="trav_...")

# Option B: Read from environment (LETSFG_API_KEY)
bt = LetsFG()

# Option C: Register inline
creds = LetsFG.register("my-agent", "agent@example.com")
bt = LetsFG(api_key=creds["api_key"])

4. Link GitHub (required before unlock)¶

Star the LetsFG repo and link your GitHub account for free unlimited access. This is a one-time step.

# 1. Star the repo: https://github.com/LetsFG/LetsFG
# 2. Link your GitHub username:
letsfg star --github your-username

# Python SDK
bt.link_github("your-username")

# cURL
curl -X POST https://api.letsfg.co/api/v1/agents/link-github \
  -H "X-API-Key: trav_..." \
  -H "Content-Type: application/json" \
  -d '{"github_username": "your-username"}'

After verification, all operations are free — no further setup needed.

5. Verify Authentication Works¶

# Check your agent profile — confirms key and payment status
profile = bt.me()
print(f"Agent: {profile.agent_name}")
print(f"Payment: {profile.payment_status}")
print(f"Searches: {profile.search_count}")
print(f"Bookings: {profile.booking_count}")

letsfg me
# Agent: my-agent
# Payment: active
# Searches: 42
# Bookings: 3

Authentication Failure Handling¶

from letsfg import LetsFG, AuthenticationError

try:
    bt = LetsFG(api_key="trav_invalid_key")
    flights = bt.search("LHR", "JFK", "2026-04-15")
except AuthenticationError:
    # HTTP 401 — key is missing, invalid, or expired
    print("Invalid API key. Register a new one:")
    creds = LetsFG.register("my-agent", "agent@example.com")
    bt = LetsFG(api_key=creds["api_key"])
    # Don't forget to set up payment after re-registering
    bt.setup_payment(token="tok_visa")

Search Flags¶

Flag	Short	Default	Description
`--return`	`-r`	(one-way)	Return date for round-trip (YYYY-MM-DD)
`--adults`	`-a`	`1`	Number of adult passengers (1–9)
`--children`		`0`	Number of children (2–11 years)
`--cabin`	`-c`	(any)	Cabin class (see below)
`--max-stops`	`-s`	`2`	Maximum stopovers per direction (0–4)
`--currency`		`EUR`	3-letter currency code
`--limit`	`-l`	`20`	Maximum number of results (1–100)
`--sort`		`price`	Sort by `price` or `duration`
`--json`	`-j`		Output raw JSON (for agents/scripts)
`--mode`	`-m`	(full)	`fast` = OTAs + key airlines only (~25 connectors, 20-40s)
`--max-browsers`	`-b`	(auto)	Max concurrent browsers for local search (1–32)

Multi-Passenger Examples¶

# Family trip: 2 adults + 2 children, economy
letsfg search LHR BCN 2026-07-15 --return 2026-07-22 --adults 2 --children 2 --cabin M

# Business trip: 3 adults, business class, direct flights only
letsfg search JFK LHR 2026-05-01 --adults 3 --cabin C --max-stops 0

# Solo round-trip, first class, sorted by duration
letsfg search LAX NRT 2026-08-10 --return 2026-08-24 --cabin F --sort duration

When you search with multiple passengers, the response includes passenger_ids (e.g., ["pas_0", "pas_1", "pas_2"]). You must provide passenger details for each ID when booking.

Cabin Class Codes¶

Code	Class	Typical Use Case
`M`	Economy	Standard seating, cheapest fares
`W`	Premium Economy	Extra legroom, better meals, priority boarding
`C`	Business	Lie-flat seats on long-haul, lounge access, flexible tickets
`F`	First	Top-tier service, suites on some airlines, maximum comfort

If omitted, the search returns all cabin classes. Specify a cabin code to filter results to that class only.

Performance Tuning¶

LetsFG auto-detects system RAM and scales browser concurrency. This prevents Chrome from overwhelming low-end machines while maximizing throughput on powerful ones.

Available RAM	Tier	Max Browsers
< 2 GB	Minimal	2
2–4 GB	Low	3
4–8 GB	Moderate	5
8–16 GB	Standard	8
16–32 GB	High	12
32+ GB	Maximum	16

Check Your System¶

letsfg system-info

Override Auto-Detection¶

# Environment variable (highest priority)
export LETSFG_MAX_BROWSERS=4

# CLI flag (per-search)
letsfg search LHR BCN 2026-04-15 --max-browsers 4

from letsfg import configure_max_browsers, get_system_profile

profile = get_system_profile()
print(f"Tier: {profile['tier']}, recommended: {profile['recommended_max_browsers']}")

# Set explicitly
configure_max_browsers(4)

Priority order: LETSFG_MAX_BROWSERS env var > explicit config > auto-detect from RAM.

Fast Mode¶

If a full search takes too long (6+ minutes with all 200+ connectors), use --mode fast to search only ~25 high-coverage OTAs and key direct airlines. This typically completes in 20-40 seconds:

letsfg search LHR BCN 2026-06-15 --mode fast

from letsfg.local import search_local
result = await search_local("LHR", "BCN", "2026-06-15", mode="fast")

Fast mode covers: Kiwi, Skyscanner, Kayak, Momondo, Cheapflights, eDreams, Trip.com, Booking.com, Traveloka, Cleartrip, Wego, Despegar, plus Ryanair, Wizz Air, Southwest, and Allegiant direct.