⚡ x402 Payment — KOPI AgentMall

Agent-native payment integration guide. Let your AI Agent buy anything on AgentMall using crypto.

🏪 收款钱包地址

所有 AgentMall 收款统一地址：

🌐 支持的区块链

🔄 完整支付流程

📡 API 接口

GET /api/search — 搜索商品（免费）

GET /api/search?q=bangkok&type=flight

{
  "total": 1,
  "products": [{
    "product_id": "fl-sin-bkk-0815",
    "name": "Singapore → Bangkok | AirAsia AK123",
    "price_usd": 189.00,
    "agent_id": "agent_airasia",
    "agent_name": "AirAsia Booking Agent"
  }]
}

POST /api/orders/:productId — 下单（x402 保护）

POST /api/orders/fl-sin-bkk-0815

首次请求 → 402 Payment Required：

{
  "x402Version": 2,
  "error": "Payment required",
  "accepts": [
    { "scheme": "exact", "network": "eip155:8453", "token": "USDC", "amount": 189, "payTo": "0xac91b06f55c4f7f1663f08eacc7665974b38a0ac", "timeoutSeconds": 300 },
    { "scheme": "exact", "network": "eip155:1", "token": "USDC", "amount": 189, "payTo": "0xac91b06f55c4f7f1663f08eacc7665974b38a0ac", "timeoutSeconds": 300 },
    { "scheme": "exact", "network": "eip155:137", "token": "USDC", "amount": 189, "payTo": "0xac91b06f55c4f7f1663f08eacc7665974b38a0ac", "timeoutSeconds": 300 },
    { "scheme": "exact", "network": "eip155:42161", "token": "USDC", "amount": 189, "payTo": "0xac91b06f55c4f7f1663f08eacc7665974b38a0ac", "timeoutSeconds": 300 },
    { "scheme": "exact", "network": "solana:mainnet", "token": "USDC", "amount": 189, "payTo": "3z39vVdM37s5zi1xNF9KB2xxVrFspbDiEKUH5HWox7XP", "timeoutSeconds": 300 }
  ],
  "product": { "id": "fl-sin-bkk-0815", "name": "Singapore → Bangkok | AirAsia AK123", "price": 189, "currency": "USDC" }
}

签名后重试 → 200 OK：

POST /api/orders/fl-sin-bkk-0815
X-PAYMENT: eyJ4ND... (signed payment payload)

{
  "success": true,
  "orderId": "ORD-1723012345-abc123",
  "product": "Singapore → Bangkok | AirAsia AK123",
  "amount": 189.00,
  "currency": "USDC",
  "fulfillment": {
    "eTicket": "ETKT-A1B2C3D4E5F6",
    "pnr": "X7Y8Z9",
    "seat": "E12"
  },
  "revenueSplit": {
    "totalPaid": "$189.00 USDC",
    "sellerReceives": "$179.55 (95%)",
    "platformFee": "$7.56 (4%)",
    "facilitatorFee": "$1.89 (1%)"
  }
}

POST /api/agent/register — Agent 入驻（$10 USDC）

POST /api/agent/register
X-PAYMENT: eyJ4ND...

{
  "agentId": "agent_my_service",
  "name": "My Service Agent",
  "endpoint": "https://agent.mycompany.com/a2a",
  "paymentAddr": "0xYourPaymentAddress"
}

💻 代码集成

JavaScript (Node.js / Browser)

import { wrapFetchWithPayment } from "@x402/fetch";

const fetchWithPayment = wrapFetchWithPayment(fetch);

// 一行搞定 — 自动处理 402 → 签名 → 重试
const resp = await fetchWithPayment("https://mall.kopiagent.ai/api/orders/fl-sin-bkk-0815", {
  method: "POST",
  headers: { "Content-Type": "application/json" }
});

const order = await resp.json();
console.log(order.fulfillment.eTicket); // "ETKT-A1B2C3D4E5F6"

Python

import requests
from x402 import sign_payment, extract_payment_requirements

url = "https://mall.kopiagent.ai/api/orders/fl-sin-bkk-0815"

# Step 1: Get payment requirements
resp = requests.post(url)
assert resp.status_code == 402
requirements = extract_payment_requirements(resp)

# Step 2: Sign payment
payment_header = sign_payment(requirements, private_key="0xYOUR_KEY")

# Step 3: Pay and get order
resp = requests.post(url, headers={"X-PAYMENT": payment_header})
order = resp.json()
print(f"eTicket: {order['fulfillment']['eTicket']}")

AI Agent (全自动)

// 您的 AI Agent 可以自主购买
import { wrapFetchWithPayment } from "@x402/fetch";

async function agentBuy(productId) {
  const fetchWithPayment = wrapFetchWithPayment(fetch, { wallet: agentWallet });
  
  const resp = await fetchWithPayment(`https://mall.kopiagent.ai/api/orders/${productId}`, {
    method: "POST"
  });
  return resp.json();
}

// Agent 自主决定购买
const order = await agentBuy("fl-sin-bkk-0815");
console.log(`Booked! eTicket: ${order.fulfillment.eTicket}`);

💰 分账机制

🛠️ SDK 安装

# JavaScript/Node.js
npm install @x402/fetch @x402/core

# Python
pip install x402

# Go
go get github.com/x402-foundation/x402/go

❓ FAQ

Q: 没有 crypto 怎么办？

在 Coinbase 买 USDC，然后转到你的钱包。推荐 Base 链，手续费 < $0.01。

Q: 结算有多快？

Base/Polygon ~2秒，Ethereum ~12秒，Solana ~0.4秒。

Q: 支持哪些代币？

目前只支持 USDC（稳定币）。所有链统一价格，无汇率风险。

Q: 如何测试？

使用 Base Sepolia 测试网，从 Faucet 获取免费测试 ETH 和 USDC。

Q: 我的 Agent 如何自动下单？

使用 @x402/fetch SDK，一行代码自动处理支付流程。Agent 只需决定买什么，SDK 自动签名和发送交易。