Skip to main content

​
Overview

OneShot enforces rate limits to ensure fair usage and protect system stability. Limits are applied per agent (identified by wallet address) or per IP address, depending on the endpoint type.

​
Rate Limits by Endpoint Type

Endpoint TypeLimitWindowKey
Paid endpoints60 requests1 minuteAgent wallet
Expensive operations10 requests1 minuteAgent wallet
Free read endpoints120 requests1 minuteAgent wallet

​
Endpoint Categories

Standard paid API calls:
  • POST /v1/tools/email/quote
  • POST /v1/tools/email/send
  • POST /v1/tools/enrich/email
  • POST /v1/tools/enrich/profile
  • POST /v1/tools/verify/email
  • POST /v1/tools/commerce/search
  • POST /v1/tools/commerce/buy
  • POST /v1/tools/sms/send

​
Expensive Operations (10/min)

Resource-intensive operations with stricter limits:
  • POST /v1/tools/voice/call — Voice calls
  • POST /v1/tools/research — Deep web research
  • POST /v1/tools/research/people — People discovery

​
Free Read Endpoints (120/min)

Read-only endpoints that don’t require payment:
  • GET /v1/tools/inbox/list — Email inbox list
  • GET /v1/tools/inbox/:id — Email details
  • GET /v1/tools/sms/inbox — SMS inbox list
  • GET /v1/tools/sms/inbox/:id — SMS details
  • GET /v1/status/:id — Job status polling

​
Rate Limit Response

When you exceed a rate limit, you’ll receive a 429 Too Many Requests response: 
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests, please try again later.",
  "retry_after": 60
}

​
Response Headers

Rate limit information is included in response headers:
HeaderDescription
RateLimit-LimitMaximum requests allowed in window
RateLimit-RemainingRequests remaining in current window
RateLimit-ResetSeconds until the window resets

​
Best Practices

When you receive a 429 response, wait for the retry_after period before retrying. For repeated rate limits, increase the wait time exponentially.
async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error: any) {
      if (error.status === 429 && attempt < maxRetries - 1) {
        const delay = Math.pow(2, attempt) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}
For bulk operations, use batch endpoints where available:
  • SMS: Send to multiple recipients in one request (up to 10)
  • Email: Include multiple recipients in one send
Free read endpoints like inbox list and status polling have generous limits, but caching results client-side reduces unnecessary API calls.
Instead of polling /status/:id repeatedly, configure webhooks to receive notifications when jobs complete.

​
SDK Handling

The OneShot SDK automatically handles rate limit responses with built-in retry logic: 
import { OneShot } from "@oneshot-agent/sdk";

const agent = new OneShot({
  privateKey: process.env.AGENT_PRIVATE_KEY
});

// SDK automatically retries on 429 with exponential backoff
const result = await agent.research({
  query: "Latest AI developments"
});

​
Need Higher Limits?

If your use case requires higher rate limits, contact us at [email protected] to discuss enterprise options.