x402 Payment Protocol: HTTP-Native Micropayments

What is x402

x402 is the payment protocol at Kizuna's edge. Named as a reference to HTTP 402 Payment Required, x402 defines how AI agents discover, verify, and settle payments with service providers. It is the interface between agent SDKs and Kizuna's settlement infrastructure.

The protocol is intentionally simple: two endpoints (verify and settle), a well-defined request/response format, and signed decision envelopes that bind verify approvals to settlement execution.

Protocol Design Principles

• Two-phase commit — verify creates a reservation, settle executes it. No single endpoint moves money.
• Exactly-once semantics — each reservation can be settled exactly once. Duplicate settle calls are idempotent.
• Signed decisions — the kernel signs every approval. The facilitator validates signatures before settlement.
• Lane-agnostic interface — client code calls the same verify/settle endpoints regardless of enterprise or crypto-fast lane.
• Extension metadata — the protocol supports Kizuna-specific metadata in response headers for lane details, reservation state, and billing references.

The Verify Endpoint

A verify request includes the payment amount, lane preference, mandate or collateral reference, and agent identity. The facilitator validates inputs, resolves the lane, and forwards to the kernel.

POST /x402/verify
{
  "amount": 100000000,
  "lane": "enterprise",
  "mandate": "mandate_abc123",
  "agent": "agent_xyz789",
  "counterparty": "service_provider_id"
}

On success, the response includes a reservation ID, signed decision envelope, approved amount, and expiration timestamp. Reservations expire if not settled within the configured window.

The Settle Endpoint

A settle request references the reservation ID from a successful verify. The facilitator validates the reservation is still active and the decision envelope is authentic, then executes settlement.

POST /x402/settle
{
  "reservationId": "res_abc123",
  "envelope": "signed_decision_envelope"
}

Settlement is atomic: it either completes fully or fails entirely. Partial settlements are not supported. On success, the response includes the on-chain transaction signature and billable event ID.

Client SDK Integration

The @kamiyo/x402-client package wraps the protocol into a clean TypeScript interface:

import { KizunaClient } from '@kamiyo/x402-client'

const client = new KizunaClient({
  endpoint: 'https://x402.kamiyo.ai',
  apiKey: process.env.KAMIYO_API_KEY,
})

// Verify and settle in sequence
const approval = await client.verify({
  amount: 50_000_000,
  lane: 'crypto-fast',
  collateral: collateralPoolId,
})

const receipt = await client.settle(approval.reservationId)
console.log('Settled:', receipt.txSignature)

The SDK handles retry logic, envelope management, and error classification. For framework-specific integrations, see the integration guide.

Protocol Evolution

x402 is versioned and backwards-compatible. New features are added as optional fields and extension metadata. Breaking changes go through governance. The protocol is designed to remain stable as Kizuna expands to additional chains and settlement rails.