HTTP API

Базовый URL: . На вход и выход — 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

Проверка только на чтение. Не транслирует и не расходует payload. Используйте, если нужен дешёвый отказ до необратимой работы; на этой сети перед выдачей всё равно вызывайте /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. Транслирует payload.signedTx с BROADCAST_MODE_SYNC, затем ждёт, пока у транзакции появится высота блока (около 20 с максимум).

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

При неуспехе success ложно и задан 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. После успешного settle:

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

Это тело реального settle в GNK. Транзакция на gonka.gg. Команды и проверки RPC — в Начале работы.

Это демо, не продакшен API продавца. Свои маршруты подключайте как в разделе Продавцы.