HTTP API

Base URL: . JSON in, JSON out. Docs pages are separate from these routes.

GET /health

Liveness. Use this for probes, not for payment logic.

curl -sS {{BASE}}/health

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

GET /supported

x402 kinds this facilitator will verify and settle. Clients and seller SDKs should read this before assuming USDC or GNK work.

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 is empty: the facilitator does not sponsor or co-sign. The buyer is the only signer.

POST /verify

Read-only validation. Does not broadcast and does not consume the payload. Use it if you want a cheap reject before work you cannot undo; still call /settle before serving on this network.

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

Success: {"isValid":true,"payer":"gonka1…"}. Failure: {"isValid":false,"invalidReason":"…","payer":"…"}.

POST /settle

Same body as /verify. Broadcasts payload.signedTx with BROADCAST_MODE_SYNC, then waits until the tx has a block height (about 20s max).

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

On failure success is false and errorReason is set. If the tx was broadcast but not confirmed, errorReason is settlement_pending and transaction is still populated — do not assume it failed.

Request body

{
  "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…"
  }
}

If paymentRequirements.scheme is empty, the facilitator uses paymentPayload.accepted.

GET /discovery/resources

Bazaar-style list of paid resources this host advertises. Currently the demo route only. The same items render on Resource listing.

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

Example paid resource. POST /demo is accepted too. Without PAYMENT-SIGNATURE you get 402. After a successful settle you get:

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

That body is from a real GNK settle. See the tx on gonka.gg. Commands and RPC checks are on Get started.

This is a demo, not a production merchant API. Wire your own routes as described in Sellers.