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

# Rate Limits and Abuse Prevention in ArcPass

> How ArcPass IP and wallet rate limiting works, what a 429 error means, how auto-blocking and replay protection prevent abuse, and how to configure thresholds.

ArcPass includes built-in abuse prevention to protect shared gas infrastructure and ensure fair access for all users. Rate limiting applies at two independent layers — per IP address and per wallet address — and operates on a sliding window that resets automatically. In addition, a short-window replay deduplication filter drops identical requests that arrive within seconds of each other.

<Note>
  Most legitimate users will never encounter these limits. A single wallet requesting its one-time sponsorship will use one request out of the allowed five per hour, well below any threshold. These controls exist to protect the infrastructure from automated abuse, not to restrict normal use.
</Note>

## IP rate limiting

Every incoming request to `POST /sponsorship/request` is counted against the originating IP address. By default, a single IP address may send up to **10 requests per hour**. If an IP exceeds this threshold, it is automatically blocked for **15 minutes** before the counter resets.

The relevant environment variables:

| Variable                       | Default               | Description                                         |
| ------------------------------ | --------------------- | --------------------------------------------------- |
| `RATE_LIMIT_IP_MAX`            | `10`                  | Max requests per IP per window                      |
| `RATE_LIMIT_WINDOW_MS`         | `3600000` (1 hour)    | Length of the sliding window                        |
| `RATE_LIMIT_BLOCK_DURATION_MS` | `900000` (15 minutes) | How long an IP is blocked after exceeding the limit |

## Wallet rate limiting

The wallet address provided in the request body is checked independently from the IP. By default, a single wallet address may appear in up to **5 requests per hour**. Exceeding this limit triggers the same auto-block behavior, locking the wallet out for **15 minutes**.

The relevant environment variable:

| Variable                | Default | Description                        |
| ----------------------- | ------- | ---------------------------------- |
| `RATE_LIMIT_WALLET_MAX` | `5`     | Max requests per wallet per window |

## Auto-block behavior

When either threshold is exceeded, ArcPass records a block entry in the database with an expiry timestamp. Blocked IPs and wallets receive an HTTP `429` response on every subsequent request until the block expires. The block duration is independent of the rate limit window — you can configure them separately to tune how aggressively the system responds to bursts.

## Replay protection

In addition to rate limiting, ArcPass deduplicates requests within a short time window to prevent accidental or deliberate duplicate submissions. If the API receives two requests with the same `walletAddress` and originating IP address within **5 seconds** of each other, the second request is dropped silently.

This protects against:

* Network retries that arrive while the first request is still processing
* Client-side double-submits from rapid button clicks
* Scripted burst submissions from a single source

## What you see when rate limited

When your IP or wallet is rate limited or blocked, the API responds with:

```http theme={null}
HTTP/1.1 429 Too Many Requests
```

```json theme={null}
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please wait before submitting another request."
}
```

If you receive a `429` response, wait for the current rate limit window or block period to expire, then try again. There is no manual reset — the block clears automatically.

## Configuring limits for your deployment

If you operate your own ArcPass instance, you can adjust all rate limit thresholds through environment variables. For example, to allow 20 requests per IP per hour with a 30-minute block:

```bash theme={null}
RATE_LIMIT_IP_MAX=20
RATE_LIMIT_WINDOW_MS=3600000
RATE_LIMIT_BLOCK_DURATION_MS=1800000
```

Setting `RATE_LIMIT_IP_MAX` or `RATE_LIMIT_WALLET_MAX` to a very high value effectively disables that layer of rate limiting, which is only appropriate in controlled environments. Public deployments should keep limits conservative.