1. Core Concepts
Kobaru
  • Kobaru.io Gateway API
    • Introduction
      • What is Kobaru?
      • Quick start
      • How x402 works
    • Integration
      • Standard x402 SDK
      • Advanced SDK
      • Transparent proxy integration
      • Direct API integration
    • Core Concepts
      • Available Chains and Assets
      • Payment schemes
      • Security
      • Usage models
      • Access tiers
      • Idempotency
    • Guides
      • Pricing your API
      • Going to Production
      • Testing with devnet
      • Bazaar discovery
      • BITE encryption for SKALE
    • API Reference
      • Error Handling
      • Get Supported Payment Kinds
      • Verify Payment Authorization
      • Settle Payment
    • Discovery
      • List Discovery Resources
    • Transparent Proxy
      • Overview - Transparent Proxy
      • Upstream authentication
      • Troubleshooting
      • Constraints and security
      • Capabilities and routes
      • Domain verification
      • Service setup
    • Effortless MCP
      • Kobaru MCP Overview
      • Wallets
      • CLI reference
      • Setup Template
    • Schemas
      • SupportedResponse
      • ErrorResponse
      • UnauthorizedResponse
      • RateLimitResponse
      • VerifySuccessResponse
      • VerifyErrorResponse
      • SettleSuccessResponse
      • SettleErrorResponse
      • DiscoveryResourceItem
      • ListDiscoveryResourcesResponse
  1. Core Concepts

Security

Kobaru implements multiple layers of security to protect your payments and prevent abuse. This page explains the security mechanisms and best practices.

API key security#

API keys authenticate your requests to Kobaru's gateway endpoints.

Key format#

kbr_{env}_{random}
ComponentDescription
kbrKobaru prefix
envEnvironment (live or test)
random40 character base62 string (256 bits of entropy)
Example: kbr_live_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW3xY5zA

Storage and validation#

Keys are never stored in plaintext - only SHA-256 hashes
Validation uses constant-time comparison to prevent timing attacks
Keys are generated with cryptographically secure randomness

Best practices#

1.
Never commit keys to source control - Use environment variables
2.
Rotate keys periodically - Create new keys and revoke old ones
3.
Use separate keys for test and production - kbr_test_* vs kbr_live_*
4.
Limit key scope - Create service-specific keys when possible
5.
Monitor key usage - Check last-used timestamps in the console

Transaction verification#

Kobaru validates every payment transaction before settlement.

Solana validation checks#

CheckWhat it prevents
Fee payer validationSpoofed fee payer addresses
Amount validationUnderpayment attacks
Recipient validationPayment to wrong address
Instruction topologyMalformed transactions
Priority fee limitsGas exhaustion attacks
Transaction simulationFailed transactions

Simulation before settlement#

Every transaction is simulated on-chain before signing. This ensures:
Payer has sufficient balance
Token account exists
Transaction will succeed
If simulation fails, the transaction is rejected without consuming gas.

Idempotency and replay protection#

Kobaru processes each payment at most once, no matter how many times you send it. For how this works end to end, what to do with each response and how it compares to key-based idempotency, see Idempotency.

The problem#

In distributed systems, the same payment request might arrive multiple times due to:
Network retries
Client bugs
Intentional replay attacks

A payment's identity is its on-chain authorization#

Kobaru identifies a payment by what the chain itself accepts only once, not by the exact bytes you send:
NetworkPayment identity
EVM (EIP-3009)Token, authorization.from and authorization.nonce
SolanaThe transaction message (signatures excluded)
Re-encoding or altering a signature doesn't create a new payment. Other payload shapes fall back to the exact payload together with the payment requirements.

Safe retries#

You can resend the same /verify or /settle request after a timeout or network error:
SituationWhat you get
The first request finishedThe stored result (same signature only), with "replayed": true and the header Idempotent-Replayed: true
The first request is still runningduplicate_request (409) with Retry-After: 5
A settle's outcome isn't known yet (a retry checks the chain first; Kobaru also resolves it in the background)settlement_pending (409) with Retry-After: 30
/verify of a payment that was already settledpayment_already_settled (400)
The payment couldn't be claimed (temporary database problem)claim_unavailable (503) with Retry-After: 5
A retry with a different signature than the one the payment was settled or first broadcast withpayment_proof_mismatch (400), nothing recorded
A settle retry can't pay twice. An EIP-3009 authorization is single-use on-chain, and Solana rejects a signed transaction it has already processed.

Replays are marked#

