HTTP API

基址：。输入输出均为 JSON。文档页与这些路由分开。

GET /health

存活检查。用于探针，不用于支付逻辑。

curl -sS {{BASE}}/health

{
  "status": "ok",
  "product": "x402-gonka",
  "network": "cosmos:gonka-mainnet",
  "payTo": "gonka1…"
}

GET /supported

本协调器会验证并结算的 x402 类型。客户端和卖家 SDK 应先读此项，再假定 USDC 或 GNK 可用。

curl -sS {{BASE}}/supported

{
  "kinds": [
    {
      "x402Version": 2,
      "scheme": "exact",
      "network": "cosmos:gonka-mainnet",
      "extra": {
        "assetTransferMethod": "signed-tx",
        "paymentFlow": "upfront"
      }
    }
  ],
  "extensions": [],
  "signers": { "cosmos:gonka-mainnet": [] }
}

signers 为空：协调器不代付、不联署。买家是唯一签名者。

POST /verify

只读校验。不广播，也不消耗载荷。若你想在不可撤销的工作前先廉价拒绝，可以使用它；在本网络上提供资源前仍须调用 /settle。

curl -sS -X POST {{BASE}}/verify \
  -H 'Content-Type: application/json' \
  -d '{"x402Version":2,"paymentPayload":{},"paymentRequirements":{}}'

成功：{"isValid":true,"payer":"gonka1…"}。失败：{"isValid":false,"invalidReason":"…","payer":"…"}。

POST /settle

请求体与 /verify 相同。以 BROADCAST_MODE_SYNC 广播 payload.signedTx，然后等待交易出现区块高度（最长约 20 秒）。

{
  "success": true,
  "payer": "gonka1…",
  "transaction": "ABC123…",
  "network": "cosmos:gonka-mainnet",
  "amount": "1000"
}

失败时 success 为 false，并设置 errorReason。若已广播但未确认，errorReason 为 settlement_pending，且 transaction 仍会填充 — 不要假定已失败。

请求体

{
  "x402Version": 2,
  "paymentPayload": {
    "x402Version": 2,
    "accepted": {
      "scheme": "exact",
      "network": "cosmos:gonka-mainnet",
      "amount": "1000",
      "asset": "ngonka",
      "payTo": "gonka1…",
      "maxTimeoutSeconds": 60
    },
    "payload": {
      "signature": "<base64>",
      "authorization": {
        "from": "gonka1…",
        "to": "gonka1…",
        "amount": "1000",
        "denom": "ngonka",
        "timeoutAt": 1710000000
      },
      "signedTx": "<base64 TxRaw>"
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "cosmos:gonka-mainnet",
    "amount": "1000",
    "asset": "ngonka",
    "payTo": "gonka1…"
  }
}

若 paymentRequirements.scheme 为空，协调器使用 paymentPayload.accepted。

GET /discovery/resources

本主机公布的付费资源列表（Bazaar 风格）。目前只有演示路由。相同条目也显示在资源列表。

curl -sS {{BASE}}/discovery/resources

{
  "x402Version": 2,
  "items": [
    {
      "resource": "https://…/demo",
      "type": "http",
      "x402Version": 2,
      "accepts": [],
      "lastUpdated": 1710000000,
      "metadata": { "provider": "Gonka Labs", "product": "x402-gonka" }
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 1 }
}

GET /demo

付费资源示例。也接受 POST /demo。没有 PAYMENT-SIGNATURE 会得到 402。成功结算后返回：

{
  "ok": true,
  "product": "x402-gonka",
  "message": "Payment settled on Gonka.",
  "transaction": "…",
  "payer": "gonka1…",
  "network": "cosmos:gonka-mainnet",
  "explorer": "https://gonka.gg/tx/…"
}

这是演示，不是生产商户 API。按卖家接入你自己的路由。