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

Usage models

Usage models define how clients consume their purchased API access. Kobaru supports two models: pay-per-request and pay-per-time.

Overview#

When a client pays for API access, they receive a usage allocation. The usage model determines how that allocation is consumed:
ModelHow it worksBest for
Pay-per-requestEach request decrements a counterVariable usage patterns
Pay-per-timeUnlimited requests within a time windowHigh-frequency access

Pay-per-request#

Clients purchase a bundle of requests. Each successful API call consumes one request from their balance.

Configuration#

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

How it works#

1.
Client pays and receives 10 requests
2.
Each request that reaches your backend decrements the counter (10 → 9 → 8...); some responses refund it (see Refunds)
3.
When counter reaches 0, access is denied
4.
Client must pay again for more requests

Tracking#

Usage is tracked atomically:
One quota per payment, whatever its encoding, owned by the first route that uses it
Each request decrements it by one
Consistent across all edge locations

Refunds#

The use is consumed when the request reaches your backend. What happens next depends on your response:
Your responseUsePayment settled?
2xxConsumedYes
401, 403Refunded (upstream auth error)No
429Refunded (upstream rate limit)No
5xxRefunded (server error)No
Any other non-2xx (e.g. 400, 404, 422)ConsumedNo
After a 2xx, if the settlement fails for good the use is refunded and the client gets 402; if the payment couldn't be claimed (503 claim_unavailable) or the gateway can't process its network right now (503 server_configuration_error, rpc_unavailable or bite_unavailable), it is refunded too. If the outcome is unknown (503 settlement_pending), the use stays consumed until the outcome is known (Kobaru resolves it on a retry or in the background); once it turns out settled, the next request with the same payment is served without costing another use.
Example: Client has 8 requests remaining. Your API returns 500. Kobaru refunds the request, so they still have 8 remaining.

Pay-per-time#

Clients purchase unlimited access for a specified duration. The clock starts on first use.

Configuration#

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

How it works#

1.
Client pays and receives a 1-hour access window
2.
Timer starts on the first request
3.
Unlimited requests allowed until timer expires
4.
After expiration, access is denied

Tracking#

Activation is tracked per payment:
Owned by the first route that uses it
Stores the activation time
Expires automatically after the time limit

No refunds#

Time-based access is not refundable. Once the timer starts, the time elapses regardless of usage or errors. The payment is settled on the first 2xx response.

Choosing a usage model#

Use pay-per-request when:#

Usage varies significantly between clients
You want to charge proportionally to consumption
Clients make occasional, valuable requests
You want to offer refunds for errors

Use pay-per-time when:#

Clients need high-frequency access
Usage is predictable and consistent
You want to reduce payment friction
Simplicity is more important than precise billing

Configuration examples#

Per-request bundle#

Sell 100 requests for $0.10:

Time-based access#

Sell 1 hour of unlimited access for $1.00:

Usage in the proxy#

When using the transparent proxy, configure usage models in the Kobaru Console:
1.
Go to Services > Routes
2.
Select your route
3.
Set Usage model to pay_per_request or pay_per_time
4.
Set Limit (requests or seconds)

Related documentation#

Transparent proxy - Automatic usage tracking
Pricing guide - Setting prices for your API
Security - How usage tracking prevents abuse
Modified at 2026-10-30 21:41:30
Previous
Security
Next
Access tiers
Built with