Harmoniis anti-spam for APIs: HTTP 402 in 10 minutes

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:

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.

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:

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, NetBSD, Windows.

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 for your platform.