FlockTravel

A Slack bot that helps teams plan group travel with budget intelligence. Search flights, hotels, activities, and airport transfers from Slack — powered by real-time Amadeus data via StableTravel's x402 micropayment API.

What it does

A coordinator types a command in Slack:

/flocktravel search AUS LAX 2025-10-13

Or uses natural language:

/flocktravel search flights from Austin to LA next Monday round trip returning Friday

FlockTravel searches hundreds of flight and hotel options in real-time, ranks them by price, and posts formatted results directly in Slack with links to book on Google Flights and Google Hotels.

Core features (v0.1)

Flight search — Query 400+ airlines via Amadeus GDS through StableTravel
Hotel search — Automatically included with round-trip searches, showing top 3 hotels at the destination
Combined results — Round-trip searches show flights AND hotels in one Slack message
Structured + natural language input — Accepts IATA codes or plain English (parsed by Claude API)
Budget-friendly results — Shows top 5 cheapest flights and top 3 cheapest hotels
Google deep links — One-click to open pre-filled searches on Google Flights and Google Hotels
Round-trip support — Search one-way (flights only) or round-trip (flights + hotels)
Travel class filtering — Economy, Premium Economy, Business, or First

Planned features

Multi-traveler group planning — Search flights for 12+ people from different cities, optimize for a shared budget
Budget optimizer — Automatically find the cheapest combination across a group, suggest date shifts or nearby airports
Booking tracker — Track who's booked via self-report, confirmation email parsing, or Ramp transaction matching
Activity search — Extend search to activities and airport transfers
Slack DMs — Send each traveler their specific flight assignment with booking details
Stripe billing — Monthly plans for teams

Architecture

┌──────────────────────────────────────────────────┐
│                 SLACK                              │
│  /flocktravel austin to vegas next Tue to Fri     │
└────────────────────┬─────────────────────────────┘
                     │ WebSocket (Socket Mode)
                     ▼
┌──────────────────────────────────────────────────┐
│           FLOCKTRAVEL SERVER (Node.js / Bolt)     │
│                                                   │
│  Command parser (structured + Claude NL)          │
│  Budget optimizer (coming soon)                   │
│  Booking tracker (coming soon)                    │
│                                                   │
│  StableTravel API client                          │
│  └── x402 micropayments (USDC on Base)            │
│  └── CDP Server Wallet for signing                │
└────────────────────┬─────────────────────────────┘
                     │ x402: $0.05 per search
                     ▼
┌──────────────────────────────────────────────────┐
│  StableTravel API → Amadeus GDS (400+ airlines)   │
│  No API keys — payment IS authentication          │
└──────────────────────────────────────────────────┘

Tech stack

Component	Technology
Runtime	Node.js 20+ (ESM)
Slack framework	@slack/bolt (Socket Mode)
Travel data	StableTravel API (Amadeus GDS)
Payments	x402 protocol — USDC micropayments on Base chain
Wallet	Coinbase CDP Server Wallet (@coinbase/cdp-sdk)
NL parsing	Anthropic Claude API (claude-sonnet-4-20250514)

Setup

Prerequisites

Node.js 20+
A Slack workspace where you can install apps
A Coinbase Developer Platform account with a Server Wallet (~$5-10 USDC on Base for development)
An Anthropic API key

1. Clone and install

git clone https://github.com/jerryhsiang/FlockTravel.git
cd FlockTravel
npm install

2. Create a Slack app

Go to api.slack.com/apps → Create New App → From scratch
Name it "FlockTravel" and pick your workspace
OAuth & Permissions → Add Bot Token Scopes: chat:write, commands
Slash Commands → Create: /flocktravel with description "Plan group travel"
Socket Mode → Enable it, generate an App-Level Token with scope connections:write
Install the app to your workspace

3. Set up Coinbase CDP Server Wallet

Go to portal.cdp.coinbase.com
Click API Keys → Create a Secret API Key → save the Key ID and Secret
Click Wallets → Accounts → Generate a Wallet Secret → download and save it
The CDP SDK will automatically create a wallet account on first run — fund the logged address with USDC on Base (~$5-10)

4. Configure environment

cp .env.example .env

Fill in your .env:

# Slack
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...
SLACK_SIGNING_SECRET=...

# Coinbase CDP (Server Wallet for x402 payments)
CDP_API_KEY_ID=...
CDP_API_KEY_SECRET=...
CDP_WALLET_SECRET=...

# StableTravel
STABLETRAVEL_BASE_URL=https://stabletravel.dev/api

# Anthropic
ANTHROPIC_API_KEY=sk-ant-...

5. Run

npm run dev

The bot connects via Socket Mode — no public URL needed. On first run it will log the wallet address — fund that address with USDC on Base to enable flight searches.

Usage

Structured search

/flocktravel search AUS LAX 2025-10-13
/flocktravel search AUS LAX 2025-10-13 2025-10-17
/flocktravel search AUS LAX 2025-10-13 2025-10-17 BUSINESS

