io.github.Kali123411/kx402

kx402 — Kaspa x402 agent payer

An agent-centric payer for x402 services settled on Kaspa L1. One package, three surfaces over the same proven payment core:

• SDK — import { openWallet, payExact } from "kx402" to pay x402 offers from your own code.
• CLI — kx402 offer|pay|balance|addr for humans and scripts.
• MCP server — drop kx402-mcp into an agent (Claude, etc.) so it can pay Kaspa x402 services as a tool.

It speaks the x402 v2 exact / standard-native flow against the @kaspa-x402 binding — conforming to the standard wire format, not extending it. It's the demand side of the Kaspa·402 marketplace.

⚠️ Alpha, and pay spends real funds. Use testnet-10 first. Keep funding keys in 0600 files, never in git.

What it solves

The internet's payment plumbing assumes a person is buying: you sign up, get an API key, put a card on file, click "approve." An AI agent can't do any of that — and you don't want to hand it your credit card. So agents can reason and act, but the moment a task needs a paid tool (data, compute, a model, an API), a human has to set up the billing first.

kx402 closes that gap. It gives an agent a wallet it can actually operate, and lets it pay per use on its own:

• No account, no API key, no signup. The agent pays the exact price for each call on the spot; it needs no relationship with the service.
• Micropayments cards can't do. Credit cards have a ~30¢ floor. Settling in KAS on Kaspa makes fractions-of-a-cent, per-call payments practical.
• A wallet built for software, not fingers. It builds, signs, sends, and proves a payment programmatically in about a second, with no human in the loop.
• Guardrails so it can't run wild. Every payment is capped at the offer's own price, paid only to that service, up to a limit you set — autonomy without the risk of overspending or paying the wrong party.

Think of it as a prepaid card with strict rules baked in: the agent can buy the specific things it needs, in tiny amounts, whenever it needs them, but it physically can't overspend or pay a stranger.

Install

npm install -g kx402      # or: npm install kx402  (for SDK use)
npm run fetch-sdk         # downloads the rusty-kaspa v2.0.0 WASM SDK into ./vendor

Kaspa signing needs the official rusty-kaspa v2.0.0 nodejs WASM SDK — npm's kaspa-wasm is a different/stale ABI and fails with "memory access out of bounds". npm run fetch-sdk grabs the right one; then point KASPA_X402_KASPA_WASM_MODULE at the printed kaspa.js path.

Configure

Copy .env.example to .env and fill it in (or pass any of these as flags / env vars):

Variable	Meaning
KASPA_X402_KASPA_WASM_MODULE	Path to the v2.0.0 nodejs WASM SDK kaspa.js
KASPA_X402_FUNDING_WALLET	wallet-key:/path/to/wallet.key or a raw 64-hex key
KASPA_X402_NETWORK	kaspa:mainnet or kaspa:testnet-10 (default)
KASPA_X402_RPC_URL	Optional; a public PNN node is resolved automatically if unset

CLI

kx402 addr    --config-file .env                 # show the wallet address (fund it first)
kx402 balance --config-file .env                 # spendable KAS
kx402 offer  https://host/exact --config-file .env   # inspect a 402 offer (no payment)
kx402 pay    https://host/exact --prompt "hi" --config-file .env   # pay and print the result

Input rides in the query on an exact GET — use --text / --prompt / --model / --input as the resource expects. Safety flags: --max <sompi> caps the spend; --dry builds the signed tx without broadcasting.

SDK

import { openWallet, payExact, resolveWalletConfig } from "kx402";

const wallet = await openWallet(resolveWalletConfig());   // reads env / .env
const r = await payExact(wallet, "https://host/exact?prompt=hello");
console.log(r.status, r.body, r.settlement);
await wallet.close();

Every payment is bounded by a fundingPolicy derived from the offer itself — it will only pay the offer's payTo, at its profile, up to your max.

MCP server

Run kx402 mcp (or the kx402-mcp bin) — a stdio server exposing kaspa_x402_address, kaspa_x402_balance, kaspa_x402_offer, and kaspa_x402_pay (which spends real funds, bounded by max_sompi). Example client config:

{
  "mcpServers": {
    "kx402": {
      "command": "npx",
      "args": ["-y", "kx402", "mcp"],
      "env": {
        "KASPA_X402_KASPA_WASM_MODULE": "/abs/path/vendor/kaspa-wasm32-sdk/nodejs/kaspa/kaspa.js",
        "KASPA_X402_FUNDING_WALLET": "wallet-key:/abs/path/wallet.key",
        "KASPA_X402_NETWORK": "kaspa:testnet-10"
      }
    }
  }
}

How it settles

On mainnet, kx402 uses non-hosted settlement: it broadcasts the signed tx itself, waits for acceptance on the same REST indexer the gateway verifies against, then presents the PAYMENT-SIGNATURE — so the gateway settles by observing the accepted tx and never needs to broadcast. All within the standard x402 v2 lifecycle.

Related

• @kaspa-x402 — the Kaspa x402 binding this builds on.
• kaspa-402.org — the marketplace of x402-payable services on Kaspa.

License

MIT