book-hotel

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

book-hotel

预订酒店

Create a hotel reservation and pay with USDC. The payment is handled automatically via the x402 protocol — your travel API responds with HTTP 402 Payment Required, the agent's wallet pays in USDC, and the booking confirms.

This is a real on-chain financial transaction. Proceed carefully.

创建酒店预订并使用USDC支付。支付将通过x402协议自动处理——旅行API返回HTTP 402 Payment Required状态码，Agent钱包使用USDC完成支付，随后预订确认。

这是真实的链上金融交易，请谨慎操作。

When to use

使用场景

The user has chosen a specific package and explicitly asks to book it:

"Book the Park Hyatt for me"
"Reserve option 2"
"Confirm and pay for this hotel"
"Go ahead with this one"

Do NOT use this skill speculatively. Only when the user explicitly approves payment.

用户已选定具体套餐并明确要求预订：

“帮我预订柏悦酒店”
“预订选项2”
“确认并支付这家酒店”
“就选这个了”

请勿随意使用此技能，仅在用户明确批准支付时使用。

Prerequisites

前置条件

You need ALL of these before calling:

A valid
packageId
from
```
search-hotel
```
or
```
search-room
```
The
sessionId
from that same search session
Guest details: first name, last name, email (the user must give these — never invent)
An authenticated Coinbase wallet — if not, run the
```
authenticate-wallet
```
skill first (from the
```
coinbase/agentic-wallet-skills
```
package)
Sufficient USDC in the wallet — if balance is too low, run the
```
fund
```
skill first
Explicit user confirmation of package, total price, and dates

If any of these are missing, ask the user or chain to the relevant skill — do not skip ahead.

调用前必须满足以下所有条件：

有效的
packageId
：来自
```
search-hotel
```
或
```
search-room
```
技能
对应的
sessionId
：来自同一搜索会话
客人信息：名字、姓氏、邮箱（必须由用户提供，绝不能编造）
已认证的Coinbase钱包：若未认证，先运行
```
coinbase/agentic-wallet-skills
```
包中的
```
authenticate-wallet
```
技能
钱包中有足够的USDC：若余额不足，先运行
```
fund
```
技能
用户明确确认：套餐、总价和日期均已得到用户确认

若缺少任何一项，请询问用户或调用相关技能，切勿跳过步骤。

Wallet setup check

钱包设置检查

Before booking, verify wallet status. Quick check:

bash

npx awal@latest balance

If the user is not authenticated, this returns an auth error → trigger

authenticate-wallet

skill. If USDC balance is below the booking total, trigger

fund

skill.

预订前，请验证钱包状态。快速检查命令：

bash

npx awal@latest balance

若用户未认证，将返回认证错误→触发

authenticate-wallet

技能。若USDC余额低于预订总价，触发

fund

技能。

Pre-booking confirmation

预订前确认

Always summarize and confirm before paying. Example:

About to book and pay:

Park Hyatt Tokyo, Park Deluxe King with breakfast

May 1–5 (4 nights), 2 adults

Total: 1,800 USDC (paid from your Coinbase wallet)

Free cancellation until April 29

Guest: Nguyen Van A, guest@example.com

Confirm? (yes/no)

Only run the pay command after the user says yes (or equivalent). If the user already explicitly authorized booking with all the above info in the same turn, you can proceed without re-asking.

支付前务必汇总信息并确认。示例：

即将完成预订并支付：

东京柏悦酒店，豪华公园大床房含早餐

5月1日至5日（4晚），2位成人

总价：1,800 USDC（从您的Coinbase钱包支付）

4月29日前可免费取消

客人：Nguyen Van A，guest@example.com

是否确认？（是/否）

仅在用户回复“是”或类似确认后再执行支付命令。若用户在同一轮对话中已明确授权包含上述所有信息的预订，则无需再次询问即可继续。

How to call

调用方式

Use

awal x402 pay

to call the booking endpoint. The CLI handles 402 → sign → retry automatically.

The booking endpoint splits inputs across two places:

