The agent API
Search, book and track flights and hotels 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"
# (usually under 2 min) BEFORE choosing: the slower sellers often carry
# other airlines' nonstops and cheaper fares.
# 2 — optional: drill into one offer (every fare, bag prices, current price; 0.01 USDC)
curl -X POST https://travel.brij.fi/air/offer-details \
-d '{"offer_id":"off_…"}'
# fare_options lists every fare of that flight, each with its own bookable offer_id.
# 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 is booking_reference on that same GET, once the ticket is
# issued (usually minutes). Relay it to the traveller.
intent_id; re-booking a booked intent returns 409. Refused calls
are never charged — a 402 that is not settled costs nothing.Booking hotels
Hotel stays worldwide (Duffel Stays inventory), in USD, with the same escrow as flights. The stay is booked as soon as the escrow is funded; a booking the hotel refuses refunds in full.
# 1 — search (0.10): a city name, a city_id from GET /hotels/places?q= (free), or coordinates
curl -X POST https://travel.brij.fi/hotels/search \
-d '{"location":"Lisbon","check_in_date":"2026-12-10","check_out_date":"2026-12-12","rooms":1,"adults":2}'
# → hotels[]: hotel_id, total_from (all-in), due_at_hotel_from (paid at the hotel, on top)
# 2 — rooms and rates (0.01), then lock one rate (0.01)
curl -X POST https://travel.brij.fi/hotels/rates -d '{"hotel_id":"srr_…"}'
curl -X POST https://travel.brij.fi/hotels/quote -d '{"rate_id":"rat_…"}'
# → the stay as booked, cancellation terms, offer_id "hotel:quo_…"
# 3 — escrow (0.10), then guests + payment (the escrow amount)
curl -X POST https://travel.brij.fi/hotels/intents -d '{"offer_id":"hotel:quo_…","funding_wallet":"YOUR_WALLET"}'
curl -X POST https://travel.brij.fi/hotels/book \
-d '{"intent_id":"intent_…","guests":[{"given_name":"Jane","family_name":"Doe"}],"email":"[email protected]","phone_number":"+15551234567"}'
# 4 — status (0.01) and cancellation (0.10), both with X-Customer-Support-Code
# POST /hotels/orders {intent_id} · POST /hotels/cancel {intent_id} + X-Passenger-Family-Name
A cancellation refunds what the rate's cancellation timeline returns at that moment, plus the service fee minus 2 % of the stay (between 2 and 5 USDC kept), to the refund wallet set at intent creation.
Endpoints & prices
| Endpoint | Price | What it does |
|---|---|---|
POST /air/search | 0.10 USDC × 1–50 load multiplier | Live flight search |
POST /air/search-updates | free | Poll a progressive search for late quotes |
POST /air/offer-details | 0.01 USDC | Refresh one offer: every fare of the flight, bag prices |
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 + the PNR (booking_reference) once issued |
GET /air/orders/{id} | 0.01 USDC | Full airline order (needs X-Customer-Support-Code) |
POST /air/refund-requests | 0.10 USDC | File a refund request for human review |
POST /hotels/search | 0.10 USDC | Search hotels for dates and a party |
POST /hotels/rates · /hotels/quote | 0.01 · 0.01 | A hotel's rates; lock one rate at its all-in price |
POST /hotels/intents · /hotels/book · /hotels/orders · /hotels/cancel | 0.10 · escrow · 0.01 · 0.10 | Escrow, guests + payment, status, cancellation |
The flight booking fee is 10 USDC + 2% of the ticket, at most 15% of it; the hotel fee is
5 USDC + 2% of the stay, at most 30 USDC. All are
included in every price the API returns and in expected_escrow_amount. Every displayed price on the
web app is fee-inclusive; the wallet quote at signing is always the
authority.
The per-call prices in the table are separate from the
escrow: a booking's wallet spend is expected_escrow_amount plus
the few calls around it — e.g. 775.72 escrow + 0.10 intent + 2 × 0.10
searches = 776.02 USDC. Quote the traveller the escrow amount, and say the
call fees are separate, so the two figures never look like a price that moved.
The clocks
| Clock | Duration | Meaning |
|---|---|---|
| Offer freshness | ~20–30 min | Offers expire after search; on 404, re-search |
| 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 |
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-requestswithX-Customer-Support-CodeandX-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 full order read 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 flights and hotels, compare fee-inclusive prices, 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.
© 2026 Brij Digital · Terms · Privacy · [email protected]