Agent Integration Examples

Plain PHP (no dependencies)

Simple examples using built-in PHP functions — no Composer or Guzzle needed:

// Simplest possible fetch — one line
$params = http_build_query([
    'url'    => 'https://example.com',
    'apikey' => 'YOUR_KEY',
    'tag'    => 'my_script',
]);

$json = file_get_contents("https://www.botanon.com/api/fetch?{$params}");
$data = json_decode($json, true);

if ($data['success']) {
    echo $data['body'];  // The fetched HTML
    echo "\nProxy: " . $data['proxy']['driver'];
} else {
    echo "Error: " . $data['error'];
}

// cURL for more control (timeouts, POST, headers)
function botanon_fetch(string $url, string $apikey, string $tag = 'php_curl'): array {
    $params = http_build_query([
        'url'    => $url,
        'apikey' => $apikey,
        'tag'    => $tag,
        'ua'     => 'random',
    ]);

    $ch = curl_init("https://www.botanon.com/api/fetch?{$params}");
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 30,
        CURLOPT_FOLLOWLOCATION => true,
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200 || $response === false) {
        return ['success' => false, 'error' => "HTTP {$httpCode}"];
    }
    return json_decode($response, true);
}

// Usage
$result = botanon_fetch('https://example.com', 'YOUR_KEY');
echo $result['body'];

$ch = curl_init('https://www.botanon.com/api/fetch');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode([
        'url'       => 'https://api.example.com/search',
        'apikey'    => 'YOUR_KEY',
        'method'    => 'POST',
        'post_data' => json_encode(['query' => 'AI agents']),
        'post_type' => 'json',
        'tag'       => 'search',
    ]),
]);

$data = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $data['body'];

Claude Code / MCP Tool

Use BotAnon as a fetch tool in your MCP server or Claude Code skill. Here's a complete PHP function for an MCP server:

// Example: PHP function an MCP server could use
function botanon_fetch(string $url, string $tag = 'claude_agent'): array {
    $client = new \GuzzleHttp\Client();
    $response = $client->get('https://www.botanon.com/api/fetch', [
        'query' => [
            'url' => $url,
            'apikey' => getenv('BOTANON_API_KEY'),
            'tag' => $tag,
            'ua' => 'random',
        ],
        'timeout' => 30,
    ]);
    return json_decode((string)$response->getBody(), true);
}

import os
import requests

def botanon_fetch(url: str, tag: str = "claude_agent") -> dict:
    """Fetch a URL through BotAnon for anonymous access."""
    resp = requests.get("https://www.botanon.com/api/fetch", params={
        "url": url,
        "apikey": os.environ["BOTANON_API_KEY"],
        "tag": tag,
        "ua": "random",
    }, timeout=30)
    resp.raise_for_status()
    data = resp.json()
    if not data["success"]:
        raise Exception(f"BotAnon error: {data.get('error', 'unknown')}")
    return data

Hermes / Autonomous Agents

Autonomous agents that scrape multiple URLs can loop through BotAnon with built-in rate limiting and error handling:

import requests
import time

BOTANON_API = "https://www.botanon.com/api/fetch"
API_KEY = "YOUR_KEY"

def agent_fetch(url, tag="hermes_agent"):
    resp = requests.get(BOTANON_API, params={
        "url": url,
        "apikey": API_KEY,
        "tag": tag,
        "ua": "random",
    })
    data = resp.json()
    if data["success"]:
        return data["body"]
    raise Exception(f"Fetch failed: {data.get('error', 'unknown')}")

# Agent workflow example
urls = [
    "https://example.com/pricing",
    "https://example.com/about",
    "https://example.com/contact",
]

for url in urls:
    html = agent_fetch(url)
    # Process html with your LLM...
    print(f"Fetched {url}: {len(html)} bytes")
    time.sleep(1)  # Be respectful

Node.js / TypeScript Agents

Modern Node.js with the built-in fetch API — no dependencies needed:

const BOTANON_API = 'https://www.botanon.com/api/fetch';

