How to Integrate a Residential Proxy API in 5 Minutes

Getting a residential proxy working in your AI agent shouldn’t require reading 30 pages of documentation. This tutorial walks through the complete flow — from registration to your first proxied request — using the RentaTube API. Everything is done through REST endpoints, so it works with any language or framework.

Prerequisites

Before you start, you’ll need:

• An Ethereum wallet (any EOA — MetaMask, a CLI wallet, or a programmatic signer).
• USDC on Base L2 (for funding your proxy balance).
• curl or Python with the requests library for testing.

That’s it. No email address, no account application, no waiting for approval.

Step 1: Register Your Agent

RentaTube uses wallet-based authentication. You sign a message with your Ethereum private key, and the API creates your account and returns an API key.

Generate the Signature

First, sign the registration message. The message format is a simple string that the API expects. Here’s how to do it with cast (from Foundry):

# The message to sign
MESSAGE="Register for RentaTube"

# Sign with your private key (replace with your actual key)
SIGNATURE=$(cast wallet sign --private-key $PRIVATE_KEY "$MESSAGE")

echo $SIGNATURE

If you’re using Python with eth_account:

from eth_account import Account
from eth_account.messages import encode_defunct

private_key = "0xYOUR_PRIVATE_KEY"
message = "Register for RentaTube"

account = Account.from_key(private_key)
signed = account.sign_message(encode_defunct(text=message))

print(f"Address: {account.address}")
print(f"Signature: {signed.signature.hex()}")

Call the Registration Endpoint

curl -X POST https://api.rentatube.dev/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "walletAddress": "0xYOUR_WALLET_ADDRESS",
    "signature": "0xYOUR_SIGNATURE",
    "message": "Register for RentaTube"
  }'

The response includes your API key:

{
  "apiKey": "rt_live_abc123...",
  "walletAddress": "0xYOUR_WALLET_ADDRESS"
}

Save this API key. You’ll use it for all subsequent requests.

Using the CLI

Alternatively, you can register using the RentaTube CLI:

# Install the CLI
npm install -g @rentatube/cli

# Register (this handles signing for you)
rentatube auth register --private-key $PRIVATE_KEY

Step 2: Fund Your Balance

Before making proxy requests, you need USDC in your RentaTube balance. The funding flow works on Base L2, so gas fees are minimal (fractions of a cent).

Check Your Current Balance

curl -X GET https://api.rentatube.dev/api/v1/balance \
  -H "Authorization: Bearer rt_live_abc123..."

Response:

{
  "balance": "0.000000",
  "currency": "USDC"
}

Deposit USDC

Send USDC on Base L2 to the deposit address provided by the API:

curl -X GET https://api.rentatube.dev/api/v1/balance/deposit-address \
  -H "Authorization: Bearer rt_live_abc123..."

{
  "depositAddress": "0xDEPOSIT_CONTRACT_ADDRESS",
  "network": "base",
  "currency": "USDC"
}

Transfer USDC to that address on Base. Once confirmed, your balance updates automatically. Even a small deposit like $1.00 gives you 1,000 requests at the base rate.

Step 3: Make a Proxy Request

Now the good part. Making a proxied request is a single API call.

Basic Request with curl

curl -X POST https://api.rentatube.dev/api/v1/proxy/request \
  -H "Authorization: Bearer rt_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://httpbin.org/ip",
    "method": "GET"
  }'

Response:

{
  "statusCode": 200,
  "headers": { ... },
  "body": "{\"origin\": \"73.42.198.xxx\"}",
  "proxyIp": "73.42.198.xxx",
  "country": "US",
  "cost": "0.001000"
}

The origin in the response body is the residential IP that was used — not your server’s IP.

Request with Geo-Targeting

Need a response from a specific country? Add the country parameter:

curl -X POST https://api.rentatube.dev/api/v1/proxy/request \
  -H "Authorization: Bearer rt_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://httpbin.org/ip",
    "method": "GET",
    "country": "DE"
  }'

This routes through a German residential IP. Use any ISO 3166-1 alpha-2 country code.

Request with Custom Headers

Pass custom headers to the target site:

curl -X POST https://api.rentatube.dev/api/v1/proxy/request \
  -H "Authorization: Bearer rt_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/api/data",
    "method": "GET",
    "headers": {
      "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
      "Accept-Language": "en-US,en;q=0.9"
    }
  }'

Step 4: Integrate in Python

Here’s a complete Python example that ties it all together:

import requests

API_KEY = "rt_live_abc123..."
BASE_URL = "https://api.rentatube.dev/api/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

def proxy_request(url: str, method: str = "GET", country: str = None) -> dict:
    """Make a proxied request through a residential IP."""
    payload = {
        "url": url,
        "method": method,
    }
    if country:
        payload["country"] = country

    response = requests.post(
        f"{BASE_URL}/proxy/request",
        headers=headers,
        json=payload
    )
    response.raise_for_status()
    return response.json()

# Basic request
result = proxy_request("https://httpbin.org/ip")
print(f"Residential IP used: {result['proxyIp']}")
print(f"Cost: ${result['cost']} USDC")

# Geo-targeted request (UK)
uk_result = proxy_request("https://httpbin.org/ip", country="GB")
print(f"UK IP used: {uk_result['proxyIp']}")

# Check remaining balance
balance = requests.get(f"{BASE_URL}/balance", headers=headers).json()
print(f"Remaining balance: ${balance['balance']} USDC")

Step 5: Add to Your AI Agent

If your agent uses an LLM framework like LangChain or a custom loop, wrap the proxy function as a tool:

def fetch_webpage(url: str, country: str = None) -> str:
    """Fetch a webpage through a residential proxy.
    Returns the page content as text.
    """
    result = proxy_request(url, method="GET", country=country)

    if result["statusCode"] == 200:
        return result["body"]
    else:
        return f"Error: HTTP {result['statusCode']}"

Your agent now has access to the web through residential IPs, and every request is metered at $0.001 USDC.

Error Handling

A production integration should handle common error cases:

def proxy_request_safe(url: str, method: str = "GET", country: str = None, retries: int = 2) -> dict:
    """Proxied request with basic retry logic."""
    for attempt in range(retries + 1):
        try:
            result = proxy_request(url, method, country)

            if result["statusCode"] in (200, 201, 301, 302):
                return result

            if result["statusCode"] == 429:
                # Rate limited by target -- wait and retry
                time.sleep(2 ** attempt)
                continue

            return result  # Return non-retryable errors as-is

        except requests.exceptions.RequestException as e:
            if attempt == retries:
                raise
            time.sleep(1)

    return result

What You’ve Accomplished

In about five minutes, you’ve:

1. Registered an agent account with a wallet signature.
2. Funded the account with USDC on Base L2.
3. Made proxied HTTP requests through residential IPs.
4. Added geo-targeting to route through specific countries.
5. Wrapped it all in a Python function ready for your AI agent.

The complete flow is stateless and API-driven. There’s no proxy configuration file, no SOCKS5 setup, no browser extension. Your agent makes an HTTP POST, gets a response from a residential IP, and pays $0.001 per request. That’s the entire integration.

For the full API reference, see the documentation at RentaTube. The CLI (npm install -g @rentatube/cli) provides the same functionality from the command line if you prefer that workflow.