Rate Limiting | KYA Chain

Overview

Rate limits for the Verification API are based on your agent's trust tier, which is determined by the amount of LABS tokens staked in the TrustVault contract. Higher tiers unlock higher API throughput, enabling production-grade usage for high-traffic agents.

Rate limits are enforced using a sliding window per-minute counter stored in Redis. Each request increments a counter for the current minute bucket. If Redis is unavailable, rate limits fail open (requests pass through), but the global IP-based rate limit of 100 requests per minute remains active.

Tier 0 agents are completely blocked from the Verification API. You must stake at least 1,000 LABS to access any endpoint.

Tier Rate Limits

Tier	Name	Staked LABS	Requests/Minute	Requests/Hour	Requests/Day
0	Unverified	0	Blocked	Blocked	Blocked
1	Bronze	1,000+	1	60	1,440
2	Silver	10,000+	16	960	23,040
3	Gold	100,000+	166	9,960	239,040
4	Diamond	500,000+	2,700	162,000	3,888,000

Tier 1 (Bronze) is suitable for testing and personal agents with low query rates.

Tier 2 (Silver) supports production agents with moderate traffic (up to 23,000 requests per day).

Tier 3 (Gold) is designed for high-traffic production agents requiring frequent verification checks.

Tier 4 (Diamond) provides enterprise-grade throughput with nearly 4 million requests per day.

How It Works

The rate limiting system uses a sliding window algorithm with 1-minute buckets:

Bucket key format: ratelimit:{agentId}:{minuteBucket} where minuteBucket is the current Unix timestamp divided by 60.
Counter increment: Each request increments the counter for the current minute bucket.
TTL: Each bucket expires after 120 seconds (covers current + previous minute).
Tier lookup: The agent's trust tier is fetched from the TrustVault contract via a two-layer cache (Redis + in-memory).
Limit enforcement: If the counter exceeds the tier's rate limit, the request is rejected with a 429 status code.

Rate limits fail open on Redis errors. If you receive 429 responses during a Redis outage, wait and retry.

Fail-Open Behavior

If Redis is unavailable, tier-based rate limits are not enforced. Requests pass through without rate limit checks. However, the global IP-based rate limit of 100 requests per minute (from @fastify/rate-limit) remains active to prevent abuse.

Rate Limit Headers

Every API response includes rate limit headers:

X-RateLimit-Limit: Maximum requests per minute for your tier (e.g., 2700 for Diamond).
X-RateLimit-Remaining: Remaining requests in the current 1-minute window (e.g., 2695).
Retry-After (429 responses only): Number of seconds to wait before retrying (e.g., 42).

Example Response Headers

X-RateLimit-Limit: 166
X-RateLimit-Remaining: 165

If rate limited:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 1
X-RateLimit-Remaining: 0
Retry-After: 42

{
  "error": "RATE_LIMITED",
  "message": "Rate limit exceeded. Your tier allows 1 requests per minute.",
  "details": {
    "tier": 1,
    "limit": 1,
    "retryAfter": 42
  }
}

Upgrading Your Tier

To increase your rate limits, stake more LABS tokens in the TrustVault contract. Your tier is recalculated immediately when you stake or unstake.

See the Tier Upgrades guide for a complete walkthrough of the staking process.

Global Rate Limit

In addition to tier-based rate limits, all requests are subject to a global IP-based rate limit of 100 requests per minute. This limit applies regardless of your tier and protects the API from abuse.

If you exceed the global limit, you'll receive a 429 response with error code TOO_MANY_REQUESTS. This limit is independent of your agent's trust tier and is enforced even if tier-based rate limiting fails open.

On this page