async function agentFetch(url, tag = 'node_agent') {
  const params = new URLSearchParams({
    url, apikey: process.env.BOTANON_API_KEY, tag, ua: 'random'
  });
  const resp = await fetch(`${BOTANON_API}?${params}`);
  const data = await resp.json();
  if (!data.success) throw new Error(data.error);
  return data;
}

// Use in your agent
const result = await agentFetch('https://example.com');
console.log(`HTTP ${result.http_code}, ${result.body_size} bytes via ${result.proxy.driver}`);

cURL / Shell Scripts

Quick command-line examples for testing or shell-based agent workflows:

curl -s 'https://www.botanon.com/api/fetch?url=https://example.com&apikey=YOUR_KEY&tag=shell' | jq .

curl -s -X POST https://www.botanon.com/api/fetch \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://api.example.com/search","apikey":"YOUR_KEY","method":"POST","post_data":"{\"q\":\"test\"}","post_type":"json"}' | jq .

curl -s --compressed 'https://www.botanon.com/api/fetch?url=https://example.com&apikey=YOUR_KEY&compress=1' | jq .

curl -s 'https://www.botanon.com/api/fetch?url=https://spa-app.com&apikey=YOUR_KEY&browser=1' | jq .body

Advanced: POST Data & Custom Headers

BotAnon supports form POSTs, JSON POSTs, and custom headers for complex API interactions:

resp = requests.post("https://www.botanon.com/api/fetch", json={
    "url": "https://example.com/login",
    "apikey": "YOUR_KEY",
    "method": "POST",
    "post_data": "username=agent&password=secret",
    "post_type": "form",
    "tag": "login_agent",
})
data = resp.json()
print(data["body"])

import json

resp = requests.post("https://www.botanon.com/api/fetch", json={
    "url": "https://api.example.com/search",
    "apikey": "YOUR_KEY",
    "method": "POST",
    "post_data": json.dumps({"query": "AI agents", "limit": 10}),
    "post_type": "json",
    "tag": "search_agent",
})
data = resp.json()
print(data["body"])

$response = $client->get('https://www.botanon.com/api/fetch', [
    'query' => [
        'url'     => 'https://tough-target.com',
        'apikey'  => 'YOUR_KEY',
        'ua'      => 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/125.0.0.0',
        'timeout' => 60,
        'browser' => 1,
        'tag'     => 'tough_target',
    ],
]);

Error Handling Best Practice

Always check the success field, implement retries with backoff, and use tags for debugging:

import requests
import time

def resilient_fetch(url, tag="my_agent", max_retries=3):
    """Fetch with automatic retries and exponential backoff."""
    for attempt in range(max_retries):
        try:
            resp = requests.get("https://www.botanon.com/api/fetch", params={
                "url": url,
                "apikey": API_KEY,
                "tag": f"{tag}_attempt_{attempt}",
                "ua": "random",
                "refresh": 1 if attempt > 0 else 0,  # Force fresh on retry
            }, timeout=30)
            data = resp.json()

            if data["success"]:
                return data

            # Non-retryable errors
            if data.get("http_code") in [404, 401, 403]:
                return data  # Don't retry client errors

        except requests.RequestException as e:
            print(f"Request error: {e}")

        if attempt < max_retries - 1:
            wait = 2 ** attempt  # 1s, 2s, 4s
            print(f"Retrying in {wait}s...")
            time.sleep(wait)

    raise Exception(f"Failed after {max_retries} attempts: {url}")

function safe_fetch(string $url, string $tag): ?array {
    try {
        $client = new \GuzzleHttp\Client();
        $response = $client->get('https://www.botanon.com/api/fetch', [
            'query' => [
                'url'    => $url,
                'apikey' => getenv('BOTANON_API_KEY'),
                'tag'    => $tag,
            ],
            'timeout' => 30,
        ]);
        $data = json_decode((string)$response->getBody(), true);

        if (!$data['success']) {
            error_log("BotAnon fetch failed [{$tag}]: " . ($data['error'] ?? 'unknown'));
            return null;
        }
        return $data;

    } catch (\Throwable $e) {
        error_log("BotAnon exception [{$tag}]: " . $e->getMessage());
        return null;
    }
}