A replayed /settle success carries the same transaction as the original and no new on-chain transfer happened. Treat it as a payment you already delivered for, not as a new payment. Fresh results never carry replayed.
Don't grant access on replayed: true alone. Once a payment is broadcast, its proof works like a bearer token: anyone who saw it (in a request header, a log, or the transaction on chain) can send it again and get the same stored success. A replay proves that the payment happened, not that the caller in front of you made it or hasn't been served. Grant access only through your own record of the payment: the order, session or account it was first settled for. A replay for a payment you have already delivered gets nothing new.

Conflicts#

The same payment is bound to the requirements it was first presented with (network, scheme, asset, payTo and amount). Presenting it again with different requirements returns idempotency_conflict (409) without touching the chain. Retrying can't succeed: send the original requirements, or have the payer sign a new authorization.
See Errors for the full list of reasons and how to handle them.

TOCTOU prevention#

Time-of-check to time-of-use (TOCTOU) attacks occur when state changes between validation and action.
The attack:
1.
Attacker submits payment A
2.
System checks: no duplicate found
3.
Attacker submits payment A again (concurrent)
4.
System checks: no duplicate found
5.
Both payments succeed (double charge!)
Kobaru's defense:
Kobaru records the claim on a payment and checks for earlier attempts in one database transaction that locks the payment's record. A concurrent request for the same payment waits for that lock, then sees the first claim and gets duplicate_request. Only one request ever reaches the chain, and it does so only after the claim is committed.

Server-side payment requirements#

When using the proxy, payment requirements (amount, asset, recipient wallet) are always determined server-side from your route configuration in the database. The proxy never trusts client-provided values.
This means:
Clients cannot manipulate the payment amount
Clients cannot redirect payments to a different wallet
The facilitator verifies client payments against your configured requirements, not what the client claims
This is enforced automatically — no action needed from merchants.

Rate limiting#

Abuse protection runs at the network layer, in Kobaru's firewall, before requests reach the gateway. /verify and /settle also require valid on-chain cryptographic proofs, which make spam expensive.
If you receive a 429 Too Many Requests response, it comes from the firewall. Wait for the Retry-After interval before you retry.

Network security#

Edge deployment#

Kobaru runs on a global edge network, providing:
Global edge distribution
DDoS protection
TLS encryption everywhere
No single point of failure

Request validation#

All requests are validated:
Body size limit: 64KB max
Content-Type validation: JSON only
Schema validation: every input is checked against a strict schema

Proxy mode protections#

The transparent proxy only forwards requests to destinations that pass its validation:
HTTPS only. Every other protocol is blocked.
Hostname and domain validation. Private, internal and restricted destinations are rejected, including Kobaru's own domains.
Verified domains. The proxy only forwards to domains you've verified. See Domain verification.
A request to a destination that fails validation is blocked before any network activity, and the client gets a generic error.

Best practices for merchants#

1. Validate payment responses#

Always check the response from /verify or /settle:

2. Use HTTPS everywhere#

All communication must use HTTPS - this is enforced at multiple levels:

For API requests#

Never transmit API keys or payment data over unencrypted HTTP connections. Always use:
https://gateway.kobaru.io/verify
https://gateway.kobaru.io/settle

For backend APIs (Proxy mode)#

If you're using Kobaru's transparent proxy, your backend API must be accessible via HTTPS. HTTP endpoints are blocked for security reasons.
Enforcement:
✅ HTTP URLs are rejected when you save them
✅ HTTP requests are blocked at runtime
❌ http://api.example.com - Rejected
✅ https://api.example.com - Allowed
For local development:
Use an HTTPS tunnel, such as ngrok:
This provides a public HTTPS endpoint that proxies to your local server.

3. Implement webhook signature verification#

When we add webhooks, always verify signatures before processing.

4. Monitor for anomalies#

Watch for:
Unusual payment volumes
High failure rates
Requests from unexpected locations

5. Keep dependencies updated#

Update your SDK and dependencies regularly to receive security patches.

Reporting security issues#

If you discover a security vulnerability, please report it responsibly:
Email: security@kobaru.io
Do not disclose publicly until we've addressed the issue
We appreciate responsible disclosure and will acknowledge your contribution

Related documentation#

API keys - Creating and managing keys
Idempotency - Safe retries, payment identity and guarantees
Error codes - Understanding error responses
Production guide - Security checklist for go-live
Modified at 2026-11-12 03:41:54
Previous
Payment schemes
Next
Usage models
Built with