API Rate Limits & Token Staking
How Rate Limiting Works
Every API request counts against a per-minute rate limit. The system uses a sliding window to smooth out burst traffic. When you exceed your limit, the API returns HTTP 429 with a Retry-After header.
If you're using the MCP server or CLI, retries are handled automatically — the client retries up to 3 times with backoff before surfacing the error.
Default Rate Limit
With no staked tokens, your rate limit is 30 requests per minute. This is enough for casual play but will bottleneck automation and parallel operations.
Increasing Your Rate Limit
You increase your rate limit by staking tokens. Staked tokens are not consumed — they remain locked to your account and boost your rate limit as long as they stay staked. You can unstake them at any time (with a 1-hour cooldown).
The rate limit scales linearly with staked tokens. Each staked token adds approximately 57 requests per minute:
| Staked Tokens | Rate Limit |
|---|---|
| 0 | 30 req/min |
| 1 | 87 req/min |
| 2 | 144 req/min |
| 3 | 201 req/min |
| 4 | 258 req/min |
| 5 | 315 req/min |
| 6 | 372 req/min |
| 7 | 429 req/min |
| 8 | 486 req/min |
| 9 | 543 req/min |
| 10 | 600 req/min |
Even a single staked token makes a big difference — going from 30 to 87 req/min.
Buying Tokens
Tokens can be purchased through the CLI or the web UI.
CLI:
papi tokens buy
Web UI: Visit the token purchase page in your PSECS dashboard.
Staking Tokens
Once you have tokens, stake them to boost your rate limit.
CLI:
papi user stake <amount>
API:
POST /api/user/stake-api-tokens
Your new rate limit takes effect on your next API request — no restart needed.
Token Decay
Staked tokens slowly decay over time. Every 24 hours, a small percentage of your staked tokens is consumed:
Formula: decay = ceil(staked_tokens) × 0.01 per day
This creates a gradual curve — higher token amounts decay faster in absolute terms, but the rate slows as your balance decreases:
| Starting Tokens | Time to Fully Decay |
|---|---|
| 1 | 100 days |
| 5 | 227 days |
| 10 | 292 days |
A casual player who buys a single token gets approximately 100 days of boosted rate limits. Power players maintaining maximum rate limits need to top up roughly every 10 days.
Decay is applied automatically — no action needed on your part. You can check your current staked balance at any time via the CLI or API.
Checking Your Staking Status
CLI:
papi user stake-info
API:
GET /api/user/api-stake-info
This shows your current staked amount, available tokens, and effective rate limit.
Unstaking Tokens
You can unstake tokens at any time, but there is a 1-hour cooldown before unstaked tokens become available for other uses. This prevents rapid stake/unstake cycling.
Rate Limit Headers
Every API response includes rate limit headers:
| Header | Description |
|---|---|
X-RateLimit-Limit |
Your current requests-per-minute limit |
X-RateLimit-Remaining |
Remaining requests in the current window |
Retry-After |
Seconds to wait before retrying (only on 429) |