获取 eSIM 技能

通过 x402 协议，在 Base 主网（或测试网用于开发测试）上使用 USDC 购买 eSIM 数据套餐。

描述

该技能使 AI 代理能够为用户购买 eSIM 数据套餐。它使用 x402 支付协议，在 Base 主网（默认）或 Base Sepolia 测试网（用于测试）上以 USDC 完成支付，随后交付 eSIM 安装页面。

默认网络：Base 主网（生产环境 — 真实 eSIM）
测试网络：Base Sepolia（测试环境 — 模拟 eSIM）

前提条件

• 支持钱包技能或可在 Base（主网或 Sepolia）上操作 USDC 的钱包
• 钱包中需有足够 USDC 余额用于购买
• 若采用 transfer 支付方案，则需持有 ETH 支付 Gas 费用

推荐钱包：Coinbase Agentic Wallet、任意兼容 x402 的钱包，或任意支持 Base 上 USDC 转账的钱包。

网络选择

默认情况下，购买操作在 Base 主网 上进行（对应真实 eSIM）。如需测试，请显式指定测试网。

各网络适用场景

指定网络方式

用户可通过以下方式表明其网络偏好：

• 提及“testnet”、“testing”、“mock”或“demo” → 使用 Sepolia 测试网
• 未明确指定，或提及“mainnet”、“production”、“real” → 使用 Base 主网（默认）

调用时机

当用户出现以下任一情况时，应调用本技能：

• 请求获取 eSIM 或移动数据服务
• 因出境旅行需要蜂窝网络数据
• 希望为特定国家/地区购买数据套餐
• 提及需要境外联网能力
• 请求用于开发的“test”或“mock” eSIM

重要提示：交易耗时说明

加密货币交易与 eSIM 配置均非即时完成。预期耗时如下：

• USDC 转账：链上确认需 5–15 秒
• 购买完成：API 验证链上交易额外需 3–30 秒
• 整体购买流程：从发起支付至 eSIM 可用，总计约需 30–60 秒

请向用户明确告知购买正在处理中，并提示其等待确认结果。

工作流

1. 确定网络：询问或识别用户是否需要主网（真实）或测试网（测试）
2. 了解需求：询问用户所需数据服务的国家/地区
3. 查询套餐：调用 esimqr.link 查询可用套餐
4. 呈现选项：展示各数据套餐及其价格
5. 获取选择：由用户选定具体套餐
6. 确认购买：显示价格、所选网络（主网/测试网）及钱包余额，并获取用户确认
7. 执行 x402 流程：
   • 向 /api/agent/purchase（主网）或 /api/agent-testnet/purchase（测试网）发送 POST 请求 → 接收含支付详情的 HTTP 402 响应
   • 使用钱包完成支付
   • 携带支付凭证头信息重发 POST 请求
8. 交付 eSIM：返回 esimPageUrl —— 一个包含 QR 码和安装按钮的用户友好页面

示例对话

主网（真实 eSIM）

User: I need an eSIM for my trip to USA

Agent: I can help you get an eSIM! This will be a real eSIM on Base Mainnet.

[Agent searches packages]

I found these options for USA:
- US_100MB_7: 100MB / 7 Days - $0.50
- US_1_7: 1GB / 7 Days - $1.18
- US_3_7: 3GB / 7 Days - $2.50
- US_5_30: 5GB / 30 Days - $4.42

Which package would you like?

User: 1GB 7 days

Agent: The US 1GB 7-Day plan costs $1.18 USDC on Base Mainnet.

My wallet balance: $30.00 USDC

Shall I purchase this eSIM now?

User: Yes

Agent: Initiating purchase on Base Mainnet...

✓ Payment sent: 1.18 USDC
✓ Transaction: 0xabc123...

Your eSIM is ready! Install it here:
https://esimqr.link/web3/esim/agent_1707184523_abc123

测试网（用于测试的模拟 eSIM）

User: Get me a test eSIM for USA

Agent: I'll get you a test eSIM on Base Sepolia testnet (mock eSIM for testing).

[Agent searches packages on testnet]

I found test packages for USA:
- US_1_7: 1GB / 7 Days - $1.18 (testnet)
- US_5_30: 5GB / 30 Days - $4.42 (testnet)

Which would you like?

User: 1GB

Agent: The US 1GB 7-Day test plan costs $1.18 testnet USDC.

My wallet balance: 10.00 testnet USDC

Shall I purchase this test eSIM?

User: Yes

Agent: Initiating testnet purchase...

✓ Test payment sent: 1.18 USDC
✓ Transaction: 0xdef456...

Your mock eSIM is ready! (For testing only):
https://esimqr.link/web3/esim/mockagent_1707184523_abc123

API 接口端点

