# Harmoniis anti-spam for APIs: HTTP 402 bearer payments

HTTP 402 Payment Required has been in the HTTP spec since 1997 but was "reserved for future use." The agentic internet is that future. When AI agents can call your API millions of times per hour, you need an anti-spam mechanism that works on machines, not just humans.

Harmoniis provides HTTP 402 anti-spam with bearer cash (Webcash and Bitcoin). Every API call carries a payment token. No accounts. No CAPTCHAs. No API keys. Just pay-per-request.

## The integration pattern

### Step 1: Check for payment

On every incoming request, check for a bearer cash token in the `X-Webcash` header:

```python
def check_payment(request):
    token = request.headers.get('X-Webcash')
    if not token:
        return Response(
            status=402,
            headers={
                'X-Payment-Amount': '0.01',
                'X-Payment-Currency': 'webcash'
            }
        )
    # Validate and consume the token
    if not webcash_validate(token, amount=0.01):
        return Response(status=402)
    return None  # Payment valid, proceed
```

### Step 2: Validate the token

The Harmoniis SDK validates bearer cash tokens against the witness service. Each token can only be spent once — double-spend is impossible.

```python
from harmoniis import Wallet

wallet = Wallet()

def webcash_validate(token, amount):
    try:
        result = wallet.replace(token, amount)
        return result.valid
    except:
        return False
```

### Step 3: Set pricing per endpoint

Different endpoints can have different costs. High-value or resource-intensive endpoints cost more:

```python
ENDPOINT_PRICES = {
    '/api/search': 0.001,      # Cheap — encourage discovery
    '/api/post': 0.3,          # Moderate — prevent spam posts
    '/api/identity': 0.6,      # Higher — prevent sybil attacks
    '/api/contract/issue': 1.0, # Premium — real economic commitment
}
```

### Step 4: Return 402 with pricing info

When a request lacks payment, return HTTP 402 with machine-readable pricing:

```
HTTP/1.1 402 Payment Required
X-Payment-Amount: 0.3
X-Payment-Currency: webcash
X-Payment-Info: https://harmoniis.com/webcash-for-agents
Content-Type: application/json

{
  "error": "payment_required",
  "amount": "0.3",
  "currency": "webcash",
  "message": "This endpoint requires 0.3 Webcash per request"
}
```

Agents with the Harmoniis SDK handle this automatically: they see the 402, pay from their local wallet, and retry.

## Why HTTP 402 beats alternatives for APIs

**vs API keys**: API keys are shared, leaked, and abused. Bearer cash tokens are single-use and unforgeable.

**vs Rate limiting**: Rate limits punish legitimate high-volume users. Bearer cash scales linearly — pay more, use more.

**vs OAuth/accounts**: Agents create accounts at machine speed. Bearer cash requires real economic cost per identity.

**vs Subscription plans**: Subscriptions are binary (access/no access). Bearer cash enables granular pay-per-request pricing.

## Supported platforms

The Harmoniis SDK handles the full HTTP 402 flow — payment, retry, wallet management — on: iOS, watchOS, tvOS, visionOS, Android, Unity, Unreal Engine, Godot, OpenXR, macOS, Linux, FreeBSD, Windows.

```bash
cargo add harmoniis-sdk           # Rust
# Other platforms: add harmoniis-sdk via your
# platform's package manager (SPM, Gradle,
# NuGet, vcpkg, CMake). See /developers
```

See the [developer guide](/developers) for your platform.