Agent 支付（x402）

这页适合想把自己的 API、内容接口或工具服务卖给 AI agent 的开发者。接入后，任何带钱包的 agent 都能按次付费调用你的接口：无账号、无卡、无人工结账页，一次 HTTP 402 往返完成支付。

Taria Pay 的 agent 支付兼容 x402 v2 开放标准，主流 x402 客户端（如 @x402/fetch）可以直接付款。

它和普通收款有什么不同

• 非托管：资金从 agent 钱包直达你配置的收款钱包，不经过 Taria Pay 资金池，无需提现。
• 免完整企业认证：注册后配置收款钱包即可开通。
• Gas 由平台垫付：agent 只需要持有稳定币（USDC），不需要 ETH；上链的 gas 由 Taria Pay 的 relayer 支付。

标准流程

agent
  -> 调用你的付费接口（无支付）
你的服务（Taria Pay 中间件）
  -> 返回 402 + PAYMENT-REQUIRED（金额、代币、收款地址）
agent
  -> 用钱包签一个 EIP-3009 转账授权（离线签名，不上链）
  -> 带 PAYMENT-SIGNATURE 重试请求
Taria Pay
  -> 验签、防重放检查、上链结算（agent 钱包 -> 你的钱包）
你的服务
  -> 放行业务响应 + PAYMENT-RESPONSE（含结算 tx 与签名回执）

开始前准备

你需要：

• 一个 Taria Pay 商家账户和 API key
• 一个你自己控制的收款钱包地址（EVM）
• 一个 Node.js 服务端（Express 或兼容框架）

支持范围（当前版本）：

• 代币：USDC（EURC 亦可）；USDT 暂不支持
• 定价：单笔固定价或按请求动态定价，金额用代币最小单位表示（USDC 6 位小数，10000 = 0.01 USDC）

Step 1：创建收费端点

一个「端点」描述一条可收费的资源：价格、链、代币、收款钱包。

curl -s -X POST https://api.tariapay.com/merchant/v1/agent/endpoints \
  -H "x-api-key: $TARIAPAY_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "market-data",
    "resourceUrl": "https://api.yoursite.com/v1/market-data",
    "chainId": 8453,
    "currency": "USDC",
    "payoutAddress": "0xYourPayoutWallet",
    "pricingMode": "fixed",
    "amountMinor": "10000"
  }'

记下返回的 endpoint.id。

可选参数：

• pricingMode: "dynamic" — 价格由你的服务端在每次请求时给出（中间件的 amountMinor 回调）。
• releasePolicy — included（默认，交易上链即放行，约 2 秒）或 confirmed（等满确认数再放行，适合高客单价内容）。

Step 2：给路由加上付费中间件

npm install @tariapay/sdk

import express from "express";
import { x402PaymentRequired } from "@tariapay/sdk/x402";

const app = express();

app.get(
  "/v1/market-data",
  x402PaymentRequired({
    apiKey: process.env.TARIAPAY_API_KEY,
    endpointId: process.env.TARIAPAY_ENDPOINT_ID,
  }),
  (req, res) => {
    // 走到这里说明支付已结算；结算信息在 req.tariaPayment 里。
    res.json({ data: "...", paidTx: req.tariaPayment?.txHash });
  },
);

中间件会自动处理 402 challenge 的签发、支付凭证的转发结算、以及 PAYMENT-RESPONSE 回执头的写入。API key 只能放在服务端。

Step 3：测试一次付费调用

用仓库里的示例 agent 客户端（或任意 x402 v2 客户端）：

# examples/paid-api-demo 提供了完整的可运行示例
AGENT_PRIVATE_KEY=0xAgentWalletKey node agent.mjs https://api.yoursite.com/v1/market-data

agent 钱包只需要持有对应链上的 USDC。第一次请求返回 402，客户端签名后重试， 成功响应带 PAYMENT-RESPONSE 头，内含结算交易 hash 和平台签名的回执。

结算与对账

• 资金直达你的收款钱包，可在链上浏览器里按 payoutAddress 查看每笔入账。
• 每笔成功结算都会生成一张签名回执（receipt）：包含金额、付款方、交易 hash， 由平台的回执密钥做 EIP-191 签名，可独立验证、可审计。
• 配置了 webhook 的商户会收到 agent_payment.settled 事件（与现有 webhook 签名与重试机制一致，见接收支付结果）。
• 查询单笔状态：GET /merchant/v1/agent/challenges/:challengeId。

费用

Beta 期免费（只做用量统计，不收费）。正式定价：每月前 1,000 笔结算免费， 超出部分每笔 max($0.005, 交易额 × 0.3%)，按月从预充值余额扣除，用量越大单价越低。

注意事项

• 收款地址在 challenge 签发时快照：修改端点的 payoutAddress 不影响已发出的 challenge。
• 一个支付授权只能用一次（链上 nonce + 平台双重防重放）；agent 重试同一笔已结算的 支付会直接拿回原回执，不会重复扣款。
• releasePolicy: "included" 下存在极小的链重组窗口，出售高价值内容请使用 confirmed。