Skip to main content

​
Authentication

The Token Launch API is currently open access with no API keys required:
  • ✅ No authentication needed
  • ✅ No API keys to manage
  • ✅ IP-based rate limiting only
Need higher rate limits? DM @zcombinatorio on Twitter to discuss increased limits for your use case.

​
Rate Limiting

All endpoints use IP-based rate limiting:

​
Current Limits

8 requests per IP per 2-minute window
  • Applies to all endpoints uniformly
  • Resets every 2 minutes
  • No exceptions for different endpoint types
  • Based on client IP address only
# Example rate limit headers (may be added in future)
X-RateLimit-Limit: 4
X-RateLimit-Remaining: 3
X-RateLimit-Reset: 1642248520
HTTP 429 - Too Many Requests
{
  "error": "Too many requests from this IP, please try again later."
}
When this happens:
  • Wait for the 2-minute window to reset
  • Implement exponential backoff
  • Consider caching responses when possible
Need more requests?For applications requiring higher rate limits:
  1. DM @zcombinatorio on Twitter
  2. Describe your use case and expected volume
  3. Custom rate limits can be arranged
  4. No cost for legitimate use cases
What to include in your DM:
  • Project description
  • Expected requests per minute
  • Use case (web app, bot, integration, etc.)
  • Timeline for deployment

​
HTTP Status Codes

​
Success Codes

Successful RequestThe request was processed successfully. Response contains the requested data.Endpoints: All endpoints return 200 on success Response: JSON object with requested data

​
Client Error Codes (4xx)

Invalid RequestThe request was malformed or contained invalid parameters.Common causes:
  • Missing required fields
  • Invalid parameter values
  • Business logic violations
  • Invalid Base58 addresses
Examples:
{
  "error": "Missing required fields: name, symbol, and payerPublicKey are required"
}

{
  "error": "CA ending must be 3 characters or less"
}

{
  "error": "Requested amount exceeds available claim amount"
}
Resource Not FoundThe requested resource doesn’t exist.Common causes:
  • Token not found in database
  • Invalid transaction keys
  • Token not launched through this API
Examples:
{
  "error": "Token not found"
}

{
  "error": "Token keypair not found. Please call /launch first."
}
Rate LimitedClient has exceeded the IP-based rate limit.Rate limit: 8 requests per IP per 2-minute windowResponse:
{
  "error": "Too many requests from this IP, please try again later."
}
Solutions:
  • Wait for rate limit window to reset (2 minutes)
  • Implement exponential backoff
  • Cache responses when possible
  • DM @zcombinatorio for higher limits

​
Server Error Codes (5xx)

Server ErrorAn unexpected error occurred on the server.Common causes:
  • Configuration issues
  • Blockchain network problems
  • External service failures
  • Database connectivity issues
Examples:
{
  "error": "RPC_URL not configured"
}

{
  "error": "Failed to create launch transaction"
}

{
  "error": "Helius API key not configured"
}
Solutions:

​
Rate Limit Best Practices

​
Client-Side Implementation

class APIClient {
  constructor() {
    this.requestCount = 0;
    this.windowStart = Date.now();
    this.maxRequests = 8;
    this.windowMs = 2 * 60 * 1000; // 2 minutes
  }

  async makeRequest(url, options) {
    // Check if we're approaching rate limit
    const now = Date.now();
    const windowElapsed = now - this.windowStart;

    if (windowElapsed >= this.windowMs) {
      // Reset window
      this.requestCount = 0;
      this.windowStart = now;
    }

    if (this.requestCount >= this.maxRequests) {
      const waitTime = this.windowMs - windowElapsed;
      throw new Error(`Rate limited. Wait ${Math.ceil(waitTime / 1000)} seconds.`);
    }

    try {
      const response = await fetch(url, options);

      if (response.status === 429) {
        // Server-side rate limit hit
        throw new Error('Rate limited by server. Please wait 2 minutes.');
      }

      this.requestCount++;
      return response;
    } catch (error) {
      if (error.message.includes('rate limit')) {
        // Exponential backoff
        await this.exponentialBackoff();
        return this.makeRequest(url, options);
      }
      throw error;
    }
  }

  async exponentialBackoff(attempt = 0) {
    const delay = Math.min(1000 * (2 ** attempt), 30000);
    const jitter = Math.random() * 1000;
    await new Promise(resolve => setTimeout(resolve, delay + jitter));
  }
}

​
Caching Strategies

Safe to cache:
  • Token verification results (/verify-token)
  • Token launch confirmations (once completed)
  • Health check results (short-term)
Cache duration suggestions:
  • Token existence: Permanent (tokens don’t get deleted)
  • Health status: 30-60 seconds
  • Launch confirmations: Permanent
Do not cache:
  • Claim eligibility (/claims/:tokenAddress) - changes over time
  • Unsigned transactions (/launch, /claims/mint) - time-sensitive
  • Error responses - may be transient
Why not to cache:
  • Claim eligibility changes every 24 hours
  • Transactions have expiration times
  • Cached errors prevent retry of transient issues

​
Monitoring Rate Limits

​
Client-Side Tracking

// Track your usage
const usage = {
  requests: 0,
  windowStart: Date.now(),

  log(endpoint) {
    this.requests++;
    console.log(`Request ${this.requests}/8 to ${endpoint}`);

    if (this.requests >= 4) {
      const nextWindow = new Date(this.windowStart + 2 * 60 * 1000);
      console.warn(`Rate limit reached. Next window: ${nextWindow.toLocaleTimeString()}`);
    }
  },

  reset() {
    this.requests = 0;
    this.windowStart = Date.now();
    console.log('Rate limit window reset');
  }
};

// Use in your API calls
usage.log('/launch');

​
Server Response Patterns

Look for these patterns in responses: 
// Rate limit approaching (implement client-side tracking)
if (clientRequestCount >= 3) {
  showWarning('Approaching rate limit. Next request may be delayed.');
}

// Rate limit hit
if (response.status === 429) {
  showError('Rate limited. Please wait 2 minutes before trying again.');
  // Set timer for retry
  setTimeout(() => {
    showInfo('Rate limit window reset. You can try again now.');
  }, 2 * 60 * 1000);
}

​
Contact for Support

Need Help?

  • Rate limit increases: DM @zcombinatorio
  • Technical issues: Report persistent 500 errors
  • Integration questions: Ask about best practices
  • Feature requests: Suggest improvements
Response time: Usually within 24 hours
⌘I