API Considerations - Webacy Docs

Overview

The Webacy API is designed for high performance and accuracy. Understanding these considerations will help you get the most out of your integration.

Speed & Latency

Initial scans may take up to 3 seconds while our Risk Engine analyzes the address. Subsequent requests for the same address return much faster.

How It Works

First Request - Full analysis runs, may take 1-3 seconds
Subsequent Requests - Returns cached results instantly
Background Refresh - System automatically re-analyzes addresses over time

Optimization Tips

Cache results on your end for frequently queried addresses
Use webhooks for real-time updates instead of polling
Batch your initial queries during off-peak hours if possible

Pre-Loading

For high-traffic applications, we offer custom pre-loading of specific token and address lists.

Pre-loading eliminates cold-start latency by ensuring addresses are already analyzed before your users query them.

Request Pre-Loading

Contact our team at info@webacy.com to set up pre-loading for:

Token contract addresses you frequently analyze
Watchlists of addresses your users interact with
New token launches you want to monitor

Failures & Retries

When an endpoint fails, the address is automatically queued for retry analysis.

Handling Failures

async function getAddressRisk(address, chain, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      const response = await fetch(
        `https://api.webacy.com/addresses/${address}?chain=${chain}`,
        { headers: { 'x-api-key': 'YOUR_API_KEY' } }
      );

      if (response.ok) {
        return await response.json();
      }

      // Wait before retry (exponential backoff)
      await new Promise(r => setTimeout(r, 1000 * Math.pow(2, i)));
    } catch (error) {
      if (i === retries - 1) throw error;
    }
  }
}

If you hit a failure, retry the request. Our system queues failed addresses for background processing, so a retry often succeeds.

Data Freshness

The API balances speed and accuracy through intelligent caching.

Cache Behavior

Scenario	Behavior
First request	May return cached data for speed
Subsequent requests	Triggers background refresh
Maximum cache age	24 hours

Forcing Fresh Data

For critical operations, you can request fresh analysis:

# Use refreshCache parameter where available
curl -X GET "https://api.webacy.com/addresses/0x...?chain=eth&refreshCache=true" \
  -H "x-api-key: YOUR_API_KEY"

Our data is regularly updated and never retains a cache longer than 24 hours. For most use cases, cached data is sufficiently current.

Data Availability & Retention

Some analyses depend on historical blockchain data from upstream providers with limited retention windows.

Early Holder Analysis

Chain	Coverage
Solana (`sol`)	Tokens launched within the last 12 months
BSC (`bsc`)	Tokens deployed within the last 3 months
Other supported chains	No retention limit

When a token falls outside the coverage window, the Holder Analysis endpoint returns HTTP 200 with data_availability: "unsupported_token_age" and a human-readable data_availability_message instead of computed first-buyer and sniper metrics.

Tokens analyzed before the retention cutoff continue to return their stored results — the limit only applies to tokens being analyzed for the first time.

Best Practices Summary

Expect initial latency - First scans take longer, plan your UX accordingly
Implement retries - Use exponential backoff for failed requests
Cache strategically - Store results for frequently queried addresses
Request pre-loading - For high-traffic use cases, contact us for pre-loading
Trust the cache - 24-hour cache is sufficient for most risk assessments

Need Help?

Our team is continuously improving these endpoints. If you have feedback or need custom solutions, contact us at info@webacy.com.

​Overview

​Speed & Latency

​How It Works

​Optimization Tips

​Pre-Loading

​Request Pre-Loading

​Failures & Retries

​Handling Failures

​Data Freshness

​Cache Behavior

​Forcing Fresh Data

​Data Availability & Retention

​Early Holder Analysis

​Best Practices Summary

​Need Help?

Overview

Speed & Latency

How It Works

Optimization Tips

Pre-Loading

Request Pre-Loading

Failures & Retries

Handling Failures

Data Freshness

Cache Behavior

Forcing Fresh Data

Data Availability & Retention

Early Holder Analysis

Best Practices Summary

Need Help?