API Reference

Everything you need to integrate with RentaTube.

Base URL: https://api.rentatube.dev/api/v1

Authentication

POST /auth/register

Create a new agent account. If walletSignature and signedMessage are provided, email verification is skipped (agent accounts only).

curl -X POST https://api.rentatube.dev/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
  "email": "[email protected]",
  "walletAddress": "0xYourEthereumAddress",
  "accountType": "agent",
  "walletSignature": "0xSignedMessage...",
  "signedMessage": "any message signed by your wallet"
}'

Request body:

email string, required — Email address

walletAddress string, required — Ethereum address (0x...)

accountType "agent" | "host" | "both" — Account type

password string, optional — Min 8 chars (optional for agents with wallet sig)

walletSignature string, optional — Signature of signedMessage by walletAddress

signedMessage string, optional — The message that was signed

Response: { data: { id, walletAddress, accountType, emailVerified: true } }

POST /auth/login

Get a JWT token. Token expires in 15 minutes.

curl -X POST https://api.rentatube.dev/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
  "email": "[email protected]",
  "walletAddress": "0xYourAddress"
}'

Response: { data: { token: "eyJ..." } }

GET /auth/api-key/challenge

Get a timestamped challenge message to sign for API key creation. No auth required.

curl https://api.rentatube.dev/api/v1/auth/api-key/challenge

Response: { data: { message: "RentaTube API Key Request: 1709500000000", timestamp: 1709500000000 } }

POST /auth/api-key

Create an API key by signing the challenge message. Requires JWT Bearer token.

curl -X POST https://api.rentatube.dev/api/v1/auth/api-key \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "walletAddress": "0xYourAddress",
  "signature": "0xSignedChallenge...",
  "message": "RentaTube API Key Request: 1709500000000"
}'

Response: { data: { apiKey: "rt_live_abc123..." } }

After this step, use X-API-Key: rt_live_... header for all subsequent requests. No more JWT needed.

Proxy API

POST /proxy Requires: API key, agent role, funded balance

Route an HTTP request through a residential IP node. The node is selected automatically based on your criteria, or you can specify a nodeId.

curl -X POST https://api.rentatube.dev/api/v1/proxy \
  -H "X-API-Key: rt_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
  "responseFormat": "text",
  "country": "US",
  "request": {
    "method": "GET",
    "url": "https://httpbin.org/ip",
    "headers": {
      "Accept": "application/json"
    },
    "timeout": 30000
  }
}'

Request body:

nodeId uuid, optional — Route through a specific node

country string(2), optional — ISO 3166-1 alpha-2 country code

minReputation number 0-100, optional — Minimum node reputation

responseFormat "base64" | "text" — Default: "base64"

request.method string, required — GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS

request.url url, required — Target URL to proxy

request.headers object, optional — Headers to forward

request.body string, optional — Body for POST/PUT/PATCH

request.timeout number, optional — 1000-120000ms (default: 30000)

Response:

{
  "data": {
    "response": {
      "statusCode": 200,
      "headers": {
        "content-type": "application/json"
      },
      "body": "{\"origin\":\"73.162.xxx.xxx\"}"
    },
    "meta": {
      "nodeId": "a1b2c3d4-...",
      "nodeCountry": "US",
      "responseTimeMs": 142,
      "paymentAmount": "0.00100000",
      "remainingBalance": "9.99900000"
    }
  },
  "error": null
}

Node Discovery

GET /discover Requires: API key, agent role

List available proxy nodes. Only returns nodes with a live heartbeat.

curl -H "X-API-Key: rt_live_..." \
  "https://api.rentatube.dev/api/v1/discover?country=US&minReputation=50&limit=10"

Query parameters:

country string(2), optional — ISO 3166-1 alpha-2

minReputation number, optional — Min reputation (0-100)

maxPrice string, optional — Max USDC per request

page number, optional — Default: 1

limit number, optional — Default: 20, max: 100

Response item:

{
  "id": "a1b2c3d4-...",
  "country": "US",
  "city": "New York",
  "status": "online",
  "pricePerRequest": "0.00100000",
  "reputationScore": 85,
  "totalRequests": 15420,
  "maxConcurrent": 15
}

Dev Faucet

POST /dev/faucet Non-production only

Get free testnet USDC for development. Max 100 USDC per account lifetime. Rate limited to 10 calls/hour per IP.

curl -X POST https://api.rentatube.dev/api/v1/dev/faucet \
  -H "Content-Type: application/json" \
  -d '{
  "accountId": "your-account-uuid",
  "amount": "10.00000000"
}'

Response: { data: { credited: "10", escrowBalance: "10", faucetRemaining: "90" } }

Error Codes

All errors return { data: null, error: { code: string, message: string } } with an appropriate HTTP status code.

INVALID_CREDENTIALS 401 API key or JWT token is invalid or expired

ROLE_NOT_ALLOWED 403 Account type does not have the required role

DOMAIN_BLOCKED 403 Target domain is blocked by platform or host

INSUFFICIENT_BALANCE 402 Not enough USDC in escrow balance

NO_NODES_AVAILABLE 503 No online nodes match your criteria

NODE_NOT_FOUND 404 The specified nodeId does not exist

NODE_OFFLINE 503 The specified node is not currently online

UPSTREAM_TIMEOUT 504 Target server did not respond within timeout

UPSTREAM_ERROR 502 Target server connection failed

INVALID_WALLET_SIGNATURE 400 Wallet signature does not match wallet address

RATE_LIMITED 429 Too many requests, slow down

ACCOUNT_NOT_FOUND 404 Account ID not found

FAUCET_LIMIT_EXCEEDED 400 Faucet lifetime cap exceeded (max 100 USDC)

Host Quick Start

Install the CLI

npm install -g @rentatube/cli

rentatube register --type host

rentatube host config --price 0.001 --max-concurrent 15

Connect your wallet, verify email, and set pricing. You'll need a Base L2 wallet for USDC payments.

Start earning

rentatube host start

Your node goes live. Every proxied request earns you USDC. Settlements daily. Withdraw anytime.

CLI Commands

rentatube register --type <host|agent> — Create a new account

rentatube login — Login with email/wallet

rentatube deposit <amount> — Deposit USDC to escrow

rentatube balance — Check your escrow balance

rentatube withdraw <amount> — Withdraw USDC from escrow

rentatube proxy <url> — Route a single request through the network

rentatube nodes — List available proxy nodes

rentatube config --key — Show or generate your API key

rentatube host config — Configure host node settings

rentatube host start — Start hosting your node

rentatube host stop — Stop hosting

rentatube host stats — Show earnings and request stats

Need help?

Open an issue on GitHub or reach out on Discord.