The agent API

Search, book and track flights programmatically — x402-paid, wallet-identified, schema at /openapi.json.

API quickstart (agents)

Base URL: https://travel.brij.fi · full schema: /openapi.json · payments: x402 (USDC on Solana). Any x402-capable client works; without payment, endpoints reply 402 with the exact price and payment instructions.

# 1 — search (x402-paid; price is dynamic, quoted in the 402 challenge)
curl -X POST https://travel.brij.fi/air/search \
  -H "Content-Type: application/json" \
  -d '{"origin_iata":"MAD","destination_iata":"BCN","depart_date":"2026-12-15",
       "adults":1,"cabin_class":"economy","cheapest_per_itinerary":true,"limit":20}'
# → offers[], each with an offer_id. status "enriching" + search_id?
#   poll POST /air/search-updates {search_id} — free — until "complete".

# 2 — optional: drill into one offer (fare menu, baggage, current price)
curl -X POST https://travel.brij.fi/air/offer-details \
  -d '{"offer_id":"lowcost:…"}'
# lowcost fare rows carry their own bookable offer_id ("…##2") and fare_index.

# 3 — create the intent (0.10 USDC)
curl -X POST https://travel.brij.fi/air/intents \
  -d '{"offer_id":"…","funding_wallet":"YOUR_WALLET"}'
# → intent.id, escrow_address, expected_escrow_amount, customer_support_code
#   ⚠ SAVE customer_support_code NOW — it is never returned again.

# 4 — fund the escrow: transfer expected_escrow_amount USDC to escrow_address.

# 5 — book (x402 pays the escrow amount if not already funded)
curl -X POST https://travel.brij.fi/air/book \
  -d '{"intent_id":"intent_…","passengers":[{"given_name":"…","family_name":"…",
       "born_on":"1990-01-01","title":"mr","gender":"m",
       "email":"…","phone_number":"+34…"}]}'

# 6 — track: GET /air/intents/{id} (free) until status "booked" / "refunded".
#     The PNR: GET /air/orders/{order_id} with X-Customer-Support-Code
#     (fastbooking), or the ticket email (lowcost).

Idempotency is built in: re-creating an intent for the same (wallet, offer) returns 409 with the existing intent_id; re-booking a booked intent returns 409. Refused calls are never charged — a 402 that is not settled costs nothing.

Endpoints & prices

Endpoint	Price	What it does
`POST /air/search`	0.10 USDC × 1–50 load multiplier	Live two-tier flight search
`POST /air/search-updates`	free	Poll a progressive search for late quotes
`POST /air/offer-details`	0.01 (fastbooking) / 0.10 (lowcost)	Refresh one offer; lowcost fare menu with baggage & conditions
`POST /air/intents`	0.10 USDC	Create the booking intent + on-chain escrow
`POST /air/book`	escrow amount	Register passengers, trigger the booking
`GET /air/intents/{id}`	free	Booking status (reduced projection)
`GET /air/orders/{id}`	0.01 USDC	Airline order + PNR (needs `X-Customer-Support-Code`)
`POST /air/refund-requests`	0.10 USDC	File a refund request for human review

The booking fee is 10% of the ticket (minimum 3 USDC), included in expected_escrow_amount. Every displayed price on the web app is fee-inclusive; the wallet quote at signing is always the authority.

The clocks

Clock	Duration	Meaning
Offer freshness	~20–30 min	Offers expire after search; on 404, re-search
Lowcost fare menu	~30 min	A `##n` fare books only while its menu is fresh (409 `fare_menu_expired`)
Intent bookability	~20 min	`expires_at`: prices move, book promptly or re-create at the current price
On-chain escrow lock	sized per tier	Outlives the whole settlement window, so a refund can never race a ticket
Lowcost capture hold	24 h	No ticket email within the hold → automatic refund

Refunds & support

Automatic: booking failure, supplier price change, cancellation, no-ticket timeout — the escrow refunds to the frozen refund wallet and the customer is emailed the refund transaction.
Requested: POST /air/refund-requests with X-Customer-Support-Code and X-Passenger-Family-Name (lead passenger). This files the request for human review — the refund target is the frozen wallet either way, so even an approved fraudulent request cannot redirect funds.
The support code is returned at intent creation and at /air/book — persist it then; it cannot be re-read. It gates the PNR and refund requests. Humans: it is also in your emails.
Email: [email protected]

The web app (humans)

app.brij.fi is the same marketplace with a wallet UI: search, compare fee-inclusive fares (lowcost fare menus load live while you fill the passenger form), pay with your Solana wallet, and receive your ticket by email — PNR, itinerary, and before-you-fly instructions. Saved travellers and memberships (fee waivers by invite code) are optional conveniences; your wallet remains the identity.