Rate Limits

​

Limits set by your key’s tier

• Request rate. Requests per minute. Exceeding it returns 429 RATE_LIMIT_EXCEEDED.
• Per-trade cap. The USDC amount of one trade. A larger trade is refused at once with 409 SPENDING_LIMIT_EXCEEDED.
• Daily spend cap. Total USDC bought through the key since 00:00 UTC. This is checked after the trade is accepted: a buy that would exceed it moves to rejected and fires a trade.rejected webhook. Sells do not count against it.
• High-value confirmation. On tiers that have one, a trade at or above the threshold returns 202 Accepted with confirmation: { token, expiresAt }. Release it before expiresAt with POST /v1/trades/{id}/confirm. This gives your system a chance to stop a runaway bot before it commits a large trade.

​

Who shares a quota

• The request rate is counted per user, across every key that user holds, so extra keys do not add throughput. Each key is also counted on its own, with the same limit.
• Spending caps are per key.
• Read routes and write routes draw from separate budgets, each at the tier’s per-minute limit:
  • Read routes (every GET) use a sliding window: smooth, with no bursting.
  • Write routes (every rate-limited POST) use a token bucket: its capacity equals the limit and it refills continuously, so short bursts are allowed.

​

Response headers

X-RateLimit-Limit:     100
X-RateLimit-Remaining: 87
X-RateLimit-Reset:     1792000060

• X-RateLimit-Limit: the per-minute limit.
• X-RateLimit-Remaining: requests left before you are refused.
• X-RateLimit-Reset: Unix time in seconds when the budget is full again.

​

Hitting the limit

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 12
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1792000072

{
  "type": "https://docs.kash.bot/developer-docs/api-errors/RATE_LIMIT_EXCEEDED",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "RATE_LIMIT_EXCEEDED",
  "detail": "…",
  "instance": "/v1/markets",
  "requestId": "…"
}

​

Temporarily disabled routes

​

Best practices

• Read the headers and keep X-RateLimit-Remaining comfortably above zero under steady load.
• Use conditional requests for polling. A 304 Not Modified still counts as a request, but it is cheap. See ETags.
• Prefer webhooks to polling trade status.
• Cache quotes briefly. Quote responses carry a short Cache-Control max-age.
• Use the SDK. It honours Retry-After with exponential backoff and jitter, and sends an idempotency key on writes so retries are safe.

​

Upgrading your tier

• free → developer: request it from the info button in the Kash web app → Feedback, with a one-line description of your use case.
• enterprise: ask from the info button in the Kash web app → Feedback, or in Discord.
• mm: ask from the info button in the Kash web app → Feedback, or in Discord.

​

Telemetry

curl https://api.kash.bot/v1/account/usage \
  -H "X-API-Key: $KASH_API_KEY" | jq '.data.auth["24h"].rateLimitRejections'

​

Next