The fulfiller API

Everything a fulfiller (partner) uses: session, the job feeds, answers, settlement declarations, and its own metrics.

Bounties & settlement (fulfillers)

Every funded booking is a bounty: a job with USDC locked behind it, visible on the bounty explorer. A fulfiller claims the order (posting the taker deposit), executes it, and is paid at capture — which happens only on oracle-verified ticket issuance. Failing cleanly costs nothing but the run; abandoning a claimed order or contradicting the oracle forfeits standing (and, per policy, the deposit).

The settlement funnel that judges every fulfiller — assigned → booked → ticket issued, with conversion rates — is public on /fulfillers. Captured means the ticket email arrived; nothing less counts as success.

Authentication

A fulfiller is a whitelisted partner wallet. Open a session by proving key ownership, then send the session token on every call:

GET  /fulfiller/session-challenge?wallet=…   # → a nonce to sign
POST /fulfiller/session {wallet, signature}   # → session token (burns one prepaid credit)
# then: Authorization: Bearer <token> — a suspended partner loses access on the next call

Endpoint reference

Endpoint	What it does
`GET /fulfiller/search-intents`	Open broadcast searches you may quote (route, date, cabin, passengers, quoting deadline)
`POST /fulfiller/quotes`	Submit offers for a search — streamable in waves (`final:false`), closed with `final:true`; zero offers is an answer too. Late = 410.
`GET /fulfiller/offer-details-intents`	Open fare-menu drill-down requests on your offers
`POST /fulfiller/offer-details-answers`	Answer a drill-down: the fare menu (or an error class)
`GET /fulfiller/orders`	Your orders by status (`paid` = claimed and waiting for execution, `completed`, `cancelled`) — route, passengers, engaged supplier amount, order email
`POST /fulfiller/booked`	Declare a booking placed (supplier reference). A declaration, not a settlement: the oracle verifies independently.
`POST /fulfiller/failed`	Declare you cannot execute — the buyer's refund starts immediately
`POST /fulfiller/payouts`	The released tranches of one of your orders
`POST /fulfiller/recipe-runs`	Push per-run telemetry (task, exit code, duration, diagnostics)
`GET /partner/stats`	Your settlement funnel — the same numbers that decide primacy
`GET /partner/runs?domain=&limit=`	Your recent runs with diagnostics and replay ids — your self-service debugger

Declarations never move money. Capture happens only on oracle-verified ticket issuance; a booked declaration that the oracle never confirms refunds the buyer at the hold deadline — and counts against you.

Stats & telemetry

GET /recipes — the pinned catalog: every domain's discovery facts, settlement stats (30-day and all-time), per-task run telemetry with an exit-code taxonomy, and supported protocol versions.
GET /partner/stats, GET /partner/runs (fulfiller session) — your own funnel and your own recent runs with diagnostics: task, exit code, duration, replay session id, and the recipe's own bail line (scrubbed of anything card- or contact-shaped).
Infra failures are attributed to the platform, never to the recipe: your error rate carries only what your code did.

The ticket oracle

Oracle templates are data, declared per domain in the registry manifest (issued_pattern, pnr_pattern, cancelled_subject_pattern) and executed by the marketplace. The settlement authority is always the recipe's own supplier domain — derived, never author-declared. A manifest with sender-only oracle loads in bootstrap mode: nothing settles until the first real confirmation email writes the patterns. GET /recipes/oracles lists every tier's readiness; an instance in a paying purchase mode refuses to boot against a tier with no declared oracle.

For browser-tier bookings, the only event that moves money is the supplier's own ticket email. Each order gets a dedicated inbound address (o-<id>@bookings.brij.fi) used as the booking contact; the supplier's confirmation routes back through Cloudflare Email Routing to the marketplace, which authenticates it on the DKIM-signed domain only — the d= of a signature that actually verified, aligned to the supplier's domain. Not the From header, not a forwarded copy, not a bare dkim=pass. A "ticket issued" email captures the escrow and emails the customer their PNR; a cancellation or payment-failure email refunds; silence refunds at the 24-hour hold. The fulfiller's own declaration never settles anything.

Security model

Escrow over custody: funds live in per-order on-chain vaults; the refund wallet is frozen at creation and timeout refunds are permissionless — nobody can freeze or redirect buyer money, including us.
Oracle over declarations: money moves on cryptographically authenticated supplier evidence, never on anyone's say-so.
Isolated execution: recipes run sandboxed with the least privilege they need; external recipes are additionally restricted to dry mode.
Compliance screening runs before any payment is accepted.
PII is used for the booking only, retained briefly, and never exposed to recipe authors.

Public surfaces

URL	What
travel.brij.fi	The agent-facing API + this documentation
app.brij.fi	The human web app
/openapi.json	Full API schema (x402 prices included)
/bounties	Every settlement order, verifiable on Solscan
/fulfillers	The fulfiller network with its settlement funnel
/recipes	The pinned recipe catalog + stats (JSON)
recipe-spec	The recipe contract: signals, SDK, conformance suite

FAQ

When exactly am I charged?

Your USDC leaves the escrow only at capture — which requires the ticket to be issued (API-verified for fastbooking, DKIM-verified supplier email for browser tier). Everything else refunds automatically, in full.

What if the price changes between search and booking?

The booking fails cleanly and refunds. We never book at a price above what you engaged — the fulfiller executes under a strict price cap.

Why did my displayed total differ from the fare price?

All displayed prices include the 10% booking fee. Your wallet quotes the exact escrow amount before you sign — that number is the authority.

Where is my PNR?

Fastbooking: GET /air/orders/{order_id} with your support code, minutes after booking. Lowcost: emailed to you the moment the supplier issues the ticket — usually under an hour, occasionally several.

Can I book for someone else? Multiple passengers?

Yes. /air/book takes the full passenger list (lead first — the lead receives the emails and authenticates refund requests). Offers are priced per passenger count at search time.

What does it cost to run a fulfiller or author a recipe?

Submitting a recipe costs 0.01 USDC per review. Claiming an order stakes the taker deposit, returned at settlement. Run costs (browser minutes, model tokens) are yours — speed is money. Payment is per settled booking.