# bluerails402 Skill

bluerails402 is a registry and settlement layer for agentic payments spanning EU/DACH publishers, hotels, ecommerce stores, and SaaS companies. Merchants list once; AI agents discover them, and — for hotels — book and pay for stays end-to-end with x402 USDC micropayments.

## MCP Endpoint

`https://402.bluerails.com/mcp` (Streamable HTTP, MCP protocol 2025-06-18)

## Tools

### list_publishers (public — no auth)
Lists active EU publishers in the registry.
- `query` (string, optional): natural language search e.g. "german news", "french business"
- `content_type` (string, optional): filter by content type
- `protocol` (string, optional): "x402" | "mpp" | "l402" — filter payment-ready publishers
- `page` (integer, optional, default 1): pagination

### get_publisher (public — no auth)
Get a single publisher by slug or UUID.
- `id` (string, required): publisher slug (e.g. "bild") or UUID

### get_fx_quote (requires X-API-Key)
Get a live EUR/USDC exchange rate quote for settlement.
- `from_currency` (string, required): ISO 4217 fiat currency code (e.g. EUR, USD)
- `to_currency` (string, required): ISO 4217 fiat currency code (e.g. USD, GBP)
- `amount` (number, required): amount to convert
- Requires operator API key in X-API-Key header.

### fetch_content (requires X-API-Key)
Fetch content at a URL via the registry. Returns the article content or payment instructions if the publisher requires a micropayment.
- `url` (string, required): article URL to fetch
- Requires operator API key in X-API-Key header.

### list_hotels (public — no auth)
List and search DACH hotel properties in the registry.
- `query` (string, optional): full-text search on name/description/tags
- `city` (string, optional): berlin, munich, vienna, zurich, frankfurt, hamburg, waldbronn
- `country` (string, optional): de | at | ch
- `starRating` (string, optional): 3-star | 4-star | 5-star | boutique
- `page` (integer, optional, default 1): pagination

### get_hotel (public — no auth)
Get a single hotel by slug, including amenities and the live x402 booking tools.
- `id` (string, required): hotel slug

### list_ecommerce (public — no auth)
List and search DACH ecommerce stores in the registry.
- `query` (string, optional): full-text search
- `category` (string, optional): fashion, beauty, home, food, electronics, sports, kids, pets, health, jewelry, auto, general
- `country` (string, optional): de | at | ch
- `page` (integer, optional, default 1): pagination

### get_ecommerce_store (public — no auth)
Get a single ecommerce store by slug.
- `id` (string, required): store slug

### list_saas (public — no auth)
List and search EU SaaS companies in the registry.
- `query` (string, optional): full-text search
- `category` (string, optional): hrtech, fintech, devtools, marketing, sales, analytics, infrastructure, ecommerce-saas, health, legal, proptech, edtech, logistics
- `country` (string, optional): ISO-2 country code (e.g. de, at, ch, fr, nl)
- `stage` (string, optional): early | growth | established
- `page` (integer, optional, default 1): pagination

### get_saas_company (public — no auth)
Get a single SaaS company by slug.
- `id` (string, required): company slug

### hotel_check_availability (public — no auth)
Check room availability and pricing for a hotel over a date range. Returns rooms with EUR price, cancellation terms, and sold-out status.
- `listingSlug` (string, required): hotel slug
- `checkIn` (string, required): check-in date (YYYY-MM-DD)
- `checkOut` (string, required): check-out date (YYYY-MM-DD)
- `adults` (integer, required): number of adults (1–20)
- `childrenAges` (integer[], optional): ages of accompanying children (0–17)

### hotel_pay (public — no auth) — recommended for agents that cannot sign
Book AND pay for a hotel room in ONE call. Authorizes a pre-funded **custodial agent wallet** held by the server to pay the x402 USDC challenge on your behalf — you do NOT sign anything and hold no key. Use this if you cannot produce an EIP-3009 signature locally (e.g. a ChatGPT connector). **Confirm the room and the total price in EUR with the user before calling — this spends real funds.**
- `listingSlug` (string, required): hotel slug
- `roomId` (string, required): room id from hotel_check_availability
- `checkIn` (string, required): check-in date (YYYY-MM-DD)
- `checkOut` (string, required): check-out date (YYYY-MM-DD)
- `adults` (integer, required): number of adults (1–20)
- `childrenAges` (integer[], optional): ages of accompanying children (0–17)
- Guest identity is server-bound — do NOT pass PII. Returns bookingId + confirmation on success.

