Transparent proxy integration

Go from unpaid API to paid API in under 5 minutes. No code changes. No deployment.

Kobaru's transparent proxy sits between your clients and your backend, handling payment verification, usage tracking, and automatic refunds. Just configure your service once in the console—all your endpoints become payment-gated instantly.

How it works

What happens at each step:

Client requests your endpoint through access.kobaru.io/{your-slug}/endpoint

No payment token? Kobaru returns HTTP 402 with payment instructions

Client pays by signing a Solana transaction

Client retries with payment proof in the Authorization header

Kobaru verifies the payment and checks remaining usage (you don't need to do anything)

Request forwarded to your backend with X-Kobaru-Payment-Hash header

Response returned to client, usage tracked, refunds processed if needed

Setup

Step 1: Create your service

In the Kobaru Console:

Navigate to Services

Click Create Service

Configure your service:

Field	Example	Description
Service name	`weather-api`	Display name for your service
Slug	`weather`	Your merchant identifier in the proxy URL
Backend URL	`https://api.yourcompany.com`	Your actual API base URL

How routing works:

Requests to access.kobaru.io/{slug}/path are proxied to {backend-url}/path:

Client requests	Kobaru proxies to
`access.kobaru.io/weather/forecast`	`api.yourcompany.com/forecast`
`access.kobaru.io/weather/data/history`	`api.yourcompany.com/data/history`
`access.kobaru.io/weather/v2/realtime`	`api.yourcompany.com/v2/realtime`

All paths are automatically proxied—no need to configure each route individually.

Step 2: Configure payment defaults

Set the default payment options for your entire service:

Field	Example	Description
Networks	Solana Mainnet, Devnet	Which blockchain networks to accept
Currency	USDC	Payment currency
Wallet address	`YourSolana...`	Where you receive payments
Price	`10000`	Default price in atomic units ($0.01)
Usage model	`pay_per_request`	How usage is tracked
Usage limit	`1`	Requests or seconds included

These defaults apply to all requests to your service.

Step 3: Configure route overrides (optional)

Need different pricing for specific endpoints? Add route-level overrides:

Route pattern	Price	Usage Model	Limit	Effective Cost
`GET /forecast/*`	10000	pay_per_request	10	$0.001 per request
`GET /historical/*`	100000	pay_per_request	1	$0.10 per request
`POST /realtime`	100000	pay_per_time	3600	$0.10 per hour

Route overrides take precedence over service defaults. Routes without overrides use the service defaults.

When to use route overrides:

Expensive endpoints that need higher pricing (e.g., AI inference, large data exports)

High-frequency endpoints that benefit from time-based access

Free endpoints that should bypass payment (set price to 0)

Step 4: Activate your service

Review your configuration

Click Activate Service

Your entire API is now payment-gated at: https://access.kobaru.io/{your-slug}/

Usage models

Kobaru supports two usage models for tracking how clients consume their payments.

Pay-per-request

Clients pay for a bundle of requests. Each successful request decrements their remaining count.

{
  "extensions": {
    "usage": {
      "model": "pay_per_request",
      "limit": 10,
      "unit": "request"
    }
  }
}

Behavior:

Client pays once, gets 10 requests

Each request decrements the counter

Refunds increment the counter back (for eligible errors)

When counter reaches 0, client must pay again

Best for: API calls with predictable value per request.

Pay-per-time

Clients pay for unlimited access within a time window.

{
  "extensions": {
    "usage": {
      "model": "pay_per_time",
      "limit": 3600,
      "unit": "second"
    }
  }
}

Behavior:

Clock starts on first request after payment

Unlimited requests until time expires

No refunds (time has elapsed regardless of errors)

When time expires, client must pay again

Best for: High-frequency access, streaming data, real-time feeds.

Headers forwarded to your backend

When Kobaru forwards a paid request to your backend, it modifies headers for security and traceability.

Note: Your backend receives clean requests with payment details removed but tracking information added.

Headers added

Header	Value	Description
`X-Kobaru-Payment-Hash`	`abc123...`	Unique payment identifier for this transaction

Headers removed

Header	Reason
`Authorization`	Prevents leaking x402 payment token to your backend
`Host`	Replaced with your backend's host
`cf-connecting-ip`	Cloudflare-specific header

Using the payment hash

Your backend can use X-Kobaru-Payment-Hash to:

Log which payment was used for each request

Implement custom rate limiting per payment

Track usage analytics by payment

Correlate requests across your logging systems

Automatic refunds

Kobaru automatically refunds usage when your backend returns errors that are not the client's fault. This applies only to the pay_per_request usage model.

Refund decision matrix

Status Code	Category	Refunded?	Reason
200-299	Success	No	Request completed successfully
400	Bad Request	No	Client sent invalid request
404	Not Found	No	Client requested non-existent resource
422	Unprocessable Entity	No	Client sent semantically invalid data
401	Unauthorized	Yes	Your backend rejected the request (auth issue on your side)
403	Forbidden	Yes	Your backend rejected the request (permission issue on your side)
429	Too Many Requests	Yes	Your backend rate-limited the request
500-599	Server Error	Yes	Your backend encountered an error
502	Bad Gateway	Yes	Kobaru could not reach your backend

Key principle: If the client paid and did everything correctly, but your backend failed, they get their usage back. If the client made an error (bad request, wrong endpoint), they do not get a refund.

Pay-per-time refunds

The pay_per_time model does not issue refunds. Time continues to elapse regardless of errors. If your backend experiences issues, clients still consume their time window.

Testing your integration

Testing with Devnet

Before going to production, test with Solana Devnet:

In the console, set your service to use Devnet: solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1

Get test USDC from a faucet

Test the complete payment flow

Verify payment requirements

Request your endpoint without payment to see the 402 response:

Expected response:

Verify paid request flow

After paying, include the token in subsequent requests:

Expected response: Your backend's normal response, forwarded through Kobaru.

Limitations

The transparent proxy has some constraints due to its edge-first architecture.

Limitation	Value	Workaround
WebSocket connections	Not supported	Use Standard SDK for WebSocket APIs
Custom authentication	Forwarded but not validated	Your backend handles its own auth
Request timeout	50 seconds	Optimize slow endpoints

When to use the SDK instead

Consider the Standard SDK integration if you need:

WebSocket or long-lived connections

Custom payment verification logic

Full control over the 402 response format

Note: Route-based dynamic pricing (different prices per endpoint) is fully supported in the proxy via route overrides. Use the SDK only if you need pricing based on request body content, user identity, or runtime conditions.

Next steps

Usage models - Understand pay-per-request vs pay-per-time

Pricing your API - Best practices for setting prices

Testing with devnet - Complete testing guide

Going to production - Production checklist

Transparent proxy integration

Transparent proxy integration#

How it works#

Setup#

Step 1: Create your service#

Step 2: Configure payment defaults#

Step 3: Configure route overrides (optional)#

Step 4: Activate your service#

Usage models#

Pay-per-request#

Pay-per-time#

Headers forwarded to your backend#

Headers added#

Headers removed#

Using the payment hash#

Automatic refunds#

Refund decision matrix#

Pay-per-time refunds#

Testing your integration#

Testing with Devnet#

Verify payment requirements#

Verify paid request flow#

Limitations#

When to use the SDK instead#

Next steps#

Transparent proxy integration

How it works

Setup

Step 1: Create your service

Step 2: Configure payment defaults

Step 3: Configure route overrides (optional)

Step 4: Activate your service

Usage models

Pay-per-request

Pay-per-time

Headers forwarded to your backend

Headers added

Headers removed

Using the payment hash

Automatic refunds

Refund decision matrix

Pay-per-time refunds

Testing your integration

Testing with Devnet

Verify payment requirements

Verify paid request flow

Limitations

When to use the SDK instead

Next steps