Kaspa x402

Kaspa x402 is a proposed native Kaspa binding for x402, the HTTP 402 payment protocol. It lets HTTP APIs and MCP tools charge native KAS per request, and lets servers verify and settle those payments directly against the Kaspa network.

Security and use

This SDK supports mainnet configuration. It has undergone extensive AI-assisted security review, and all four payment profiles were tested on funded Testnet. It has not received an independent third-party security audit. Undiscovered bugs may result in loss of funds. Provided as is, without warranty. Review and testing details.

Status

• Standard and SDK: 1.0.1 released, covering all four native profiles. The four public packages are available on npm's latest channel. See the 1.0.1 release notes.
• SDK supports kaspa:testnet-10 and explicit opt-in kaspa:mainnet. Testnet-10 is the default. See production operating requirements.
• Hosted demo: demo.kaspa-x402.org runs 1.0.1 on Testnet only. Try a payment or read the gateway guide.
• Standards: the kaspa:* identifiers remain proposed x402/CAIP names. This release does not claim upstream registry adoption.

What is x402

x402 is an open protocol that turns the HTTP 402 Payment Required status code into a machine-payable flow: a server answers an unpaid request with a 402 carrying a machine-readable offer, the client retries with a signed payment payload, and the server verifies the payment, settles it, and serves the response. The same primitives work over HTTP headers and MCP _meta fields, so paid APIs and tools are usable by autonomous agents. See x402.org.

What is Kaspa

Kaspa is a proof-of-work layer 1 whose blockDAG consensus produces blocks at sub-second cadence with native UTXO semantics. See kaspa.org.

Why a native Kaspa binding

The claims below are engineering rationale, each specified or backed by testnet evidence. None of them is a mainnet claim.

• Settlement latency close to request latency. Paying per HTTP request only works when payment confirmation is not the slow path. Kaspa's block cadence makes one-shot native payments practical at request time; the live testnet report records executed end-to-end flows.
• Small per-request prices. Amounts are decimal strings in sompi (1 KAS = 100,000,000 sompi). KIP-9 storage mass depends on the complete transaction shape; Kaspa does not define a universal 0.1 KAS consensus dust floor. The reference runtime applies a conservative 10,000,000 sompi output policy. Batch-settlement vouchers can price individual requests below that application policy.
• Direct verification, no facilitator lock-in. Kaspa is UTXO-native, so a server can verify and settle against a node it trusts: payment identity is bound to transaction ids, outpoints, and script-public-key material rather than to a hosted intermediary. A self-hosted facilitator profile exists for x402 /supported, /verify, /settle compatibility, but it is optional.
• Escrow channels for repeated requests. For clients making many fixed-price calls, batch settlement creates one singleton KIP-20 genesis, signs lifetime cumulative ceilings off-chain, supports repeated partial claims and same-lineage top-ups, and ends with a timed refund. The stable covenant ID and A/S/T accounting survive successor rotation and runtime restart.

Payment schemes

The binding ships two schemes with different settlement shapes.

exact — fixed-price one-shot native transfer under kaspa-exact-v2. standard-native is the default ordinary KAS transfer. The optional additive profile consumes and recreates a reusable merchant KIP-10 head; the successor increase is the sole exact payment, with no second merchant output and no per-offer inventory reservation.

The SDK also includes the optional hash-chain-additive exact profile with OTP-style one-time signing grants. The payer independently broadcasts a payment that increases the head and advances its hash guard. Try it in the browser demo on Testnet.

{
  "scheme": "exact",
  "network": "kaspa:<network>",
  "asset": "KAS",
  "amount": "<sompi>",
  "extra": {
    "binding": "kaspa-exact-v2",
    "profile": "standard-native",
    "paymentFlow": "upfront"
  }
}

batch-settlement — repeated requests with a payer-approved fixed charge per invocation against a KIP-20 escrow lane. Its lifecycle is singleton genesis → repeated partial claims → top-up → refund. The current outpoint and V rotate while the stable covenant ID and lifetime A/S/T remain recoverable; R is the advertised minimum successor reserve. Spec: kaspa-batch-settlement-v3.

{
  "scheme": "batch-settlement",
  "network": "kaspa:<network>",
  "asset": "KAS",
  "amount": "<fixed per-request sompi>",
  "extra": {
    "binding": "kaspa-escrow-v3",
    "templateId": "kaspa-x402-escrow-v5"
  }
}

Start here

• Implementing: read the SDK integration guide, the core binding, the relevant exact or batch-settlement scheme, and the conformance vectors.
• Testing: use the hosted gateway reference and the browser demo.
• Reviewing: start with the threat model, live testnet report, and mainnet readiness gates.

Packages

Install the stable SDK using the exact versions below, or npm latest.

npm install @kaspa-x402/core@1.0.1 @kaspa-x402/covenant@1.0.1 @kaspa-x402/client@1.0.1 @kaspa-x402/server@1.0.1

Machine-readable: packages.json, site-manifest.json.