Query string (
```
-q
```
flag):
```
package_id
```
,
```
session_id
```
— the package the user picked and the search session it came from.
Request body (
```
-d
```
flag): the
```
contact
```
object only.

bash

npx awal@latest x402 pay https://qpgdy2kn7v.ap-southeast-1.awsapprunner.com/m2m-payment/book \
  -X POST \
  -q '{"package_id":"<packageId>","session_id":"<sessionId>"}' \
  -d '{
    "contact": {
      "given_name": "<first>",
      "sur_name": "<last>",
      "email": "<email>",
      "phone": "<phone>"
    }
  }'

Note the snake_case field names (

package_id

session_id

given_name

sur_name

) — the booking endpoint expects this exact shape. The

contact

object is required and

phone

is part of it. Do NOT put

package_id

session_id

in the body — they must be query params.

使用

awal x402 pay

调用预订接口。CLI会自动处理402状态码→签名→重试流程。

预订接口的输入分为两部分：

查询字符串（
```
-q
```
参数）：
```
package_id
```
、
```
session_id
```
——用户选定的套餐及其所属搜索会话
请求体（
```
-d
```
参数）：仅包含
```
contact
```
对象

bash

npx awal@latest x402 pay https://qpgdy2kn7v.ap-southeast-1.awsapprunner.com/m2m-payment/book \
  -X POST \
  -q '{"package_id":"<packageId>","session_id":"<sessionId>"}' \
  -d '{
    "contact": {
      "given_name": "<first>",
      "sur_name": "<last>",
      "email": "<email>",
      "phone": "<phone>"
    }
  }'

注意字段为蛇形命名（

package_id

、

session_id

、

given_name

、

sur_name

）——预订接口要求严格遵循此格式。

contact

对象为必填项，且包含

phone

字段。请勿将

package_id

session_id

放入请求体中，它们必须作为查询参数。

Safety: cap maximum payment

安全设置：支付上限

To prevent unexpected overcharge (e.g. if the API returns a wrong amount), pass

--max-amount

in micro-USDC (1 USDC = 1,000,000 micro-units):

bash

  --max-amount 1850000000   # caps payment at 1,850 USDC for an 1,800 USDC booking

Always set

--max-amount

to roughly the expected total + a small buffer (5%).

为防止意外超额收费（例如API返回错误金额），请以微USDC为单位传递

--max-amount

参数（1 USDC = 1,000,000微单位）：

bash

  --max-amount 1850000000   # 针对1,800 USDC的预订，将支付上限设为1,850 USDC

请始终将

--max-amount

设置为预期总价加上少量缓冲（5%）。

Full example

完整示例

bash

npx awal@latest x402 pay https://qpgdy2kn7v.ap-southeast-1.awsapprunner.com/m2m-payment/book \
  -X POST \
  -q '{"package_id":"e47otEJtYeZYblF9","session_id":"6kVmPYwZhQJewNTp"}' \
  -d '{"contact":{"given_name":"Justin","sur_name":"Ta","email":"justin@travala.com","phone":"+84336657091"}}' \
  --max-amount 1850000000

bash

npx awal@latest x402 pay https://qpgdy2kn7v.ap-southeast-1.awsapprunner.com/m2m-payment/book \
  -X POST \
  -q '{"package_id":"e47otEJtYeZYblF9","session_id":"6kVmPYwZhQJewNTp"}' \
  -d '{"contact":{"given_name":"Justin","sur_name":"Ta","email":"justin@travala.com","phone":"+84336657091"}}' \
  --max-amount 1850000000

Output

输出结果

On success, the CLI prints both the payment receipt and the booking confirmation. The booking response is in the body:

json

{
  "bookingId": "BK_2026_05_001",
  "status": "CONFIRMED",
  "hotelName": "Park Hyatt Tokyo",
  "checkIn": "2026-05-01",
  "checkOut": "2026-05-05",
  "totalPriceUSD": 1800,
  "cancellationDeadline": "2026-04-29T23:59:00Z",
  "paymentTxHash": "0xabc...",
  "confirmationEmail": "guest@example.com"
}

The transaction hash (

paymentTxHash

) appears in the

