| name | travala |
| description | Travel Agent — book AND cancel real hotels and stays end to end. Use when the user wants to BOOK or RESERVE a hotel/stay (not just look one up): "book me a hotel in Lisbon", "reserve that room"; or to CANCEL / look up a booking they made through you: "cancel my hotel", "what's my booking". Discovery is free; booking spends real USDC and always requires the user's explicit confirmation; cancelling requires a code Travala emails to the booking address. Hotels and stays only (no flights). Routes payment through the platform's proven x402 rail — never invent payment logic, never sign a transfer yourself. |
STOP — What Booking Actually Needs (the money is gated, not the door)
Searching is free for every user, always: no setup, no wallet, no plan. Never tell
a user to enable anything before searching, and never pre-screen them yourself —
attempt the flow, and relay the platform's answer at the moment it appears. The
platform gates the MONEY, and it speaks through the booking script's narrations.
The real requirements are exactly two, each asked at the moment it matters
(booking is open to EVERY plan, Starter included — no tier gate anywhere):
- A funded agent wallet (USDC on Base). The
would_drain_wallet narration
gives the exact amount needed and the full wallet address. Relay as-is.
- A one-tap dashboard approval for THIS booking — every booking, every time.
That tap is the consent; a chat "yes" is never enough (see Rule 2).
Booking does NOT need the "autonomous spending" switch (decoupled 2026-06-12).
That switch grants a different power — the agent moving money on its own
initiative — and hotel booking is never that: the user personally approves the
exact room and price before a dollar moves. Never send a user to Spending
settings to book a hotel.
A gated response now means exactly one thing: the operator paused booking
platform-wide (an emergency stop). Relay plainly and suggest trying later.
Funding — answer these COLD, never via a failed booking
A user may ask "how do i fund my agent's wallet", "how much usdc do i have", or
"how do i add money so you can book" with no booking in flight. Answer at the
same standard as the deny-time narration — exact address, exact network, exact
path — without making them attempt a booking first:
- Your wallet address: read it yourself —
grep ^BANKR_WALLET_ADDRESS= ~/.openclaw/.env
(and ~/.openclaw/workspace/WALLET.md is the wallet ground truth; read it for
anything deeper). Give the user the FULL address, never truncated — they will
copy-paste it into a send.
- What to send: USDC on Base (the network matters — USDC on another chain
will not arrive in a usable form). Any wallet or exchange that supports Base
withdrawals works.
- Where it lives in the dashboard: instaclaw.io dashboard, the Wallet card —
address and current balance, with a copy button.
- Balance questions: don't guess a number. Point to the dashboard Wallet card,
or give the verifiable link:
https://basescan.org/address/<their address>.
- What funding unlocks: autonomous booking through this skill (a room is
typically $50-150 in USDC, plus a small cushion for fees), and everything else
the agent can pay for on its own wallet.
The shape of a good cold answer: "your agent wallet is 0x... (full address, also
in your dashboard under Wallet). send USDC on Base, any amount; a typical hotel
runs $50-150. once it's funded i can book with your one-tap approval."
NEVER build your own Travala client, sign a USDC transfer, call travala_book
directly, write .env files, or construct an X-PAYMENT by hand. The platform
manages the OAuth token (off your VM), the payment rail, and the consent gate.
Improvising here moves real money incorrectly.
Travel Agent (Travala) — discover free, book with consent
name: travala
display: Travel Agent
version: 0.1.0
updated: 2026-06-10
author: InstaClaw / Wild West Bots
triggers:
keywords: [book hotel, reserve, booking, travala, stay, lodging, accommodation, check in, check out, nights]
phrases: ["book me a hotel", "reserve that room", "book the trip", "book a stay", "reserve a hotel in"]
NOT: [just looking, what's the weather, flight status only, "how much is a hotel" (that's a search, see below)]
MANDATORY RULES — read before any booking
Rule 0 — Use the platform scripts. Never improvise payments.
The skill's scripts live at ~/.openclaw/skills/travala/scripts/:
travala-search.mjs — find hotels/packages (free, public, no money).
travala-book.mjs — book one (routes through the frontier x402 rail + consent).
travala-manage.mjs — look up a booking's details + cancellation policy (read-only).
travala-cancel.mjs — cancel a booking the user made through you (two-step, email code).
You MUST use these. NEVER call the Travala MCP travala_book / travala_cancel_booking
/ travala_manage_bookings tools directly — they are intentionally not wired as native
tools on your VM so you cannot pay or cancel around the platform's gates. NEVER sign a
transfer or build an X-PAYMENT yourself.
Rule 1 — Two steps, never one: SEARCH, then (with consent) BOOK.
Discovery and booking are separate on purpose. A search returns a packageId +
sessionId. You may search freely. You may book ONLY after the user explicitly
confirms the specific option, price, and guest details.
Rule 2 — Consent is ALWAYS required, and the user approves it from their dashboard (one tap).
A chat "yes" is NOT enough to spend money on a booking — the platform requires an
unforgeable browser-session approval (so a confused or hijacked agent can never
spend on its own). The flow:
- You present the booking summary: hotel/package, dates, guests, total price, and
cancellation policy.
- You run
travala-book.mjs. It returns an approval link (approval_url).
- You give the user the link and say: "approve this $X booking from your dashboard
— one tap."
- The user taps it (in their logged-in browser). Then you finish the booking.
Never assume approval. Never claim a booking is done before the user has tapped.
One booking = one dashboard tap.
Rule 3 — The price you charge is the on-chain price, not the sticker price.
The platform authorizes and signs against the booking's maxAmountRequired (the
exact USDC amount), which can be a few cents above the displayed price (fees).
The script handles this — never hand-edit an amount.
Rule 4 — Refundable first, and tell the user the policy.
Prefer refundable inventory and always state the cancellation policy in your
confirmation. The user is spending real money on a real reservation.
Rule 5 — You CAN cancel a booking the user made through you. Refunds are Travala
credit, never crypto back to the wallet — never say otherwise.
You can cancel and look up bookings made through you (see "How to cancel", below).
Two hard truths you must always tell the user honestly:
- Refunds are Travala Travel Credit, not USDC. When a booking is cancelled,
any refund posts as Travala travel credit to their account, ~7 business days
later — it does NOT come back on-chain to their wallet. The crypto payment is
final. NEVER promise USDC back, a wallet refund, or an on-chain reversal. Say
"expected as Travala credit", never "refunded" as if it's done and in-wallet.
- You can't change dates or rooms — that's cancel-and-rebook. Travala has no
modify/amend tool. If the user wants different dates or a different room, the
only path is: cancel the existing booking (within its policy, possibly with a
fee) and book a new one. Tell them that plainly; don't imply an in-place change.
If a booking wasn't made through you (no record on this agent), you can't cancel it
— tell them to use travala.com or their Travala confirmation email.
How to book (the flow)
-
Search (free):
node ~/.openclaw/skills/travala/scripts/travala-search.mjs --type hotel \
--args '{"location":"Lisbon","checkIn":"2026-06-24","checkOut":"2026-06-26","rooms":["2"]}' --json
Present 1–3 good options with price + cancellation policy. Note each option's
packageId and sessionId.
-
Summarize for the user. The chosen option, price, dates, guests, and cancel
policy. (No chat "yes" needed yet — the real consent is the dashboard tap.)
-
Book (kicks off approval, then pays, then saves the booking so you can cancel it later):
node ~/.openclaw/skills/travala/scripts/travala-book.mjs \
--package-id <packageId> --session-id <sessionId> \
--customer '{"firstName":"...","lastName":"...","email":"...","phone":"..."}' \
--max-usd <a-cap-at-or-above-the-quote> --why "Lisbon hotel, Jun 24–26" \
--snapshot '{"hotelName":"...","checkIn":"2026-06-24","checkOut":"2026-06-26","room":"...","displayPrice":219.00,"currency":"USD","cancellationPolicy":"<the policy string from search>","freeCancellationUntilUtc":"<the deadline from search, if any>","refundable":true}' \
--json
Always pass --snapshot with the chosen option's details from the search
result (hotel name, dates, room, price, the cancellation policy string, and
the free-cancellation deadline). This is saved with the booking and is what
lets you tell the user their real cancellation deadline later — it is
impossible to recover once the search session expires. Use the customer's
REAL email: it's where Travala sends the cancellation code if they ever cancel.
Possible outcomes:
awaiting_approval: true (the normal first response) — the script returns
an approval_url and a request_id. Give the user the link: "approve this $X
booking from your dashboard — one tap: <approval_url>". When they tell you
they've tapped it, resume the SAME booking by re-running with
--retry --request-id <that request_id> (plus the same --package-id,
--session-id, --customer, --max-usd). The link expires in 15 minutes; if
it does, the resume returns a fresh approval_url — just relay the new one.
paid: true — done. Report the booking ref, dates, total paid, tx hash,
and cancel policy.
outcome: "deny" — the script's narration already explains the TRUE cause:
over the travel limit, an empty wallet, spending paused by the operator, or a
booking attempt that was already finalized/revoked. Relay that narration
as-is — it names the real remedy. Do not retry or improvise.
gated — the operator paused booking platform-wide (emergency stop; see
the STOP section). Relay plainly and suggest trying later.
-
Recovery / status is built in: any --retry checks book-status first, so a
booking that already went through is never charged twice. Always resume with
--retry --request-id <id>; never start a fresh request_id for the same quote
(the user's approval is bound to that exact spend).
How to cancel (or look up) a booking
You can cancel or look up any booking the user made through you (it's saved in
your trips with a booking ref). Cancellation is protected by a code Travala emails
to the booking address — so it's a two-step flow, and you can't skip it.
-
(Recommended first) Show the booking + its cancellation policy so the user
sees the deadline and any fee before they decide:
node ~/.openclaw/skills/travala/scripts/travala-manage.mjs --booking-id <ref> --json
This returns "I emailed a code…" — ask the user to read back the 6 digits, then:
node ~/.openclaw/skills/travala/scripts/travala-manage.mjs --booking-id <ref> --otp <code> --json
Now you can state the real status, dates, price, and cancellation policy.
-
Cancel (two steps):
node ~/.openclaw/skills/travala/scripts/travala-cancel.mjs --booking-id <ref> --json
Never tell the user a refund is going back to their wallet or on-chain. Never
claim a cancellation is done before the cancelled state comes back. Never invent
a way to change dates in place — that's cancel-and-rebook (Rule 5).
Routing — StableTravel plans, Travala books
- "find / compare / how much is a hotel or flight" → StableTravel search
(planning, no money). This is the default for any non-booking travel question.
- "book / reserve / pay for that hotel" → Travala (this skill, real money,
consent-always).
If booking is denied (plan, spending, funding — STOP section), you can still plan the whole trip with
StableTravel and hand the user direct links to book themselves.