ar.io Logoar.io Documentation
ar.io Gateway

Rate Limiting

Query and manage rate limit bucket balances. Supports both public balance queries and top-ups via x402 payments or admin authentication.

⚠️ EXPERIMENTAL FEATURES: The rate limiter and x402 payment protocol are experimental features subject to change. API endpoints, parameters, behavior, and configuration options (environment variables) may evolve in future releases as these systems continue to be developed. See docs/x402-and-rate-limiting.md for comprehensive documentation.

Query IP bucket balance

Get the current rate limit token balance for an IP address. Returns both regular (refilling) and paid tokens. Buckets are created on first request and refill over time.

Token System:

  • 1 token = 1 KiB (1,024 bytes)
  • Regular tokens: Automatically refill based on configured rate (e.g., 20 KB/s)
  • Paid tokens: Acquired via x402 payments, never refill, consumed after regular tokens
GET
/ar-io/rate-limit/ip/{ip}

Path Parameters

ipstring

IP address (IPv4, IPv6, or IPv4-mapped IPv6 format)

Formatipv4 or ipv6

Response Body

curl -X GET "https://turbo-gateway.com/ar-io/rate-limit/ip/192.168.1.100"
{
  "ip": "192.168.1.100",
  "tokens": 95000,
  "paidTokens": 50000,
  "capacity": 100000,
  "refillRate": 20,
  "lastRefill": 1735689600000
}
{
  "error": "Invalid IP address format"
}
{
  "error": "Bucket not found",
  "message": "No rate limit bucket exists for this IP. Buckets are created on first request."
}
"Internal Server Error"

Top up IP bucket

Add paid tokens to an IP bucket via x402 payment or admin authentication.

Authentication Modes:

  1. x402 Payment (Public):

    • Provide X-Payment header with payment data
    • Tokens calculated from payment amount
    • 10x capacity multiplier applied
    • Example: $0.10 payment → ~976 KB equivalent → ~976,000 tokens

  2. Admin (Private/Testing):

    • Provide Authorization: Bearer header with admin API key
    • Specify exact token count and type in request body
    • No multiplier applied (raw token count)
    • Only supports paid tokens currently
POST
/ar-io/rate-limit/ip/{ip}

Authorization

AuthorizationBearer <token>

ADMIN_API_KEY set in your .env file.

In: header

Path Parameters

ipstring

IP address

Formatipv4 or ipv6

Header Parameters

X-Payment?string

Base64-encoded x402 payment data (for x402 payment mode). Mutually exclusive with Authorization header.

Formatbase64

Request Body

Required for admin authentication mode. Omit for x402 payment mode.

tokensnumber

Number of tokens to add (admin mode only)

Range1 <= value
tokenTypestring

Type of tokens (admin mode only, currently only "paid" supported)

Value in"paid"

Response Body

curl -X POST "https://turbo-gateway.com/ar-io/rate-limit/ip/192.168.1.100" \  -H "X-Payment: string" \  -H "Content-Type: application/json" \  -d '{    "tokens": 50000,    "tokenType": "paid"  }'
{
  "ip": "192.168.1.100",
  "tokens": 95000,
  "paidTokens": 150000,
  "capacity": 100000,
  "refillRate": 20,
  "lastRefill": 1735689600000,
  "topUp": {
    "tokensAdded": 100000,
    "paymentAmount": "1000000",
    "multiplierApplied": 10,
    "tokenType": "paid"
  }
}
{
  "error": "Invalid tokens value",
  "message": "tokens must be a positive number"
}
{
  "error": "Unauthorized",
  "message": "Provide X-Payment header for x402 payment or Authorization: Bearer header for admin access"
}
{
  "error": "Payment failed",
  "message": "Payment verification failed: insufficient amount"
}
"Internal Server Error"

Query resource bucket balance

Get the current rate limit token balance for a specific resource (method + host + path combination). Useful for monitoring resource-specific usage.

Smart Defaults:

  • method: Defaults to "GET" (most common)
  • host: Defaults to current request's Host header
  • path: Required parameter
GET
/ar-io/rate-limit/resource

Query Parameters

pathstring

Request path

method?string

HTTP method

Default"GET"
Value in"GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS"
host?string

Host header (defaults to current request host)

Response Body

curl -X GET "https://turbo-gateway.com/ar-io/rate-limit/resource?path=%2FTX_ID&method=GET&host=gateway.example.com"
{
  "method": "GET",
  "host": "gateway.example.com",
  "path": "/TX_ID",
  "tokens": 980000,
  "paidTokens": 100000,
  "capacity": 1000000,
  "refillRate": 100,
  "lastRefill": 1735689600000
}
{
  "error": "Missing required parameter: path",
  "validMethods": [
    "GET",
    "POST",
    "PUT",
    "DELETE",
    "PATCH",
    "HEAD",
    "OPTIONS"
  ]
}
{
  "error": "Bucket not found",
  "message": "No rate limit bucket exists for this resource. Buckets are created on first request."
}
"Internal Server Error"

Top up resource bucket

Add paid tokens to a resource bucket via x402 payment or admin authentication. Uses same authentication modes as IP bucket top-up.

Resource Identification:

  • Combination of method + host + path uniquely identifies a resource bucket
  • Smart defaults: method=GET, host=current request host
POST
/ar-io/rate-limit/resource

Authorization

AuthorizationBearer <token>

ADMIN_API_KEY set in your .env file.

In: header

Query Parameters

pathstring

Request path

method?string

HTTP method

Default"GET"
Value in"GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS"
host?string

Host header (defaults to current request host)

Header Parameters

X-Payment?string

Base64-encoded x402 payment data (for x402 payment mode)

Formatbase64

Request Body

Required for admin authentication mode. Omit for x402 payment mode.

tokensnumber

Number of tokens to add (admin mode only)

Range1 <= value
tokenTypestring

Type of tokens (admin mode only)

Value in"paid"

Response Body

curl -X POST "https://turbo-gateway.com/ar-io/rate-limit/resource?path=%2FTX_ID&method=GET&host=gateway.example.com" \  -H "X-Payment: string" \  -H "Content-Type: application/json" \  -d '{    "tokens": 50000,    "tokenType": "paid"  }'
{
  "method": "GET",
  "host": "gateway.example.com",
  "path": "/TX_ID",
  "tokens": 980000,
  "paidTokens": 150000,
  "capacity": 1000000,
  "refillRate": 100,
  "lastRefill": 1735689600000,
  "topUp": {
    "tokensAdded": 100000,
    "paymentAmount": "1000000",
    "multiplierApplied": 10,
    "tokenType": "paid"
  }
}
{
  "error": "Missing required parameter: path",
  "validMethods": [
    "GET",
    "POST",
    "PUT",
    "DELETE",
    "PATCH",
    "HEAD",
    "OPTIONS"
  ]
}
{
  "error": "Unauthorized",
  "message": "Provide X-Payment header for x402 payment or Authorization: Bearer header for admin access"
}
{
  "error": "Payment failed",
  "message": "Payment settlement failed: timeout"
}
"Internal Server Error"

How is this guide?

Farcaster Frames

Previous Page

Turbo APIs

Upload and payment services for fast, reliable data uploads to Arweave