Kobaru
  1. Transparent Proxy
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
    • Guides
      • Pricing your API
      • Going to Production
      • Testing with devnet
      • Bazaar discovery
    • 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
    • Schemas
      • SupportedResponse
      • ErrorResponse
      • UnauthorizedResponse
      • RateLimitResponse
      • VerifySuccessResponse
      • VerifyErrorResponse
      • SettleSuccessResponse
      • SettleErrorResponse
      • DiscoveryResourceItem
      • ListDiscoveryResourcesResponse
  1. Transparent Proxy

Capabilities and routes

Capabilities define which payment methods your proxy accepts. Routes let you override pricing for specific API paths.

Capabilities (global defaults)#

A capability represents a payment method available to your account. Each capability combines:
SettingExampleDescription
NetworkSolana, Base, SKALEThe blockchain network
CurrencyUSDCThe token used for payment
SchemeExact (x402)The payment protocol
Wallet address7xKXtg...Where you receive payments
Default price0.10 USDCHow much to charge
Usage modelPay per requestHow access is consumed
Usage limit100 requestsHow much access each payment buys

Enabling a capability#

1.
Go to Capabilities in the Kobaru Console
2.
Click Enable Capability
3.
Select the network, currency, and scheme combination
4.
Click Enable

Configuring a capability#

After enabling, configure the required fields:
1.
Click the edit icon on the capability row
2.
Set your wallet address (where payments are sent)
3.
Set the default price (in USDC)
4.
Choose a usage model (pay_per_request or pay_per_time)
5.
Set the usage limit (number of requests or seconds)
6.
Click Save
All four fields are required. The proxy won't process traffic until at least one capability is fully configured.

Multiple capabilities#

You can enable multiple capabilities to accept payments on different networks. When a client requests your API, they receive all available payment options and choose which one to use.

Usage models#

Pay-per-request#

Clients purchase a bundle of requests. Each successful API call consumes one request from their balance.
How it works:
1.
Client pays and receives N requests
2.
Each successful request decrements the counter
3.
When the counter reaches 0, access is denied
4.
Client must pay again
Usage credits: If your backend returns certain errors, the request is not counted against the usage limit:
Status codeCounted against usage?Reason
200-299YesSuccessful response
400, 404, 422YesClient error
401, 403, 429NoUpstream issue (credit restored)
500-599NoServer error (credit restored)
"Credit restored" means the usage counter is incremented back. No blockchain transaction is reversed.

Pay-per-time#

Clients purchase unlimited access for a duration. The clock starts on first use.
How it works:
1.
Client pays and receives a time window (e.g., 1 hour)
2.
Timer starts on the first request
3.
Unlimited requests allowed until the timer expires
4.
After expiration, access is denied
No refunds: Time-based access is not refundable. Once the timer starts, time elapses regardless of usage or errors.

Choosing a model#

Use pay-per-request whenUse pay-per-time when
Usage varies between clientsClients need high-frequency access
You want proportional billingUsage is predictable
Clients make occasional requestsYou want to reduce payment friction
You want refunds for errorsSimplicity is more important

Routes (path-specific overrides)#

Routes let you set different pricing for specific API paths. Without routes, all paths use the capability's default pricing.

Creating a route#

1.
Go to Routes in the Kobaru Console
2.
Click Add Route
3.
Select the service this route applies to
4.
Enter the path pattern (e.g., /premium/*, /free, /historical)
5.
Override the price, usage model, or usage limit
6.
Click Save

How route matching works#

When a request arrives, the gateway:
1.
Checks if the request path matches any route pattern
2.
If a match is found, uses the route's pricing overrides
3.
If no match is found, uses the capability's default pricing

Example configuration#

Service: weather-service
Capability default: 0.10 USDC per 100 requests

Routes:
  /premium/*     --> 0.50 USDC per 50 requests
  /free/*        --> 0.01 USDC per 10 requests
  /historical    --> 0.20 USDC per 200 requests
A request to /premium/forecast uses the premium pricing. A request to /current uses the default capability pricing.

Next steps#

Your proxy is now configured and accepting payments. Review the constraints and security details, or jump to troubleshooting if you run into issues.
Modified at 2026-02-10 21:52:10
Previous
Constraints and security
Next
Domain verification
Built with