Cabin — 使用 USDC 进行航班搜索与预订

在 500 多家航空公司中搜索真实航班，并在 Base 上使用 USDC 完成预订。

API 基础 URL

https://api.cabin.team

端点

搜索航班

当用户希望查找航班时：

curl -X POST https://api.cabin.team/v1/search 
  -H "Content-Type: application/json" 
  -d '{
    "from": "HAN",
    "to": "ATH",
    "date": "2026-03-15",
    "return_date": "2026-03-22",
    "adults": 1,
    "class": "ECONOMY",
    "currency": "USD",
    "max_results": 5
  }'

参数说明：

• from（必填）：出发地 IATA 机场代码
• to（必填）：目的地 IATA 机场代码
• date（必填）：出发日期（格式：YYYY-MM-DD）
• return_date（可选）：往返行程的返程日期
• adults（可选，默认为 1）：乘客人数
• class（可选）：舱等类型，可选值为 ECONOMY、PREMIUM_ECONOMY、BUSINESS、FIRST
• currency（可选，默认为 USD）：价格显示所用货币
• max_results（可选，默认为 10）：最多返回结果数

响应内容包括：

• results[] —— 包含价格、航司、起降时间、经停信息的航班报价数组
• image_url —— 渲染后的 PNG 格式结果对比图 URL
• search_id —— 用于后续预订操作的搜索唯一标识 ID

向用户展示结果的方式：

• 加载并展示 image_url 指向的图片，便于用户进行可视化比价
• 利用结构化数据回答具体问题（例如：“哪一班最便宜？”、“有直飞航班吗？”）
• 始终同时显示以 USD 和对应 USDC 折算的价格

预订航班

当用户希望完成预订时：

curl -X POST https://api.cabin.team/v1/book 
  -H "Content-Type: application/json" 
  -d '{
    "offer_id": "offer_1",
    "search_id": "abc123",
    "passengers": [{
      "type": "adult",
      "given_name": "John",
      "family_name": "Doe",
      "email": "john@example.com",
      "born_on": "1990-01-15",
      "gender": "m"
    }]
  }'

必需的乘客信息：

• given_name（名）、family_name（姓）
• email（邮箱）
• born_on（出生日期，格式：YYYY-MM-DD）
• gender（性别，m/f）

响应内容包括：

• booking_id —— Cabin 预订编号（格式：CBN-YYYY-XXXX）
• amount_usdc —— 需支付的 USDC 金额
• payment.deposit_address —— Base 网络上的 USDC 充值地址
• payment.checkout_url —— 可分享给用户的支付页面 URL

USDC 支付流程

完成预订后，用户需在 Base 网络上以 USDC 完成支付：

1. 向用户展示 amount_usdc 数值及 payment.checkout_url
2. 用户可选择以下任一方式完成支付： a. 直接向 payment.deposit_address 地址发送 USDC（Base 网络） b. 访问 checkout_url，进入引导式支付流程
3. 支付成功后，预订将自动确认

若代理具备钱包能力（例如 evm-wallet 技能）：

# 查询 Base 网络上的 USDC 余额
node src/balance.js base --json

# 向充值地址发送 USDC
node src/send.js base USDC   --yes --json

查询预订状态

curl https://api.cabin.team/v1/booking/CBN-2026-XXXX

可能的状态： awaiting_payment → confirmed → checked_in

获取确认页链接

https://api.cabin.team/v1/booking/CBN-2026-XXXX/confirmation

在用户完成付款并确认后，将此 URL 分享给用户。

获取值机页链接

https://api.cabin.team/v1/booking/CBN-2026-XXXX/checkin

在临近航班值机时段时，将此 URL 分享给用户。

常用 IATA 机场代码

工作流示例

简单单程搜索

用户：“帮我找一下下周五从曼谷飞往东京的航班。”

1. 解析：from=BKK，to=NRT（或 HND），date=下周五
2. 调用 POST /v1/search
3. 将 image_url 展示给用户
4. 呈现前 3–5 个选项及其价格

往返行程预订

用户：“帮我预订一趟 3 月 15 日至 22 日从伦敦到巴塞罗那的最便宜往返航班。”

1. 搜索参数：from=LHR，to=BCN，date=2026-03-15，return_date=2026-03-22
2. 展示可选航班列表
3. 用户选定某一项 → 收集乘客信息
4. 携带乘客信息调用 POST /v1/book
5. 分享支付 URL → 用户使用 USDC 完成支付
6. 确认预订 → 分享确认页链接

多人出行

用户：“我们需要三个人从首尔飞往巴厘岛，4 月 1 日至 10 日。”

1. 搜索时设置 adults=3
2. 展示的价格为每人单价
3. 预订时需收集全部三位乘客的信息
4. 总 USDC 金额 = 单人价格 × 3

错误处理

• 无搜索结果：建议尝试邻近机场或调整出发/返程日期
• 预订已过期：搜索结果有效期为 30 分钟，需重新发起搜索
• 支付超时：预订创建后 1 小时内未完成支付即自动失效
• 机场代码无效：提示用户正确的 IATA 代码

Base 上的 USDC

• 链：Base（以太坊 L2）
• 代币：USDC（合约地址：0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913）
• Gas 费：约 $0.01/笔交易
• 确认时间：约 2 秒