Integrate payments directly into your API using the official x402 SDK. Fully compliant with the x402 v2 protocol, this approach ensures ecosystem-wide compatibility while giving you complete control over your infrastructure.The Standard SDK is for developers who want to add payment middleware to their existing TypeScript/Node.js, Go or Python applications. Kobaru handles payment verification and settlement while you maintain control over hosting, scaling, and business logic.
Prerequisites#
Before you begin, ensure you have:A Solana, Base and/or SKALE wallet address to receive payments (more networks are being implemented!)
Node.js and npm, Go or Python available
An existing API or server
Optional: A Kobaru account with an API key to make usage of premium features (get one from the Kobaru Console) Overview#
The x402 SDK adds payment middleware to your existing HTTP framework. When a request arrives without payment, the middleware returns HTTP 402 with payment options. When a request includes valid payment proof, the middleware verifies it with Kobaru and allows the request to proceed.This approach gives you easy implementation with few lines of code added to your backend.
Usage#
You can find the x402 SDK official documentation at Github.
After setting it up, you just need to set Kobaru as your facilitator:If you created a Kobaru account to use our premium features you should also use your API key:Check out Node.js and Go examples in the official repository Environment variables#
Configure these environment variables for your application:kbr_{environment}_{random}
kbr_live_... for production
kbr_test_... for testing (devnet)
How it works#
The payment flow follows these steps:Step 1: Request without payment#
Client makes a request to your protected endpoint without a payment header.Step 2: Payment required response#
The SDK middleware returns HTTP 402 with payment options in the PAYMENT-REQUIRED header:Step 3: Client signs payment#
The client creates and signs a Solana transaction authorizing the payment.Step 4: Request with payment proof#
Client resubmits the request with the signed transaction in the PAYMENT-SIGNATURE header:Step 5: Verification and response#
1.
Extracts the payment proof from the header
2.
Calls Kobaru's /v1/verify endpoint to validate
3.
On success, allows the request to proceed to your handler
4.
On failure, returns an error response
Testing#
Devnet testing#
Use Solana Devnet during development to avoid using real funds:Unit testing#
Mock the facilitator client in your test suite:
Advanced patterns#
Dynamic pricing#
Calculate prices based on request parameters:Multiple payment options#
Offer clients a choice of payment networks:
Comparison: SDK vs. proxy#
Choose the integration method that fits your needs:| Feature | SDK | Proxy |
|---|
| Code changes | Required | None |
| Setup time | 30 minutes | 5 minutes |
| Control | Full control over logic and hosting | Limited to proxy configuration |
| Dynamic pricing | Yes | No |
| Request size limit | Unlimited | 64KB |
| WebSocket support | Yes | No |
| Streaming responses | Yes | Yes |
| Hosting | Your infrastructure | Kobaru edge network |
| Scaling | You manage | Automatic |
| Custom authentication | Full control | Forwarded but not validated |
Choose SDK when you need:Dynamic pricing based on request content
Request bodies larger than 64KB
Full control over error handling
Custom authentication logic
No infrastructure management
Next steps#
Advanced SDK - Sessions, budgets, and analytics (coming soon) Modified at 2026-01-22 17:30:33
