x402-flight-search

x402-flight-search

Pay-per-query flight search over the Amadeus Self-Service API — offers, confirmed pricing, and fare-drop checks, priced per call for AI agents.

Pay in USDC on Base or Solana — your client picks the rail.

Why x402 for this

Flight data is metered, expensive, and normally gated behind a sales call: an API key, a contract, a monthly minimum. An agent that wants to check one route once shouldn't need any of that. x402 makes the price part of the HTTP conversation — the server quotes half a cent in the 402, the client signs a USDC transfer and retries, and the 200 body is the search result. No account, no key, no subscription that outlives the question.

It also fixes fare watching. A subscription-shaped watcher bills you for silence; here /check is a pay-per-poll snapshot that returns the current fare and the delta against your last one, so you pay per look and own the loop.

Quickstart

git clone https://github.com/nirholas/x402-flight-search
cd x402-flight-search && npm install
cp .env.example .env            # ships with working payTo addresses — edit to get paid yourself
npm run dev                     # service at http://localhost:4022

No API keys needed to run it — see Real backend below.

First 402, no wallet needed:

curl -s "http://localhost:4022/search?origin=JFK&destination=LAX&date=2026-09-15" \
  | jq '.accepts[] | {network, payTo, maxAmountRequired}'

{ "network": "base-sepolia", "payTo": "0x40252CFDF8B20Ed757D61ff157719F33Ec332402", "maxAmountRequired": "5000" }
{ "network": "solana",       "payTo": "WwwuGbqHrwF5RG89KhUbmRWEvjnRH9k5kVM5p7T3WwW", "maxAmountRequired": "5000" }

Two rails in one challenge — pay whichever you hold.

Full paid flow (funded Base Sepolia wallet — free USDC at faucet.circle.com):

export PRIVATE_KEY=0x…
npm run client

API

A full "find and confirm" is $0.008. Watching a fare is $0.002 per look, and nothing accrues between polls.

Full details: docs/api.md.

How x402 works

1. GET /search with no payment → 402 + an accepts[] array with one entry per rail (price, network, payTo, USDC mint/contract).
2. The client picks a rail and signs for it — an EIP-3009 USDC transfer authorization on Base, or an SPL USDC transfer on Solana.
3. Retry with X-PAYMENT: <base64 signed payload>.
4. The server verifies + settles through the facilitator and answers 200 with the flight offers. The settlement receipt — tx hash plus which rail settled it — rides in the X-PAYMENT-RESPONSE header.

GET /search?…                    402  accepts: [ base-sepolia USDC , solana USDC ]
GET /search?…  X-PAYMENT: …      200  { source, offers: [...] }   +  X-PAYMENT-RESPONSE

Dual-rail configuration

Both default to the x402 Suite's public receive addresses so the demo runs with zero setup — set your own to receive funds. A rail with a missing or malformed address is dropped from accepts with a warning; the other keeps working.

Real backend / API keys

Amadeus is a keyed API, so this service is env-gated:

Free sandbox keys, no card required, at developers.amadeus.com.

Being honest about fixtures: without keys, the offers are generated — stable and realistic-looking, deterministic for a given query, and not real fares. Every response and GET /health carry the source field so a caller is never guessing. Never quote a fixture price to a user as a real one. The point of the fallback is that the demo, the tests, and an agent's integration work all run without anyone needing a paid account.

Live /price has one real constraint worth knowing: Amadeus needs the original offer object to re-price, so live am-… offer ids are scoped to the server process that produced them. Fixture fx-… ids encode their own query and never expire.

For AI agents

• skill.md — agent-readable instructions for every endpoint, plus budgeting notes.
• /.well-known/x402 — machine-readable price sheet with both rails and full input/output schemas, indexable by x402scan.com, the x402 Bazaar, and agentic.market. List your deployment there so agents can find it.
• examples/mcp-tool.md — expose the service as MCP tools for Claude.
• examples/agent-client.ts — full search → price → fare-check flow with x402-fetch.
• docs/agents.md — discovery, both payment rails, and what each artifact contains.

Docs

Site: https://nirholas.github.io/x402-flight-search/ — tutorial · API reference · for agents

Part of the x402 Suite.

Support

Questions, bugs, or listing requests: nichxbt@gmail.com

License

Apache-2.0

Star History

Support the project

If x402-flight-search saves you time, star it on GitHub. Stars are how other developers and AI agents find the repositories worth trusting, and they cost you one click.

Know someone who would use it? Post on X · Share on Bluesky · Share on LinkedIn · Submit to Hacker News · Share on Reddit

Built for AI agents too

Coding agents and LLM tooling can read this repo directly: AGENTS.md, llms.txt, llms-full.txt. Point an agent at https://github.com/nirholas/x402-flight-search and it has the context it needs.

More from the same author

• All repositories by nirholas: the full catalog, grouped by topic
• three.ws: the platform for 3D AI agents with Solana wallets, a skill marketplace and x402 payments
• Questions or ideas: open an issue or start a discussion

Contributors