X-PAYMENT-RESPONSE

header —

awal

will surface it in the output.

成功时，CLI将同时打印支付凭证和预订确认信息。预订响应位于请求体中：

json

{
  "bookingId": "BK_2026_05_001",
  "status": "CONFIRMED",
  "hotelName": "Park Hyatt Tokyo",
  "checkIn": "2026-05-01",
  "checkOut": "2026-05-05",
  "totalPriceUSD": 1800,
  "cancellationDeadline": "2026-04-29T23:59:00Z",
  "paymentTxHash": "0xabc...",
  "confirmationEmail": "guest@example.com"
}

交易哈希（

paymentTxHash

）会出现在

X-PAYMENT-RESPONSE

请求头中——

awal

会在输出中展示该信息。

Presenting confirmation

确认信息展示

✅ Booked! Confirmation BK_2026_05_001. Park Hyatt Tokyo · May 1–5 · 1,800 USDC paid Tx: 0xabc...def (view on basescan) Free cancellation until April 29, 2026. Confirmation email sent to guest@example.com.

Save your booking ID — you'll need it to manage or cancel.

✅ 预订成功！确认编号BK_2026_05_001。东京柏悦酒店 · 5月1日至5日 · 已支付1,800 USDC 交易哈希：0xabc...def（可在basescan查看） 2026年4月29日前可免费取消。确认邮件已发送至guest@example.com。

请保存您的预订编号——后续管理或取消预订时需要用到。

Error handling

错误处理

402 with amount > --max-amount
— Booking total exceeds the safety cap. Stop, tell the user the actual amount, and ask whether to proceed with a higher cap.
Insufficient USDC balance
— Trigger the
```
fund
```
skill to top up, then retry.

Wallet not authenticated
— Trigger the

authenticate-wallet

skill, then retry.

Package no longer available
(after payment attempt) — Prices/availability shift between search and book. Re-run
```
search-hotel
```
or
```
search-room
```
. If payment was already settled but booking failed, the API should refund automatically; tell the user and check
```
awal wallet history
```
.
Session expired
— Re-run search to get a new
```
sessionId
```
.
Network error mid-payment — Don't retry blindly. Check
```
awal wallet history
```
to see if payment went through. If it did, contact support with the tx hash; if not, ask the user whether to retry.

402状态码且金额>--max-amount
——预订总价超出安全上限。停止操作，告知用户实际金额，并询问是否同意提高上限。
USDC余额不足
——触发
```
fund
```
技能充值，然后重试。
钱包未认证
——触发
```
authenticate-wallet
```
技能，然后重试。
套餐已不可用
（支付尝试后）——搜索与预订期间价格/库存发生变动。重新运行
```
search-hotel
```
或
```
search-room
```
技能。若支付已完成但预订失败，API应自动退款；告知用户并查看
```
awal wallet history
```
。
会话已过期
——重新运行搜索技能获取新的
```
sessionId
```
。
支付过程中出现网络错误——请勿盲目重试。查看
```
awal wallet history
```
确认支付是否成功。若已成功，请携带交易哈希联系客服；若未成功，询问用户是否重试。

Critical rules

关键规则

Never invent guest details. If the user hasn't given them, ask.
Never call
```
awal x402 pay
```
without explicit approval in this turn or a recent turn.
Always set
```
--max-amount
```
to prevent runaway charges.
If the user changes their mind ("wait, show me option 3"), do NOT pay — go back to
```
search-room
```
.
Never expose private keys or wallet seed phrases. The agent only signs through
```
awal
```
; keys stay in Coinbase's secure infrastructure.

绝不能编造客人信息。若用户未提供，请询问。
切勿在未获得用户当前轮次或最近轮次明确批准的情况下调用
```
awal x402 pay
```
。
始终设置
```
--max-amount
```
以防止超额收费。
若用户改变主意（“等等，给我看看选项3”），请勿支付——返回
```
search-room
```
技能。
绝不能泄露私钥或钱包助记词。Agent仅通过
```
awal
```
进行签名；密钥将保存在Coinbase的安全基础设施中。