# Sendero Developer Docs

> Developer documentation for Sendero MCP tools, x402 nanopayments, Arc settlement, and agent integration paths.

Canonical: https://docs.sendero.travel/llms.txt

## Product

Sendero is an agent-native travel platform. It gives every trip a persistent AI agent that can search, book, invoice, and settle travel flows over WhatsApp, Slack, email, web, and MCP.

- Core network - Circle Arc testnet with USDC-denominated settlement and Circle Gateway liquidity.
- Inventory - Duffel flight booking and travel inventory integrations.
- Buyer model - Clerk organizations map to tenant-scoped wallets, invoices, trips, spend caps, and branding.

## Read In Order

- [Welcome](https://docs.sendero.travel/docs) - What Sendero is and what agents can build.
- [Quickstart](https://docs.sendero.travel/docs/quickstart) - Get an API key, fund a wallet, and call the first tool.
- [Agent-to-agent booking](https://docs.sendero.travel/docs/agent-to-agent-booking) - How another AI agent delegates search, escrow, booking, settlement, and invoices to Sendero.
- [Tool catalog](https://docs.sendero.travel/docs/tools/overview) - Every tool, per-call USDC price, and tool envelope.
- [x402 nanopayments](https://docs.sendero.travel/docs/x402-nanopayments) - How payment-required responses and EIP-3009 signatures become paid tool calls.
- [MCP integration](https://docs.sendero.travel/docs/mcp-integration) - Connect Sendero to Claude Desktop, Cursor, Zed, or custom MCP hosts.

## Canonical Agent Endpoints

- [OpenAPI 3.1 spec](https://www.sendero.travel/api/openapi.json) - Machine-readable description of every tool — generated from the canonical registry in @sendero/tools, so drift between code and docs is impossible. Feed this to Scalar / Redoc / Postman / your OpenAPI client.
- [Scalar API viewer](https://docs.sendero.travel/api-viewer) - Interactive HTML viewer over the OpenAPI spec. Try-it-out against sandbox keys.
- [Edge MCP](https://edge.sendero.travel/mcp) - Primary non-UI MCP endpoint for agent hosts.
- [App MCP](https://www.sendero.travel/api/mcp) - Next.js app-hosted MCP endpoint for local and buyer-console flows.
- [Paid HTTP tools](https://edge.sendero.travel/tools) - x402-gated direct HTTP tool catalog for hosts that do not speak MCP.
- [Self-serve API key](https://www.sendero.travel/dashboard/settings/api-keys) - Clerk-native API-key issuance. One click, no form, no sales call. Sandbox keys are auto-issued on tenant creation and do not move real USDC.
- [Per-page LLM markdown](https://docs.sendero.travel/docs/api-reference.md) - Append `.md` to any docs URL for a plaintext-markdown version — LLM-friendly, no HTML chrome. Mirrors Sherpa's "Trips LLM Friendly" pattern across every page.

## Managed Tool Catalog

Stable abbreviated index. For exact JSON schemas + per-tool prices, call `tools/list` on the live MCP endpoint or fetch `/api/openapi.json` from the app origin.

- check_treasury - Read treasury balance and policy limits.
- check_policy - Evaluate a proposed trip or payment against tenant travel policy.
- rate_agent - Read ERC-8004-style reputation and agent identity signals.
- log_agent_action - Emit an on-chain breadcrumb for an agent action against a claimed trip.
- faucet_drip - Request test assets for local or testnet demos.
- quote_fx - Quote indicative FX for travel spend and settlement reporting.
- gateway_balance - Read Circle Gateway unified USDC liquidity across supported chains.
- guest_claim_link - Convert a guest claim link into claim calldata for a traveler wallet.
- search_flights - Search real Duffel flight inventory by route, date, cabin, and passenger count.
- search_hotels - Search lodging inventory for the trip context.
- geocode_trip_stop - Normalize an itinerary stop into a canonical address and coordinates.
- trip_weather_brief - Read current weather conditions for a destination or trip stop.
- air_quality_brief - Read AQI and health recommendations for a destination or route.
- validate_travel_address - Validate and geocode travel-critical addresses such as hotels and pickups.
- timezone_brief - Explain time zone, offsets, and local-time context for a trip stop.
- elevation_risk_brief - Assess elevation and altitude sensitivity for a location.
- travel_safety_aid - Produce a single travel safety brief that combines weather, air quality, address confidence, timezone, and elevation.
- recommend_restaurants - Recommend in-trip restaurants from traveler context and location.
- export_route_map - Export routes and itineraries into Google Maps and Apple Maps links with a shareable preview card.
- restaurant_route_card - Shortlist restaurants and export a route from the traveler to the top pick. One canonical concierge card for web, WhatsApp, and Slack.
- airport_transfer_coordinator - Plan an airport-to-destination ground leg with meeting point, primary transport, backup options, and route links.
- airport_arrival_playbook - Produce a one-screen arrival briefing: deplane to check-in steps, primary + backup transport, local timezone, and route.
- trip_checkin_reminder - Build the canonical check-in nudge: check-in window, airport transit note, leave-by time, and next action. Backs the sendero.check_in_reminder workflow.
- trip_delay_replanner - Rebuild a disrupted itinerary: replacement flights, overnight hotel fallback, airport-to-hotel route, and a traveler-ready share card.
- ensure_flight_customer - Idempotently sync the traveler with Duffel identity (CustomerUser + CustomerUserGroup) and return the icu_… id. Unlocks Travel Support Assistant for future orders.
- list_flight_ancillaries - Return ancillary options on a Duffel offer — bags, cancel-for-any-reason, and seat map — ready to feed back into book_flight as services[].
- find_airports_nearby - Find Duffel-bookable airports within a radius of a lat/lng or matching a query. Useful when the traveler names a city that has no direct airport.
- display_offer_conditions - Canonical render of change/refund conditions for a Duffel offer: free / penalty / allowed-unknown-fee / not allowed / unknown, plus slice-level + private_fares + airline-credit applicability.
- quote_stay - Turn a Duffel Stays rate into a confirmed quote. Exposes cancellation timeline, payment type (pay_now/deposit/guarantee), and supported loyalty programme.
- book_stay - Book a Duffel Stays quote. Supports loyalty_programme_account_number + Customer User linkage to unlock Travel Support Assistant for the guest.
- cancel_order_quote - Create an unconfirmed Duffel order cancellation quote. Returns refund destination (original form of payment / airline_credits / voucher) + any credits to be issued.
- confirm_cancel_order - Confirm a previously created Duffel cancellation quote. Must run within the quote expiry. Returns final credit_code on each airline credit issued.
- list_airline_credits - List a traveler's Duffel airline credits (unused tickets, MCOs, vouchers) with availability state and totals by currency. Reads a Prisma cache (hydrated by webhooks) before hitting Duffel.
- manage_stays_negotiated_rate - CRUD for Duffel Stays negotiated rates (corporate RACs). action: create | update | delete.
- scan_document - Extract structured fields from a travel or finance document (invoice, receipt, boarding pass, or ID) via the @sendero/ocr multimodal pipeline. Accepts a public URL or inline base64; returns a typed object plus provider, model, and latency.
- send_tokens - Transfer USDC on Arc.
- gateway_transfer - Move USDC across Gateway chains with server-side treasury controls.
- prefund_trip - Create a prepaid guest escrow without storing private link fragments or claim codes.
- reserve_booking - Reserve a proposed booking against a prefunded trip budget.
- commit_booking - Commit the actual vendor amount and release unused escrow reserve.
- confirm_flight - Confirm a Duffel hold and attach booking metadata for settlement.
- [confirm_booking](https://docs.sendero.travel/docs/pricing/markup) - Snapshot tenant pricing policy, compute three-leg breakdown (cost + agency markup + Sendero take), persist onto the Booking, and encode the on-chain commitBookingV2 userOp. Sendero take is metered alongside the per-call price as one MeterEvent. (scopes: settlement; +optional: tenant:pricing:override; $0.0030)
- [get_tenant_pricing_policy](https://docs.sendero.travel/docs/pricing/markup#activation) - Read the active markup policy for the calling tenant. Returns status (active / inactive / partial / sandbox_seed / not_initialized), missing kinds, floor, ceiling, and the optional historical-median recommendation. ($0.0005)
- [activate_tenant_pricing_policy](https://docs.sendero.travel/docs/pricing/markup#activation) - Admin-only. Activate a new TenantPricingPolicy version (production keys only — sandboxes blocked). Runs treasury preflight before flipping `activated=true`. (scopes: settlement; $1.0000)
- settle_booking - Finalize the booking ledger and invoice-safe trip settlement state.
- cancel_booking - Cancel an unissued or refundable booking and sweep unspent escrow.
- generate_booking_invoice - Render invoice data and PDF output for a tenant-scoped booking.
- swap_tokens - Swap tokens on Arc.
- bridge_to_arc - Bridge USDC into Arc with CCTP.
- book_flight - Hold and pay a Duffel order from prefunded balance.
- swap_and_bridge - Bridge into Arc and swap in one composed action.
- settle_split - Atomically fan out commission across supplier, agency, rail, and validator legs.

## Managed Workflow Catalog

Live workflow registry: `/api/workflows/list`.

- sendero.book_flight - Escrow-backed flight booking workflow: search, policy, reserve, hold, ticketing pause, settle, and invoice.
- sendero.travel_safety_brief - Parallel travel-safety workflow: geocode, weather, air quality, timezone, elevation, and optional address validation.
- sendero.guest_prefund - Create a prepaid traveler budget, send a claim link, wait for claim, then book against escrow.
- sendero.agency_cohort - Fund a cohort of prepaid traveler links for agencies, events, bootcamps, or team travel.
- sendero.group_trip - Coordinate multi-traveler search, approvals, holds, and settlement for a shared itinerary.
- sendero.refund_booking - Cancel or refund a booked trip while preserving policy, escrow, ledger, and invoice state.
- sendero.check_in_reminder - Geocode origin airport, read timezone, and deliver the canonical trip check-in reminder (check-in window, transit note, leave-by) before awaiting traveler reply.
- sendero.trip_delay_replanner - Disruption recovery: build a rebook plan with replacement flights, optional overnight hotel, and airport route. On approval, hold the chosen flight via book_flight.
- sendero.book_with_ancillaries - Sell-up flow: search flights, list ancillaries, pause for selection, then hold with bags/seats/CFAR attached. Unlocks Travel Support Assistant via ensure_flight_customer.
- sendero.cancellation_recovery - Post-ticket recovery on order.cancelled / airline-initiated change webhooks. Rebook via trip_delay_replanner or cancel + refund.
- sendero.book_stay_with_loyalty - Stays: search → pause for pick → quote (with cancellation timeline) → pause for loyalty input → book with loyalty_programme_account_number.
- sendero.cancel_order_with_credits - Flight cancellation: quote → pause for approval (operator sees refund destination + credits) → confirm within expiry.

## Agent Guidance

- Best first read - Start with `/docs/quickstart`, then `/docs/agent-to-agent-booking`, then inspect `/docs/tools/overview` before calling paid tools.
- Payment model - Tool calls are metered in USDC. Failed tool execution should not capture payment.
- User consent - Ask the traveler before booking, paying, cancelling, or changing irreversible itinerary state.
- Data minimization - Persist itinerary metadata and receipts, not private invite fragments or plaintext secrets.

## SEO And AI Discovery

Crawler-safe discovery files and social preview assets for search engines, AI answer engines, and agent hosts.

- [Canonical llms.txt](https://docs.sendero.travel/llms.txt) - Primary machine-readable summary for this Sendero surface.
- [Well-known llms.txt](https://docs.sendero.travel/.well-known/llms.txt) - Standards-friendly alias for agent discovery.
- [Robots.txt](https://docs.sendero.travel/robots.txt) - Crawler policy with explicit LLM crawler allowances.
- [Sitemap.xml](https://docs.sendero.travel/sitemap.xml) - Canonical URLs, locale alternates, and public agent-discovery routes.
- [Open Graph image](https://docs.sendero.travel/brand/seo/open-graph-1200x630.png) - 1200x630 Sendero preview canvas for social sharing and link unfurls.
- [Google Discover image](https://docs.sendero.travel/brand/seo/google-discover-1600x900.png) - Large image asset eligible for rich search previews.
- [Schema logo](https://docs.sendero.travel/brand/seo/schema-logo-512.png) - 512x512 organization logo referenced by structured data.

## Related llms.txt Files

- [Product app llms.txt](https://www.sendero.travel/llms.txt) - Authenticated buyer console, MCP endpoint, webhooks, billing, and trip operations.
- [Website llms.txt](https://sendero.travel/llms.txt) - Public positioning, pricing, audiences, and launch-state guidance.
- [Help llms.txt](https://help.sendero.travel/llms.txt) - Human support articles and agent-safe troubleshooting paths.
- [Edge llms.txt](https://edge.sendero.travel/llms.txt) - Direct edge worker discovery for MCP and non-UI agent surfaces.

## Notes

- Sendero is public beta on Arc testnet. The `effectiveKeyType` resolved per request determines whether a `MeterEvent` settles on-chain (`paid`) or stays sandbox-routed (`sandbox`). Trust the meter status, not the key type, when deciding if real USDC moved.
- Do not log or persist guest private-link fragments, plaintext claim codes, Clerk secrets, Circle secrets, webhook secrets, or user travel documents.
- Paid or on-chain tools must be idempotent. Reuse caller-supplied idempotency keys when present. Sendero responses carry `x-sendero-trace-id`, `x-sendero-meter-id`, and `x-sendero-sig` headers — verify the signature on receipt to detect cached-response replay.
- Use tenant-scoped routes and Clerk organization context for buyer data. Never infer tenant access from an email domain alone. API keys pin the tenant server-side; ignore any caller-supplied tenantId when both are present.