- Updated: March 19, 2026
- 6 min read
Configuring Per‑Agent Token‑Bucket Limits with OpenClaw Rating API
To configure and enforce per‑agent token‑bucket limits with the OpenClaw Rating API mobile SDKs, you define a bucket size and refill rate in code, instantiate a RateLimiter per agent, and apply the limiter before each API call on both iOS (Swift) and Android (Kotlin) platforms.
Introduction
Mobile developers building apps that charge users by usage or need to protect backend resources often turn to rate‑limiting algorithms. The OpenClaw Rating API provides a ready‑made SDK for iOS and Android, but the real power lies in configuring per‑agent token‑bucket limits that match your business model.
This guide walks you through the token‑bucket theory, why per‑agent limits matter, and step‑by‑step integration for Swift and Kotlin. You’ll also see real‑world scenarios, testing tips, and where to host your OpenClaw instance on UBOS.
What is a Token‑Bucket?
The token‑bucket algorithm is a simple yet flexible way to control request rates. Imagine a bucket that can hold N tokens. Every time a client (or “agent”) makes a request, it must consume one token. Tokens are added to the bucket at a steady refill rate (e.g., 5 tokens per second). If the bucket is empty, the request is rejected or delayed.
| Parameter | Meaning |
|---|---|
| Bucket Size | Maximum tokens the bucket can hold. |
| Refill Rate | Tokens added per second (or per minute). |
| Token Cost | How many tokens a single request consumes. |
This model naturally supports bursts (a short spike of traffic) while guaranteeing a long‑term average rate.
Why per‑agent limits matter
In multi‑tenant mobile apps, each user, device, or API key is an “agent”. Enforcing limits per agent lets you:
- Prevent a single free‑tier user from exhausting shared resources.
- Offer differentiated SLAs (e.g., premium users get larger buckets).
- Collect accurate usage metrics for billing.
- Detect abuse patterns early, especially for IoT devices that may misbehave.
OpenClaw’s SDK exposes a RateLimiter class that can be instantiated per agent, making per‑agent enforcement straightforward.
Setting up OpenClaw Rating API SDKs
4.1 iOS (Swift) integration
First, add the OpenClaw Swift package to your Xcode project:
swift package add https://github.com/openclaw/rating-sdk-swift.gitImport the module in the file where you’ll perform API calls:
import OpenClawRatingInitialize the SDK with your API key (store the key securely, e.g., in the Keychain):
let ratingClient = RatingClient(apiKey: "YOUR_OPENCLAW_API_KEY")
4.2 Android (Kotlin) integration
Add the Maven dependency to your build.gradle:
implementation "com.openclaw:rating-sdk:1.2.0"Sync the project, then import the SDK in your Kotlin file:
import com.openclaw.rating.RatingClientCreate a client instance using your secret key:
val ratingClient = RatingClient("YOUR_OPENCLAW_API_KEY")
Configuring token‑bucket parameters in code
5.1 Defining bucket size and refill rate
Both SDKs expose a TokenBucket struct/class. Below are Swift and Kotlin examples that set a bucket of 100 tokens with a refill of 10 tokens per minute.
Swift (iOS)
struct AgentRateLimiter {
let limiter: RateLimiter init(agentId: String) {
let bucket = TokenBucket(
capacity: 100, // bucket size
refillRate: 10, // tokens per minute
refillInterval: .minutes(1) // interval
)
self.limiter = RateLimiter(agentId: agentId, bucket: bucket)
}
func canProceed() -> Bool {
return limiter.tryConsume(tokens: 1)
}
}
Kotlin (Android)
class AgentRateLimiter(agentId: String) {
private val bucket = TokenBucket(
capacity = 100, // bucket size
refillRate = 10, // tokens per minute
refillInterval = Duration.ofMinutes(1)
)
private val limiter = RateLimiter(agentId, bucket) fun canProceed(): Boolean = limiter.tryConsume(1)
}
5.2 Applying limits per agent
Instantiate a limiter for each user/device and check it before every API request.
Swift usage example
func fetchUserScore(userId: String) {
let limiter = AgentRateLimiter(agentId: userId) guard limiter.canProceed() else {
print("Rate limit exceeded for user \(userId)")
return
}
ratingClient.getScore(for: userId) { result in
// handle response
}
}
Kotlin usage example
fun fetchUserScore(userId: String) {
val limiter = AgentRateLimiter(userId) if (!limiter.canProceed()) {
Log.w("RateLimiter", "Rate limit exceeded for $userId")
return
}
ratingClient.getScore(userId) { result ->
// handle response
}
}
Real‑world scenarios
Below are three common patterns where per‑agent token‑bucket limits shine.
6.1 API throttling for free‑tier users
Free users get a bucket of 50 tokens, refilling at 5 tokens per hour. Once exhausted, the app shows a “Upgrade to continue” prompt.
Implementation tip: Store the bucket state in UserDefaults (iOS) or SharedPreferences (Android) so limits survive app restarts.
6.2 Premium usage caps
Premium subscribers receive a larger bucket (500 tokens) and a faster refill (100 tokens per minute). The SDK can read the subscription tier from your backend and adjust the TokenBucket parameters dynamically.
6.3 Burst handling for IoT devices
IoT sensors often send data in bursts (e.g., after a motion event). By setting a high burst capacity (e.g., 200 tokens) but a modest refill (20 tokens per minute), you allow the spike while protecting downstream services.
Combine the token‑bucket with a LeakyBucket fallback to smooth out extreme bursts.
Testing and monitoring
Effective rate‑limiting requires observability. Follow these steps:
- Write unit tests that simulate rapid request bursts and verify
tryConsumereturnsfalseafter the bucket empties. - Instrument the SDK with analytics events (e.g., “rate_limit_exceeded”) and send them to your telemetry platform.
- Expose an admin endpoint that returns current bucket states for a given agent – useful for support teams.
- Set alerts on abnormal “rate_limit_exceeded” spikes, which may indicate abuse or a mis‑configured bucket.
“Never rely on a single limit; combine token‑bucket with IP‑based throttling for defense‑in‑depth.” – Industry Insight
Publishing the article on UBOS blog
When you push this guide to the UBOS blog, make sure to:
- Use the UBOS templates for quick start to keep the layout consistent.
- Tag the post with
mobile‑sdk,rate‑limiting, andOpenClawfor discoverability. - Link to the UBOS pricing plans so readers can see cost options for hosting.
- Reference the UBOS platform overview for a broader context of how OpenClaw fits into the ecosystem.
Production hosting for OpenClaw
After you’ve verified your rate‑limiting logic locally, deploy the OpenClaw service using UBOS’s managed hosting. The OpenClaw hosting option provides auto‑scaling, TLS termination, and built‑in monitoring, letting you focus on the client‑side SDK integration.
Conclusion
Per‑agent token‑bucket limits give you granular control over API consumption, protect backend resources, and enable flexible billing models. By following the Swift and Kotlin snippets above, you can embed robust rate‑limiting directly into your mobile app, test it thoroughly, and scale it with UBOS’s production hosting.
Ready to accelerate your development? Explore the AI marketing agents for automated user onboarding, or check out the UBOS partner program to collaborate on future integrations.