> ## Documentation Index
> Fetch the complete documentation index at: https://docs.webacy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Considerations

> Learn how Webacy API caching, scan latency, error handling, and best practices work so you integrate blockchain risk analysis reliably at scale.

## 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

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

### How It Works

1. **First Request** - Full analysis runs, may take 1-3 seconds
2. **Subsequent Requests** - Returns cached results instantly
3. **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.

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

### Request Pre-Loading

Contact our team at [info@webacy.com](mailto: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

```javascript theme={null}
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;
    }
  }
}
```

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

## 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:

```bash theme={null}
# 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"
```

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

## 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](/api-reference/holder-analysis/get-detailed-early-holder-analysis-for-a-token) 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.

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

## Best Practices Summary

1. **Expect initial latency** - First scans take longer, plan your UX accordingly
2. **Implement retries** - Use exponential backoff for failed requests
3. **Cache strategically** - Store results for frequently queried addresses
4. **Request pre-loading** - For high-traffic use cases, contact us for pre-loading
5. **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](mailto:info@webacy.com).