Integrating with Kizuna: Developer Quick Start

Quick Start

This guide walks through integrating Kizuna into your AI agent application. By the end, your agent will be able to verify payment approvals and settle transactions through the x402 facilitator.

Install the SDK

npm install @kamiyo/x402-client

The @kamiyo/x402-client package is the primary integration point. It wraps the x402 verify/settle endpoints with TypeScript types, retry logic, and error classification.

Initialize the Client

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

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

The client handles authentication, request signing, and connection management. Pass your API key via environment variable — never hardcode it.

Verify a Payment

Before your agent can make a payment, it must verify the request through Kizuna:

const approval = await client.verify({
  amount: 100_000_000,        // lamports
  lane: 'enterprise',          // or 'crypto-fast'
  mandate: 'mandate_abc123',   // enterprise: mandate ID
  // collateral: 'pool_xyz',   // crypto-fast: pool ID
})

if (approval.status === 'approved') {
  console.log('Reservation:', approval.reservationId)
  console.log('Expires:', approval.expiresAt)
} else {
  console.log('Denied:', approval.reason)
}

The verify response includes a reservation ID (for approved requests) or a denial reason. Reservations expire — settle them promptly.

Settle the Payment

const receipt = await client.settle(approval.reservationId)

console.log('Transaction:', receipt.txSignature)
console.log('Billable event:', receipt.eventId)

Settlement is atomic — it either completes fully or fails entirely. The receipt includes the on-chain transaction signature and billable event ID for your records.

Framework Integrations

Kizuna provides framework-specific packages for popular AI agent toolkits:

Error Handling

The SDK classifies errors into actionable categories:

• InsufficientFunds — mandate balance or collateral too low. Replenish and retry.
• PolicyDenied — kernel policy check failed. Check mandate limits and counterparty allowlists.
• ReservationExpired — too long between verify and settle. Re-verify and settle promptly.
• NetworkError — transient connectivity issue. SDK retries automatically with backoff.
• InvalidRequest — malformed request. Check parameter types and required fields.

Next Steps

• Enterprise Lane guide — Configure mandates and prefunding
• Crypto-Fast Lane guide — Set up collateral and pool management
• Financial Safety — Understand safety controls and kill switches
• x402 Protocol — Deep dive into the protocol specification
• Full Documentation — Complete API reference and guides