Protocol

This facilitator speaks x402 version 2 over HTTP. The chain binding is Cosmos exact with a client-signed TxRaw.

Network binding

x402 version	`2`
Scheme	`exact`
Network	`cosmos:gonka-mainnet` (CAIP-2)
Transfer method	`signed-tx` — client signs, facilitator broadcasts
Payment flow	`upfront` — settle, then serve. `/verify` is not required for that ordering.

The generic protocol is documented at docs.x402.org and in the v2 specification. This page is the Gonka binding.

Headers

`PAYMENT-REQUIRED`	Server → client. Base64 JSON `PaymentRequired`. Sent on 402.
`PAYMENT-SIGNATURE`	Client → server. Base64 JSON `PaymentPayload`.
`PAYMENT-RESPONSE`	Server → client. Base64 JSON settle result. Sent after an attempt, success or fail.

Encoding is standard base64 of UTF-8 JSON, not base64url. CORS exposes the payment headers so browsers can read them.

PaymentRequired

{
  "x402Version": 2,
  "error": "PAYMENT-SIGNATURE header is required",
  "resource": {
    "url": "https://example/demo",
    "description": "…",
    "mimeType": "application/json",
    "serviceName": "x402-gonka",
    "tags": ["gonka", "x402", "usdc"]
  },
  "accepts": [ { "scheme": "exact", "network": "cosmos:gonka-mainnet", "amount": "1000", "asset": "ngonka", "payTo": "gonka1…", "maxTimeoutSeconds": 60, "extra": {} } ],
  "extensions": {}
}

accepts[].extra on this network includes name, decimals, assetTransferMethod, and paymentFlow.

Payment payload

The object inside PAYMENT-SIGNATURE:

`x402Version`	`2`
`accepted`	The `PaymentRequirements` you fulfilled.
`payload.signedTx`	Base64 protobuf `TxRaw` (body, auth info, signature).
`payload.signature`	Base64 of the 64-byte secp256k1 signature (same bytes as in `TxRaw`).
`payload.authorization.from`	Payer `gonka1…`. Must match the tx signer.
`payload.authorization.to`	Must equal `accepted.payTo`.
`payload.authorization.amount`	Atomic units. Tx amount must be ≥ this and ≥ `accepted.amount`.
`payload.authorization.denom`	`ngonka` or the USDC contract.
`payload.authorization.timeoutAt`	Unix seconds. If set in the past, rejected.

Transaction shape

GNK

First (and only) message: /cosmos.bank.v1beta1.MsgSend with a single coin {denom: "ngonka", amount}.

USDC

First message: /cosmwasm.wasm.v1.MsgExecuteContract. contract is the USDC CW-20. msg is JSON {"transfer":{"recipient":"…","amount":"…"}}.

Auth info

One signer, /cosmos.crypto.secp256k1.PubKey, SIGN_MODE_DIRECT (mode 1), fee 0ngonka, gas limit typically 120000. SignDoc is body_bytes || auth_info_bytes || chain_id || account_number, hashed with SHA-256.

What verify checks

Version, scheme, and network.
signedTx decodes to a supported message.
Recipient, asset, and amount match requirements.
Authorization from matches the signer address.
On-chain account number/sequence match the signed tx.
Signature verifies against the SignDoc.
On /verify only: payer balance ≥ amount.
On /settle only: TxRaw has not been settled before, then broadcast and wait for a block.

Rejection codes are listed on Errors.