Kaspa x402

Demo Implementer Guide

Status: alpha, testnet-only guide for the deployed alpha.8 contract. The hosted gateway is an integration target, not a production or mainnet service.

Start With The Artifacts

Canonical site:

https://kaspa-x402.org

Useful entry points:

Install the alpha packages explicitly:

npm install @kaspa-x402/core@alpha @kaspa-x402/client@alpha

The registry alpha tag resolves to 0.1.0-alpha.8. Pin the exact prerelease version when repeatable conformance results matter.

The public npm release includes core schema/header helpers and client helpers; the hosted gateway package is not published.

Validate Schemas And Vectors

Before calling the hosted gateway, an implementation should be able to:

1. Fetch JSON Schemas from /schemas/. 2. Validate local copies against the published $id routes. 3. Load /vectors/index.json. 4. Validate every vector in x402-http, settlement-response, voucher, channel-id, tx-v1, and negative. 5. Confirm negative vectors fail for the expected reason.

Amounts are decimal strings in sompi. KIP-9 storage mass depends on the full transaction shape rather than defining a universal dust amount. The gateway's on-chain exact output and batch deposit use a conservative 10000000 sompi reference policy; smaller values require transaction-specific mass analysis.

Discover Gateway Support

curl -fsS https://demo.kaspa-x402.org/supported

Hosted capability, subject to live availability:

No mainnet profile is advertised. If exact is absent from /supported or /exact returns 503 exact_unavailable, exact settlement is disabled or an additive deployment has no available head; use batch-settlement instead.

The 2026-07-15 alpha.8 paid canary proved hosted standard-native exact, identical replay, and cross-resource rejection. Historical alpha.7 evidence also records batch deposit/voucher reuse, stale-voucher rejection, and a stable absolute refund DAA. Transaction and channel evidence is recorded in the gateway reference.

Exact Flow

Request the protected resource:

curl -i https://demo.kaspa-x402.org/exact

Hosted result while exact settlement is disabled or an additive head is unavailable:

Enabled expected result:

Decode the PAYMENT-REQUIRED header and inspect extra.profile. standard-native is the default: build an ordinary native KAS transaction whose canonical payment output transfers exactly the advertised amount to payTo. For optional additive, the offer contains a complete reusable head challenge: head id/version, expected outpoint, amount, script public key, redeem script, covenant threshold, challenge id, and canonical output index zero. Spend that head and create the same-script successor at index zero with:

successor amount = head amount + advertised exact amount

That successor increase is the entire merchant payment; do not create a second merchant payment output. Build the signed SDK-safe JSON transaction artifact and retry with an exact-transaction payload. The hosted gateway submits that artifact through TN10 PNN/WSS and waits for accepted payment evidence before serving the response:

PAYMENT-SIGNATURE: <base64 x402 PaymentPayload>

Successful retry result:

Identical retries with the same request and payment evidence should return the cached HTTP 200. Reusing the same exact transaction for a different resource must be rejected. If an additive gateway has no available head, clients should use batch-settlement or another server.

The hosted gateway uses REST for read-side evidence and public TN10 PNN/WSS for KIP-10 exact transaction submission. Public REST submit is not used for hosted KIP-10 broadcast because it does not preserve tx-v1 computeBudget.

Batch Flow

The batch contract is unchanged from alpha.7 and remains the deployed alpha.8 batch profile.

Request:

curl -i https://demo.kaspa-x402.org/batch

Expected result:

Open a channel by funding the advertised escrow terms with at least extra.minDepositSompi, then submit a deposit-voucher payment payload. For a later request on the same channel, submit a voucher-only payload with a higher cumulative signed amount.

Successful batch retries return HTTP 200 with `PAYMENT-RESPONSE.success: true`, a commitment id in the settlement transaction field, and channel state metadata in extensions.kaspa.

Stale vouchers should receive a corrective HTTP 402 that includes current channel and voucher state.

Unsupported And Future Profiles

The hosted gateway must not accept foreign or future schemes as Kaspa payment evidence. A paid retry whose selected payment requirement uses a foreign scheme should fail before protected content is produced.

Expected public error reason:

unsupported_scheme

Clients should parse mixed accepts envelopes selectively: validate the envelope shape, keep compatible Kaspa entries, and skip foreign entries. A foreign-only challenge should fail locally as unsupported.

Reporting Interop Issues

When reporting an interoperability issue, include:

Do not post private keys, wallet seeds, or reusable unpaid payment headers.

Source: /docs/demo-implementer-guide.md