### hotel_book (public — no auth; x402 payment proof is the sole gate)
Book a hotel room by signing the payment yourself. An unpaid call returns an x402 v2 402 challenge with a signed USDC quote; retry with the EIP-3009 payment in _meta["x402/payment"] to settle on-chain and confirm. Returns bookingId + confirmation number. **Agents that cannot sign EIP-3009 locally (e.g. ChatGPT connectors) should call `hotel_pay` instead.**
- `listingSlug` (string, required): hotel slug
- `roomId` (string, required): room id from hotel_check_availability
- `checkIn` (string, required): check-in date (YYYY-MM-DD)
- `checkOut` (string, required): check-out date (YYYY-MM-DD)
- `adults` (integer, required): number of adults (1–20)
- `childrenAges` (integer[], optional): ages of accompanying children (0–17)
- Guest identity is server-bound — do NOT pass PII.

### hotel_capture (requires X-API-Key)
Capture one or more HELD hotel bookings into EUR via the configured swap port. Returns a remittance line (confirmation, gross, fee, net EUR).
- `bookingIds` (string[], required): one or more HELD booking ids
- Requires operator API key.

### hotel_cancel (requires X-API-Key)
Cancel a HELD hotel booking. Cancels the PMS reservation and refunds the held USDC on-chain to the original payer.
- `bookingId` (string, required): booking id
- `confirmationNumber` (string, required): confirmation number from hotel_book
- Requires operator API key.

## Recommended Flow

1. Call `list_publishers` with user's topic to find relevant publishers
2. Present results to user (name, shortDescription, websiteUrl, trustTier)
3. If user selects a publisher, call `get_publisher` with the slug for full detail
4. Display publisher info — do NOT surface trustTier numeric score if present
5. If user wants to access content, use `fetch_content` with the article URL (requires API key)

### Hotel booking flow

1. Call `list_hotels` (or `get_hotel`) to find a property
2. Call `hotel_check_availability` with the listing slug and dates to get rooms + EUR prices
3. **Confirm the exact room and the total price in EUR with the user** — this next step spends real funds
4. Call `hotel_pay` with the listing slug, room id and dates. It books and pays in **one call**: a pre-funded custodial agent wallet held by the server pays the x402 USDC challenge on your behalf (you do NOT sign anything). Keep the returned bookingId + confirmation number
5. Only if you can sign an EIP-3009 authorization yourself: use `hotel_book` instead (unpaid call → sign the 402 → retry paid). Most connectors cannot sign locally and should use `hotel_pay`
6. `hotel_capture` / `hotel_cancel` (operator-only) settle a HELD booking into EUR or cancel + refund the held USDC

## REST API (alternative to MCP)

- `GET /api/publishers?q=<query>&protocol=x402` — list publishers (public)
- `GET /api/publishers/<slug>` — get publisher detail (public)
- `GET /api/hotels?q=<query>` — list DACH hotels (public)
- `GET /api/hotels/<slug>` — get hotel detail (public)

## Critical Guardrails

- NEVER fabricate publisher data — always fetch from the API or MCP tool
- NEVER surface the raw trustTier numeric score — show tier label only (bronze/silver/gold/platinum)
- Do NOT initiate payment (`fetch_content` with paid article) without explicit user confirmation
- Do NOT call `get_fx_quote` or `fetch_content` without a valid operator API key
- If `list_publishers` returns zero results, suggest broadening the search query — do not invent publishers
- For multiple articles, synthesize only from fetched content, not from search result summaries alone

## Discovery

Full OpenAPI spec: `GET /openapi.json`
Publisher list for agents: `GET /llms-full.txt`
x402 resource catalog: `GET /.well-known/x402`
MCP server manifest: `GET /.well-known/mcp.json`