How x402 works

x402 is an open payment standard that adds native payment capabilities to HTTP. When a client requests access to your paid API without a valid payment, they receive an HTTP 402 "Payment Required" response with payment instructions. The client then submits payment proof, and your API delivers the content.

Think of it like a vending machine for APIs: insert payment, receive data.

The payment flow

Here's what happens when an AI agent or developer accesses your paid endpoint:

Client requests your API without payment

Your API returns 402 with payment options (price, wallet, network)

Client signs a transaction authorizing the payment

Client resubmits the request with payment proof in the header

Your API calls Kobaru to verify (or verify and settle) the payment

Kobaru confirms the payment is valid

Your API delivers the content

Key concepts

Payment requirements

When payment is required, your API returns instructions telling the client how to pay. This includes which blockchain network to use, how much to pay, and where to send the funds.

{
  "x402Version": 2,
  "error": "Payment required",
  "resource": {
    "url": "https://api.yourcompany.com/premium-data",
    "description": "Premium data access",
    "mimeType": "application/json"
  },
  "accepts": [{
    "scheme": "exact",
    "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
    "amount": "1000",
    "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "payTo": "YourSolanaWalletAddress...",
    "maxTimeoutSeconds": 60
  }]
}

Field	What it means
`scheme`	Payment method. `exact` means direct transfer of the specified amount.
`network`	Blockchain network in CAIP-2 format. `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` is Solana mainnet.
`amount`	Payment amount in atomic units. `1000` = 0.001 USDC (USDC has 6 decimals).
`asset`	Token address. The example shows the USDC token on Solana.
`payTo`	Your wallet address where you receive funds.
`maxTimeoutSeconds`	How long the client has to complete payment.

Payment proof

After the client signs a transaction, they include the payment proof in their request. The proof contains the signed transaction data that authorizes the transfer.

The PAYMENT-SIGNATURE header contains a base64-encoded JSON payload:

{
  "x402Version": 2,
  "accepted": {
    "scheme": "exact",
    "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
    "amount": "1000",
    "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "payTo": "YourSolanaWalletAddress..."
  },
  "payload": {
    "transaction": "BASE64_ENCODED_SIGNED_TRANSACTION..."
  }
}

You don't need to parse this yourself. Kobaru handles verification for you.

Verification and settlement

Kobaru provides two endpoints for processing payments:

Endpoint	Purpose	When to use
`POST /v1/verify`	Validates the payment without executing it on-chain	Pre-authorization checks, when you want to settle later
`POST /v1/settle`	Validates and executes the payment on-chain	When you want immediate settlement

Verify response (valid payment):

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

Settle response (successful settlement):

{
  "success": true,
  "transaction": "5xK9Zr7vB2mN...",
  "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
  "payer": "ClientWalletAddress..."
}

What you need to know

As a merchant integrating with Kobaru, here's what matters:

You set the price

Define pricing per endpoint or per service. Charge

0.001 p erre q u es t,

0.10 for an hour of access, or any amount that makes sense for your API. Prices are set in USDC atomic units (1 USDC = 1,000,000 atomic units).

Kobaru handles the crypto

You don't need to understand Solana transactions or blockchain mechanics. Kobaru:

Verifies transaction signatures

Confirms the client has sufficient funds

Validates the payment amount matches your requirements

Settles the transaction on-chain

Handles idempotency and replay protection

Clients pay in USDC

USDC is a stablecoin pegged 1:1 to the US dollar. This means:

No cryptocurrency price volatility

Predictable revenue in dollar terms

Easy accounting and pricing

You receive funds directly

Payments go directly to your Solana wallet. There's no intermediary holding your funds. You have immediate access to settled payments.

Next steps

Now that you understand how x402 works, choose your integration path:

Quick start guide - Get your first paid request in 5 minutes

Transparent proxy - Zero-code integration

Standard SDK integration - Full control with middleware

Direct API integration - Build custom implementations

Networks and assets - Supported blockchains and tokens

The payment flow#

Key concepts#

Payment requirements#

Payment proof#

Verification and settlement#

What you need to know#

You set the price#

Kobaru handles the crypto#

Clients pay in USDC#

You receive funds directly#

Next steps#