| Header | Value | Description |
|---|---|---|
Authorization | Bearer <API_KEY> | Your Kobaru API key from the console |
Content-Type | application/json | Required for all POST requests |
kbr_{env}_{random} where env is live or test.PAYMENT-REQUIRED header.PAYMENT-REQUIRED header contains a base64-encoded JSON object with payment options.{
"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
}
],
"extensions": {
"usage": {
"model": "pay_per_request",
"limit": 1,
"unit": "request"
}
}
}| Field | Type | Required | Description |
|---|---|---|---|
x402Version | integer | Yes | Must be 2 for x402 v2 protocol |
error | string | Yes | Human-readable error message |
resource | object | No | Information about the requested resource |
resource.url | string | Yes | Full URL of the requested resource |
resource.description | string | No | Human-readable description of the resource |
resource.mimeType | string | No | MIME type of the resource |
accepts | array | Yes | Array of accepted payment methods |
extensions | object | No | Protocol extensions (e.g., usage tracking) |
| Field | Type | Required | Description |
|---|---|---|---|
scheme | string | Yes | Payment scheme. Currently only exact is supported |
network | string | Yes | CAIP-2 network identifier (e.g., solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp) |
amount | string | Yes | Payment amount in atomic units (e.g., 1000 = 0.001 USDC) |
asset | string | Yes | Token mint address for Solana (USDC: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v) |
payTo | string | Yes | Your wallet address to receive payment |
maxTimeoutSeconds | integer | No | Maximum time for payment completion. Default: 60 |
| Network | CAIP-2 Identifier | Environment |
|---|---|---|
| Solana Mainnet | solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp | Production |
| Solana Devnet | solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1 | Testing |
| Human Amount | USDC Atomic Units | Calculation |
|---|---|---|
| $0.001 | 1000 | 0.001 x 10^6 |
| $0.01 | 10000 | 0.01 x 10^6 |
| $0.10 | 100000 | 0.1 x 10^6 |
| $1.00 | 1000000 | 1 x 10^6 |
PAYMENT-SIGNATURE header as a base64-encoded JSON object.{
"x402Version": 2,
"resource": {
"url": "https://api.yourcompany.com/premium-data",
"description": "Premium data access",
"mimeType": "application/json"
},
"accepted": {
"scheme": "exact",
"network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
"amount": "1000",
"asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"payTo": "YourSolanaWalletAddress...",
"maxTimeoutSeconds": 60
},
"payload": {
"transaction": "BASE64_ENCODED_SOLANA_TRANSACTION..."
}
}| Field | Type | Required | Description |
|---|---|---|---|
x402Version | integer | Yes | Must be 2 |
resource | object | No | Resource being accessed (echoed from requirements) |
accepted | object | No | The payment method the client accepted |
payload | object | Yes | Scheme-specific payment data |
payload.transaction | string | Yes | Base64-encoded Solana transaction (for Solana exact scheme) |
extensions | object | No | Protocol extensions |
| Endpoint | Purpose | When to Use |
|---|---|---|
POST /verify | Validates payment without executing on-chain | Pre-authorization, checking transaction validity |
POST /settle | Validates AND executes payment on-chain | Capturing funds when ready to deliver content |
{
"paymentPayload": {
"x402Version": 2,
"resource": {
"url": "https://api.yourcompany.com/premium-data",
"description": "Premium data access",
"mimeType": "application/json"
},
"accepted": {
"scheme": "exact",
"network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
"amount": "1000",
"asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"payTo": "YourSolanaWalletAddress...",
"maxTimeoutSeconds": 60
},
"payload": {
"transaction": "BASE64_ENCODED_SOLANA_TRANSACTION..."
}
},
"paymentRequirements": {
"scheme": "exact",
"network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
"amount": "1000",
"asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"payTo": "YourSolanaWalletAddress...",
"maxTimeoutSeconds": 60
}
}| Field | Type | Required | Description |
|---|---|---|---|
paymentPayload | object | Yes | The payment authorization from the client (decoded from PAYMENT-SIGNATURE header) |
paymentRequirements | object | Yes | The payment requirements you originally specified |
| Field | Type | Required | Description |
|---|---|---|---|
scheme | string | Yes | Must be exact |
network | string | Yes | CAIP-2 network identifier |
amount | string | Yes | Payment amount in atomic units |
asset | string | Yes | Token mint address |
payTo | string | Yes | Your wallet address |
maxTimeoutSeconds | integer | No | Maximum timeout in seconds (default: 60) |
{
"isValid": true,
"payer": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
}| Field | Type | Description |
|---|---|---|
isValid | boolean | true if payment is valid |
payer | string | Wallet address of the payer |
{
"isValid": false,
"invalidReason": "invalid_exact_solana_payload_authorization_value",
"payer": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
}| Field | Type | Description |
|---|---|---|
isValid | boolean | false if payment is invalid |
invalidReason | string | Error code explaining why the payment is invalid |
payer | string | Wallet address of the payer (if available) |
{
"isValid": false,
"invalidReason": "simulation_failed",
"simulationDetails": {
"error": "Instruction 2: InsufficientFunds",
"errorCode": "InsufficientFunds",
"logs": [
"Program TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA invoke [1]",
"Program log: Error: insufficient lamports",
"Program TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA consumed 3452 of 200000 compute units"
]
}
}| Field | Type | Description |
|---|---|---|
simulationDetails | object | Present only when invalidReason is simulation_failed |
simulationDetails.error | string | Human-readable error message |
simulationDetails.errorCode | string | Solana error code |
simulationDetails.logs | array | Last 5 program log lines for debugging |
{
"success": true,
"transaction": "5wHu1qwD7q4XJJnYZcPcqL8mPwRfzAQCHQ2X4KxEaJhbNgVbPjKtqZY8jW3xLqNpMdR9vS2KuHfA8yXtEcJgWmNr",
"network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
"payer": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM"
}| Field | Type | Description |
|---|---|---|
success | boolean | true if settlement succeeded |
transaction | string | Solana transaction signature (can be viewed on Solana Explorer) |
network | string | CAIP-2 network identifier where the transaction was executed |
payer | string | Wallet address of the payer |
{
"success": false,
"errorReason": "simulation_failed"
}| Field | Type | Description |
|---|---|---|
success | boolean | false if settlement failed |
errorReason | string | Error code explaining why settlement failed |
PAYMENT-RESPONSE header.| Error Code | HTTP Status | Description | Troubleshooting |
|---|---|---|---|
invalid_x402_version | 400 | x402Version is not 2 | Ensure x402Version: 2 in paymentPayload |
invalid_payload | 400 | Missing, invalid, or malformed payload | Check JSON structure matches the schema |
invalid_payment_requirements | 400 | Missing or invalid requirements | Verify all required fields are present |
invalid_network | 400 | Invalid or unsupported network | Use valid CAIP-2 format (e.g., solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp) |
unsupported_scheme | 400 | Scheme not supported | Only exact scheme is currently supported |
capability_not_enabled | 400 | Client lacks this capability | Enable the network/scheme/asset in Kobaru console |
duplicate_request | 409 | The same payment is being processed right now | Wait for the Retry-After seconds (5), then retry |
settlement_pending | 409 | A settlement's outcome isn't known yet (/settle, or /verify while a settle of the payment is unresolved); transaction when known | Wait for the Retry-After seconds (30), then retry /settle with the same payload. Don't deliver or ask for a new payment until the result is final. Kobaru also resolves it in the background, so a later /settle or /verify returns the outcome even without a retry |
claim_unavailable | 503 | The payment couldn't be claimed (database unavailable); nothing was recorded or broadcast | Wait for the Retry-After seconds (5), then retry |
rpc_unavailable | 503 | EVM: the network's RPC couldn't be reached while reading the token contract; nothing was broadcast | Wait for the Retry-After seconds (5), then retry |
bite_unavailable | 503 | SKALE with BITE: the encryption service is unreachable; nothing was broadcast | Wait for the Retry-After seconds (10), then retry |
idempotency_conflict | 409 | The same payment already has a binding outcome with a different payTo or amount | Don't retry. Use the original requirements or a new payment |
payment_already_settled | 400 | /verify only. The payment was already settled | Treat the payment as used. Don't deliver again for a single-use payment |
payment_settlement_failed | 400 | /verify only. The payment's settlement failed for good: reverted on chain, expired without landing, or the payer canceled the authorization | Don't deliver; a new payment is needed |
evm_authorization_canceled | 400 | /settle. The payer canceled the EVM authorization on chain before it was used, found while resolving a pending settlement. Final | Don't deliver; a new payment is needed |
payment_proof_mismatch | 400 | This signature isn't the one the payment was verified, settled or first broadcast with | Use the original payload |
unexpected_verify_error | 500 | Server error during verification | Retry the request |
unexpected_settle_error | 500 | Server error during settlement | Retry the request |
| Error Code | HTTP Status | Description | Troubleshooting |
|---|---|---|---|
invalid_exact_solana_payload_authorization_value | 400 | Amount does not match requirements | Ensure transaction transfers the exact amount |
invalid_exact_solana_payload_recipient_mismatch | 400 | Wrong destination address | Verify payTo address matches |
invalid_asset_mismatch | 400 | Wrong token mint | Use correct token address (USDC mint) |
invalid_fee_payer | 400 | Fee payer is not the facilitator | Kobaru must be the fee payer |
invalid_transaction_format | 400 | Cannot decode transaction | Ensure transaction is valid base64 |
missing_compute_budget_limit | 400 | Missing SetComputeUnitLimit instruction | Add compute budget instructions |
missing_compute_budget_price | 400 | Missing SetComputeUnitPrice instruction | Add compute budget instructions |
priority_fee_exceeds_limit | 400 | Priority fee too high | Reduce priority fee below limit |
invalid_instruction_count_topology | 400 | Wrong instruction order | Follow required instruction order |
facilitator_cannot_be_payer | 400 | Facilitator wallet is the source | Use a different source wallet |
simulation_failed | 400 | Transaction simulation failed | Check payer has sufficient balance |
submission_failed | 400 | Transaction broadcast failed | Retry the settlement |
accepted field in the payment payload matches what you required:from and nonce, or the Solana transaction message), so resending the same payment never charges twice. Retry like this:duplicate_request or settlement_pending (409): wait for the Retry-After header (5s and 30s), then resend.idempotency_conflict (409): don't retry. The payment is bound to the requirements it was first sent with; the payer must sign a new authorization.replayed: true on a settle success: the payment was already settled by an earlier request (same transaction, no new transfer). Treat it as already delivered, not as a new payment, and never as a reason to grant access to whoever sent it: anyone who saw the proof can replay it. The header Idempotent-Replayed: true carries the same signal.| Status Code | Meaning | When Returned |
|---|---|---|
| 200 | OK | Payment verified/settled successfully |
| 400 | Bad Request | Invalid payment or malformed request |
| 402 | Payment Required | No payment provided or payment invalid |
| 500 | Internal Server Error | Unexpected server error |