基础 URL：https://esimqr.link

主网端点（生产环境）

测试网端点（测试环境）

共用端点（适用于两个网络）

速率限制

• 限制：每 IP 每分钟最多 10 次请求
• 响应：HTTP 429，含 Retry-After 头
• 请尊重 Retry-After 值，优雅地处理限流

网络配置

Base 主网（默认）

Base Sepolia（测试网）

注意：付款钱包地址由 API 在报价（quote）及 HTTP 402 响应中动态返回，请勿硬编码支付地址。

支付方案（x402）

HTTP 402 响应在 accepts 数组中提供两种支付选项。请根据钱包能力选择：

如何选择支付方案

• 选用 exact 方案，当：您的钱包支持 EIP-3009 的 transferWithAuthorization 签名（如 Circle 钱包、兼容 x402 的 SDK）。优势：免 Gas —— 由中介方代为广播交易。

• 选用 transfer 方案，当：您的钱包支持标准 USDC 转账，但不支持 EIP-3009。适用于所有支持 Base 的钱包，但需用户自行支付 Gas 费用。

• 不确定？：推荐优先尝试 transfer 方案，因其兼容所有支持 USDC 的钱包。

exact 方案流程（免 Gas）：

1. 向 /api/agent/purchase（主网）或 /api/agent-testnet/purchase（测试网）发送 POST 请求 → 接收含 EIP-3009 参数的 HTTP 402 响应
2. 对 transferWithAuthorization 消息签名（无需链上交易）
3. 携带头信息重发 POST 请求：PAYMENT-SIGNATURE:
4. 中介方为您广播交易

transfer 方案流程：

1. 向 /api/agent/purchase（主网）或 /api/agent-testnet/purchase（测试网）发送 POST 请求 → 接收含支付详情的 HTTP 402 响应
2. 在对应网络上将 USDC 转账至 payTo 地址（务必确保网络正确！）
3. 携带头信息重发 POST 请求：X-PAYMENT: txHash=0x...,nonce=...

API 响应示例

查询套餐

GET /api/web3/packages?q=US

{
  "packages": [
    {"packageCode": "US_1_7", "name": "United States 1GB 7Days", ...}
  ]
}

报价（主网）

GET /api/agent/quote?packageCode=US_1_7

{
  "packageCode": "PHAJHEAYP",
  "slug": "US_1_7",
  "planName": "United States 1GB 7Days",
  "usdcAmount": "1.18",
  "paymentDetails": {
    "recipient": "",
    "chainId": 8453,
    "network": "eip155:8453"
  }
}

报价（测试网）

GET /api/agent-testnet/quote?packageCode=US_1_7

{
  "packageCode": "PHAJHEAYP",
  "slug": "US_1_7",
  "planName": "United States 1GB 7Days",
  "usdcAmount": "1.18",
  "paymentDetails": {
    "recipient": "",
    "chainId": 84532,
    "network": "eip155:84532"
  },
  "isTestnet": true
}

HTTP 402 Payment Required

POST /api/agent/purchase
Body: {"packageCode": "US_1_7"}

{
  "x402Version": 2,
  "accepts": [
    {"scheme": "exact", ...},
    {"scheme": "transfer", "amount": "1180000", "payTo": "", "extra": {"nonce": "abc123"}}
  ]
}

重要：务必始终使用 HTTP 402 响应中提供的 payTo 地址，切勿硬编码任何支付地址。

购买成功响应

POST /api/agent/purchase
Headers: X-PAYMENT: txHash=0x...,nonce=abc123
Body: {"packageCode": "US_1_7"}

{
  "success": true,
  "esimId": "agent_1707184523_abc123",
  "esimPageUrl": "https://esimqr.link/web3/esim/agent_1707184523_abc123",
  "esimDetails": {
    "iccid": "8901234...",
    "activationCode": "LPA:1$..."
  }
}

状态值说明

• pending — 订单已创建，等待开通
• processing — eSIM 正在开通中
• ready — eSIM 已就绪，可安装
• activated — eSIM 已成功安装至设备
• failed — 订单失败（请联系技术支持）
• cancelled — 模拟 eSIM 自动取消（仅测试网）

文档

• 主网文档：https://esimqr.link/api/agent/docs
• 测试网文档：https://esimqr.link/api/agent-testnet/docs
• 落地页：https://esimqr.link/agents

文件

• esim_api.py — esimqr.link 的 API 客户端（同时支持主网与测试网）

依赖项

requests>=2.28.0

Hackathon 提交信息

• 赛道：Agentic Commerce
• 协议：x402（HTTP 402 Payment Required）
• 网络：Base 主网（生产环境）、Base Sepolia（测试环境）
• 支付币种：USDC

提交至：https://www.moltbook.com/m/usdc