Format: /flocktravel search ORIGIN DEST DEPARTURE [RETURN] [CLASS]

Natural language search

The search prefix is optional — just type naturally:

/flocktravel austin to vegas next Tue to Fri
/flocktravel flights from Austin to Los Angeles on October 13
/flocktravel round trip NYC to San Francisco next Monday returning Friday
/flocktravel business class Boston to Miami Dec 5

When structured parsing fails, the input is sent to Claude for extraction.

Travel classes

ECONOMY (default), PREMIUM_ECONOMY, BUSINESS, FIRST

API costs

FlockTravel uses StableTravel's pay-per-request API. Each API call costs a small amount in USDC:

Search type	Cost per call
Flights	$0.05
Hotels	$0.03
Activities	$0.05
Transfers	$0.003
Flight status	$0.005
Reference data	$0.005

No API keys, no subscriptions — payment is authentication via the x402 protocol.

Project structure

flocktravel/
├── src/
│   ├── app.js                  — Bolt app init, socket mode, command routing
│   ├── commands/
│   │   └── search.js           — /flocktravel search handler
│   ├── services/
│   │   ├── stableTravel.js     — StableTravel API client with CDP wallet + x402
│   │   ├── flightSearch.js     — Amadeus flight response normalizer
│   │   ├── hotelSearch.js      — Hotel list caching, 2-step search, normalizer
│   │   ├── slackMessages.js    — Slack Block Kit message builders (flights + hotels)
│   │   ├── googleFlights.js    — Google Flights + Hotels URL builders
│   │   └── llm.js              — Claude API wrapper for NL parsing
│   └── utils/
│       ├── airports.js         — IATA code validation and lookup
│       ├── dates.js            — Date parsing, formatting, duration helpers
│       └── currency.js         — USD currency formatting
├── test/
│   └── fixtures/
│       └── amadeus-flight-response.json
├── .env.example
├── package.json
└── CLAUDE.md

How it works

User types /flocktravel austin to vegas next Tue to Fri in Slack
Bot tries structured parsing (ORIGIN DEST DATE); if that fails, sends to Claude for NL extraction
Validates parameters (valid airports, future dates, etc.)
For round-trips: searches flights AND hotels in parallel via Promise.allSettled()
Calls StableTravel endpoints — payment handled automatically via x402 (USDC on Base, signed by CDP Server Wallet)
Normalizes the Amadeus GDS responses into clean flight and hotel objects
Sorts by price, takes top 5 flights + top 3 hotels
Posts a combined Block Kit message to Slack with flight cards, hotel cards, and Google deep links
Hotel search failures are non-fatal — flights still show if hotels fail

x402 payment flow

GET stabletravel.dev/api/flights/search?...
                    │
                    ▼
Server: "402 Payment Required"
Pay me $0.05 USDC on Base to this address
                    │
                    ▼
Our wallet (0x017C...) signs a USDC transfer
$25.00 balance → authorize $0.05 to server
                    │
                    ▼
Resend request + signed payment header
x-payment: <signed USDC authorization>
                    │
                    ▼
Server verifies signature, settles on Base
$0.05 USDC moves on-chain in ~1 second
                    │
                    ▼
200 OK + flight data

No API keys. No signup. No dashboard. Payment IS authentication.

Example Slack output

AUS (Austin-Bergstrom) ✈ LAS (Las Vegas)
Round-trip • Tue, Mar 24 - Fri, Mar 27 • 5 results
──────────────────────────────────────────────────
ALASKA AIRLINES AS 3293  —  $352
✈ 6:10 AM → 9:50 AM • 5h 40m • 1 stop (SAN)
↩ 6:00 AM → 4:44 PM • 8h 44m • 1 stop (SEA)
──────────────────────────────────────────────────
[✈️ Book on Google Flights]
──────────────────────────────────────────────────

🏨 Hotels in LAS (Las Vegas)
Tue, Mar 24 - Fri, Mar 27 • 3 nights • 3 results
──────────────────────────────────────────────────
Fairfield by Marriott Inn and Suites
1 King, Mini fridge, Microwave
$148 /night • $445 total
[✈️ Google Travel]
──────────────────────────────────────────────────

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
src		src
test/fixtures		test/fixtures
.env.example		.env.example
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

FlockTravel

What it does

Core features (v0.1)

Planned features

Architecture

Tech stack

Setup

Prerequisites

1. Clone and install

2. Create a Slack app

3. Set up Coinbase CDP Server Wallet

4. Configure environment

5. Run

Usage

Structured search

Natural language search

Travel classes

API costs

Project structure

How it works

x402 payment flow

Example Slack output

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

FlockTravel

What it does

Core features (v0.1)

Planned features

Architecture

Tech stack

Setup

Prerequisites

1. Clone and install

2. Create a Slack app

3. Set up Coinbase CDP Server Wallet

4. Configure environment

5. Run

Usage

Structured search

Natural language search

Travel classes

API costs

Project structure

How it works

x402 payment flow

Example Slack output

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages