Facilitator Profile

Status: draft

Kaspa x402 supports facilitators for exact and batch-settlement, but must not require a third-party hosted facilitator.

Modes

Direct Mode

The resource server verifies payment payloads and settles itself.

For exact, this means selecting the advertised kaspa-exact-v2 profile, verifying its exact-transaction artifact with trusted UTXO and consensus facts, broadcasting it if needed, and observing it at the required finality.

For batch-settlement, this means verifying vouchers, tracking channel state, and building claim/refund transactions.

Self-Hosted Facilitator Mode

The resource server or service operator exposes:

GET  /supported
POST /verify
POST /settle

GET /supported returns the x402 v2 supported response. Kaspa-specific binding, asset, and mode metadata belongs in each kind's extra object:

{
  "kinds": [
    {
      "x402Version": 2,
      "scheme": "exact",
      "network": "kaspa:testnet-10",
      "extra": {
        "asset": "KAS",
        "binding": "kaspa-exact-v2",
        "defaultProfile": "standard-native",
        "profiles": ["standard-native", "additive"],
        "modes": ["verify", "settle"]
      }
    },
    {
      "x402Version": 2,
      "scheme": "batch-settlement",
      "network": "kaspa:testnet-10",
      "extra": {
        "asset": "KAS",
        "binding": "kaspa-escrow-v1",
        "modes": ["verify", "settle", "claim"]
      }
    }
  ],
  "extensions": [],
  "signers": {}
}

The extra.modes and exact extra.profiles lists are authoritative for that facilitator instance. standard-native is the default exact profile. A facilitator MUST omit additive unless its canonical KIP-10 verifier, durable head pool, and reconciliation implementation are configured and healthy. Valid mode values are verify, settle, claim, and refund. A facilitator must not execute a mode for a (scheme, network) pair unless the matching kind advertises it. Facilitators should omit kinds or modes when the local verifier, settlement builder, signer, or state backend required for that action is not configured.

POST /verify validates a payment payload without releasing the protected resource. The request follows the x402 v2 facilitator shape:

{
  "x402Version": 2,
  "paymentPayload": {},
  "paymentRequirements": {}
}

Kaspa facilitators may also accept resource and requestHash fields. requestHash binds verification and settlement to the resource server's operation fingerprint. It is mandatory for exact, must match the mandatory signed request authorization in the payment payload, and cannot be inferred or removed. For batch vouchers a facilitator may still derive a deterministic local fingerprint when an explicit hash is absent. Servers that need portable idempotency across direct and facilitator mode should send requestHash explicitly for every scheme.

Successful /verify returns x402 v2 VerifyResponse:

{
  "isValid": true,
  "payer": "kaspatest:..."
}

Invalid verification returns:

{
  "isValid": false,
  "invalidReason": "invalid_payload"
}

POST /settle applies the scheme-specific success step:

• exact: verify the signed transaction artifact for the selected profile, consume its replay evidence before protected work, broadcast it if needed, observe the resulting transaction at the required finality, and return the independently recomputed transaction id. For additive, verification also atomically claims the expected head and settlement advances the durable head state through its recoverable stages;
• batch-settlement: for voucher-only requests, store the voucher commitment using settlement-time paymentRequirements.amount as the actual charge while the signed voucher ceiling remains bound to paymentPayload.accepted.amount; for deposit-voucher, broadcast if needed, wait until the deposit or top-up transaction is accepted by the selected Kaspa network, and store the voucher commitment before returning success; for claim operations, broadcast if needed and wait until the relevant transaction is accepted by the selected Kaspa network before returning success or mutating active channel state.

For batch-settlement, /verify responses should include extra.channelState and /settle responses should include extensions.kaspa.channelState whenever the facilitator reads or changes channel state.

Refund transaction construction is implementation-specific in v0.1. A facilitator must not advertise refund support in /supported unless it has an explicit refund settler and verifies client refund authorization before broadcasting or reporting success.

Third-Party Facilitator Mode

A third-party facilitator may verify payment state, relay transactions, index channels, or expose discovery. Any delegated authority must be explicit in PaymentRequirements.extra and discoverable through /supported.

Hardcoded facilitator keys, URLs, or service identities are out of scope for the standard.

Third-party facilitators must authenticate resource servers before performing server-owned operations such as settlement, claim, refund relay, or receipt signing. A facilitator can relay and index state, but voucher correctness must remain independently verifiable from channel config, active outpoint, voucher digest, and settlement responses.

Source: /spec/facilitator-profile.md