Hyperbrowser

https://www.hyperbrowser.ai/docs
Admin
Hyperbrowser provides fast, reliable cloud browsers for AI automation, large-scale web scraping, and...
Tokens:561,306
Snippets:4,062
Trust Score:7.9
Update:3 hours ago
Show doc for...
Tokens:
Raw
### Quickstart example

Source: https://www.hyperbrowser.ai/docs/hyperagent/overview

A minimal example that initializes HyperAgent, navigates to Hacker News, and uses page.ai() to find and summarize the top story. This is the quickest way to get started with HyperAgent.

```javascript
import { HyperAgent } from "@hyperbrowser/agent";

const agent = new HyperAgent();
const page = await agent.newPage();

await page.goto("https://news.ycombinator.com");
await page.ai("find the top story and summarize it");

await agent.closeAgent();
```

--------------------------------

### Python 1.0+ example with URL filters

Source: https://www.hyperbrowser.ai/docs/web/crawl

Python 1.0+ example using the Hyperbrowser SDK to start a crawl with crawl_options.

```python
import os
from dotenv import load_dotenv
from hyperbrowser import Hyperbrowser

load_dotenv()

client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))

result = client.web.crawl.start_and_wait(
    {
        "url": "https://example.com",
        "crawl_options": {
            "max_pages": 50,
            "follow_links": True,
            "include_patterns": ["/docs/*", "/blog/*"],
            "exclude_patterns": ["/docs/archive/*"],
        },
    }
)

print(result)
```

--------------------------------

### Start Crawl with Options (Python 1.0+)

Source: https://www.hyperbrowser.ai/docs/web-scraping/crawl

Python example using the Hyperbrowser client to start a crawl and wait for completion, with max_pages, follow_links, and ignore_sitemap options.

```python
import os
from dotenv import load_dotenv
from hyperbrowser import Hyperbrowser

# Load environment variables from .env file
load_dotenv()

# Initialize Hyperbrowser client
client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))


# Start crawling and wait for completion
crawl_result = client.crawl.start_and_wait(
    {
        "url": "https://example.com",
        "max_pages": 50,
        "follow_links": True,
        "ignore_sitemap": False,
    }
)
print("Crawl result:\n", crawl_result.model_dump_json(indent=2))
```

--------------------------------

### Start Crawl with Options (Python legacy)

Source: https://www.hyperbrowser.ai/docs/web-scraping/crawl

Legacy Python example using StartCrawlJobParams to start a crawl and wait for completion, with max_pages, follow_links, and ignore_sitemap options.

```python
import os
from dotenv import load_dotenv
from hyperbrowser import Hyperbrowser
from hyperbrowser.models import StartCrawlJobParams

# Load environment variables from .env file
load_dotenv()

# Initialize Hyperbrowser client
client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))


# Start crawling and wait for completion
crawl_result = client.crawl.start_and_wait(
    StartCrawlJobParams(
        url="https://example.com", max_pages=50, follow_links=True, ignore_sitemap=False
    )
)
print("Crawl result:\n", crawl_result.model_dump_json(indent=2))
```

--------------------------------

### SDK Usage Examples

Source: https://www.hyperbrowser.ai/docs/web-scraping/crawl

Examples of using the Hyperbrowser SDK to start a crawl job and wait for completion in Node.js and Python.

```APIDOC
## SDK Usage Examples

### Description
Examples of using the Hyperbrowser SDK to start a crawl job and wait for completion in Node.js and Python.

### Node.js
```javascript
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

const main = async () => {
  const crawlResult = await client.crawl.startAndWait({
    url: "https://example.com",
    maxPages: 50,
    followLinks: true,
    ignoreSitemap: false,
  });
  console.log("Crawl result:", crawlResult);
};

main();
```

### Python (1.0+)
```python
import os
from dotenv import load_dotenv
from hyperbrowser import Hyperbrowser

# Load environment variables from .env file
load_dotenv()

# Initialize Hyperbrowser client
client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))


# Start crawling and wait for completion
crawl_result = client.crawl.start_and_wait(
    {
        "url": "https://example.com",
        "max_pages": 50,
        "follow_links": True,
        "ignore_sitemap": False,
    }
)
print("Crawl result:\n", crawl_result.model_dump_json(indent=2))
```

### Python (legacy)
```python
import os
from dotenv import load_dotenv
from hyperbrowser import Hyperbrowser
from hyperbrowser.models import StartCrawlJobParams

# Load environment variables from .env file
load_dotenv()

# Initialize Hyperbrowser client
client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))


# Start crawling and wait for completion
crawl_result = client.crawl.start_and_wait(
    StartCrawlJobParams(
        url="https://example.com", max_pages=50, follow_links=True, ignore_sitemap=False
    )
)
print("Crawl result:\n", crawl_result.model_dump_json(indent=2))
```
```

--------------------------------

### Install X402 dependencies

Source: https://www.hyperbrowser.ai/docs/integrations/x402/fetch

Install the required npm packages for the X402 fetch example, including the X402 SDKs, wallet libraries, and dotenv. Also installs tsx as a dev dependency to run TypeScript files.

```bash
npm install @x402/fetch @x402/core @x402/evm @x402/svm viem @solana/kit @scure/base dotenv
npm install --save-dev tsx
```

--------------------------------

### Start Crawl with Options (Node.js)

Source: https://www.hyperbrowser.ai/docs/web-scraping/crawl

Node.js example using the Hyperbrowser SDK to start a crawl and wait for completion, with maxPages, followLinks, and ignoreSitemap options.

```typescript
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

const main = async () => {
  const crawlResult = await client.crawl.startAndWait({
    url: "https://example.com",
    maxPages: 50,
    followLinks: true,
    ignoreSitemap: false,
  });
  console.log("Crawl result:", crawlResult);
};

main();
```

--------------------------------

### Node.js startAndWait() example

Source: https://www.hyperbrowser.ai/docs/agents/jev-computer-use

Uses the Hyperbrowser SDK to start a Jev task and wait for the result. Requires HYPERBROWSER_API_KEY environment variable.

```javascript
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

async function main() {
  const result = await client.agents.jevComputerUse.startAndWait({
    task: "Go to Hacker News and tell me the title of the top post",
    maxSteps: 20,
  });

  console.log(`Output:\n${result.data?.finalResult}`);
}

main().catch((err) => {
  console.error(`Error: ${err.message}`);
});
```

--------------------------------

### Install Hyperbrowser MCP server with npx

Source: https://www.hyperbrowser.ai/docs/integrations/model-context-protocol

Run this command to install and start the Hyperbrowser MCP server. Requires Node.js v14 or later and npm or yarn.

```bash
npx hyperbrowser-mcp
```

--------------------------------

### Python (legacy) start_and_wait() example

Source: https://www.hyperbrowser.ai/docs/agents/jev-computer-use

Uses the Hyperbrowser Python SDK (legacy) with StartJevComputerUseTaskParams to start a Jev task and wait for the result. Requires HYPERBROWSER_API_KEY environment variable.

```python
from hyperbrowser import Hyperbrowser
from hyperbrowser.models import StartJevComputerUseTaskParams
import os
from dotenv import load_dotenv

load_dotenv()

client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))

result = client.agents.jev_computer_use.start_and_wait(
    params=StartJevComputerUseTaskParams(
        task="Go to Hacker News and tell me the title of the top post", max_steps=20
    )
)

print(f"Output:\n{result.data.final_result}")
```

--------------------------------

### Python 1.0+ start_and_wait() example

Source: https://www.hyperbrowser.ai/docs/agents/jev-computer-use

Uses the Hyperbrowser Python SDK (v1.0+) to start a Jev task and wait for the result. Requires HYPERBROWSER_API_KEY environment variable.

```python
from hyperbrowser import Hyperbrowser
import os
from dotenv import load_dotenv

load_dotenv()

client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))

result = client.agents.jev_computer_use.start_and_wait(
    params={
        "task": "Go to Hacker News and tell me the title of the top post",
        "max_steps": 20,
    }
)

print(f"Output:\n{result.data.final_result}")
```

--------------------------------

### Node.js Example: Get Downloads with OpenAI CUA

Source: https://www.hyperbrowser.ai/docs/sessions/downloads

This Node.js example uses the Hyperbrowser SDK to create a session with saveDownloads set to true, start an OpenAI CUA agent task, and poll for the download zip to be ready. It demonstrates the getDownloadsURL() method and handles the completed or failed statuses.

```typescript
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

async function sleep(ms: number) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

async function waitForDownload(sessionId, timeout = 15_000) {
  const maxRetries = timeout / 1000;
  let retries = 0;
  while (retries < maxRetries) {
    console.log(
      `Waiting for download zip to be ready... (${retries + 1}/${maxRetries})`
    );
    const downloadsResponse = await client.sessions.getDownloadsURL(sessionId);
    if (
      downloadsResponse.status === "completed" ||
      downloadsResponse.status === "failed"
    ) {
      return downloadsResponse;
    }
    await sleep(1000);
    retries++;
  }
  throw new Error(`Download zip not ready after ${timeout}ms`);
}

async function main() {
  const session = await client.sessions.create({
    saveDownloads: true,
  });
  console.log("Session created:", session.id);

  try {
    const resp = await client.agents.cua.startAndWait({
      task: "1. Go to this site https://browser-tests-alpha.vercel.app/api/download-test. 2. Click on the Download File link once, then end the task. Do not wait or double check the download, just end the task.",
      sessionId: session.id,
    });

    console.log("Status:", resp.status);
    console.log("Final result:", resp.data?.finalResult);

    await sleep(3000);

    // Wait for the zipped downloads to be uploaded to our storage
    const downloadsResponse = await waitForDownload(session.id);

    console.log("downloadsResponse", downloadsResponse);
  } catch (err) {
    console.error(`Encountered error: ${err}`);
  } finally {
    await client.sessions.stop(session.id);
  }
}

main().catch(console.error);
```

--------------------------------

### Quick Start

Source: https://www.hyperbrowser.ai/docs/sdks/node

Initialize the Hyperbrowser client with your API key.

```APIDOC
## Quick Start

### Initialize Client
```typescript
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});
```
```

--------------------------------

### Python (legacy) quick start with StartGeminiComputerUseTaskParams

Source: https://www.hyperbrowser.ai/docs/agents/gemini-computer-use

Legacy Python example using the Hyperbrowser SDK's start_and_wait method with the StartGeminiComputerUseTaskParams model. It loads the API key from environment variables and prints the final result.

```python
from hyperbrowser import Hyperbrowser
from hyperbrowser.models import StartGeminiComputerUseTaskParams
import os
from dotenv import load_dotenv

load_dotenv()

client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))

result = client.agents.gemini_computer_use.start_and_wait(
    params=StartGeminiComputerUseTaskParams(
        task="Go to Hacker News and tell me the title of the top post", max_steps=20
    )
)

print(f"Output:\n{result.data.final_result}")
```

--------------------------------

### Install playwright-core and tsx

Source: https://www.hyperbrowser.ai/docs/integrations/x402/sessions

Install the required packages to run the TypeScript example. Use npm to install playwright-core and tsx as a dev dependency.

```bash
npm install playwright-core
npm install --save-dev tsx
```

--------------------------------

### Python 1.0+ quick start with start_and_wait

Source: https://www.hyperbrowser.ai/docs/agents/gemini-computer-use

Python 1.0+ example using the Hyperbrowser SDK's start_and_wait method to run a Gemini Computer Use task. It loads the API key from environment variables and prints the final result.

```python
from hyperbrowser import Hyperbrowser
import os
from dotenv import load_dotenv

load_dotenv()

client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))

result = client.agents.gemini_computer_use.start_and_wait(
    params={
        "task": "Go to Hacker News and tell me the title of the top post",
        "max_steps": 20,
    }
)

print(f"Output:\n{result.data.final_result}")
```

--------------------------------

### Get Response

Source: https://www.hyperbrowser.ai/docs/sandboxes/volumes/managing

Example JSON response from getting a volume, showing the volume ID and name.

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "my-workspace"
}
```

--------------------------------

### cURL commands for starting and checking crawl jobs

Source: https://www.hyperbrowser.ai/docs/web-scraping/crawl

Three cURL commands: start a crawl job with POST, get job status, and get job status with data. Replace <YOUR_API_KEY> and {jobId} with actual values.

```bash
# Start Crawl Job
curl -X POST https://api.hyperbrowser.ai/api/crawl \
    -H 'Content-Type: application/json' \
    -H 'x-api-key: <YOUR_API_KEY>' \
    -d '{
        "url": "https://example.com",
        "maxPages": 10,
        "followLinks": true
    }'
```

```bash
# Get Crawl Job Status
curl https://api.hyperbrowser.ai/api/crawl/{jobId}/status \
    -H 'x-api-key: <YOUR_API_KEY>'
```

```bash
# Get Crawl Job Status and Data
curl https://api.hyperbrowser.ai/api/crawl/{jobId} \
    -H 'x-api-key: <YOUR_API_KEY>'
```

--------------------------------

### Node.js quick start with startAndWait

Source: https://www.hyperbrowser.ai/docs/agents/gemini-computer-use

Node.js example using the Hyperbrowser SDK's startAndWait method to run a Gemini Computer Use task. It loads the API key from environment variables and prints the final result.

```javascript
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

async function main() {
  const result = await client.agents.geminiComputerUse.startAndWait({
    task: "Go to Hacker News and tell me the title of the top post",
    maxSteps: 20,
  });

  console.log(`Output:\n${result.data?.finalResult}`);
}

main().catch((err) => {
  console.error(`Error: ${err.message}`);
});
```

--------------------------------

### Grok Computer Use Quick Start with Python 1.0+

Source: https://www.hyperbrowser.ai/docs/agents/grok-computer-use

Use the start_and_wait() method with a params dictionary to run a Grok Computer Use task.

```python
from hyperbrowser import Hyperbrowser
import os
from dotenv import load_dotenv

load_dotenv()

client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))

result = client.agents.grok_computer_use.start_and_wait(
    params={
        "task": "Go to Hacker News and tell me the title of the top post",
        "max_steps": 20,
    }
)

print(f"Output:\n{result.data.final_result}")
```

--------------------------------

### Browser-Use Quick Start with Python 1.0+

Source: https://www.hyperbrowser.ai/docs/agents/browser-use

Uses start_and_wait() with a params dictionary to run a Browser-Use task. Requires HYPERBROWSER_API_KEY environment variable.

```python
from hyperbrowser import Hyperbrowser
import os
from dotenv import load_dotenv

load_dotenv()

client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))

result = client.agents.browser_use.start_and_wait(
    params={
        "task": "Go to Hacker News and tell me the title of the top post",
        "llm": "gemini-2.5-flash",
        "max_steps": 20,
    }
)

print(f"Output:\n{result.data.final_result}")
```

--------------------------------

### Ruby request to get sandbox images

Source: https://www.hyperbrowser.ai/docs/api-reference/get-list-of-sandbox-images

Ruby example using net/http to GET /api/images. Replace <api-key> with your API key.

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.hyperbrowser.ai/api/images")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### Python 1.0+: Create sandbox, start server, expose with auth, and build preview URL

Source: https://www.hyperbrowser.ai/docs/sandboxes/runtime

Creates a Python sandbox, starts an HTTP server on port 3000, exposes it with auth enabled, and constructs a browser URL with a 'next' query parameter pointing to '/preview'. Uses the hyperbrowser SDK's client.sandboxes.create and sandbox.expose methods.

```python
import time
from urllib.parse import parse_qsl, urlencode, urlparse, urlunparse

sandbox = client.sandboxes.create(
    {
        "image_name": "python",
    }
)

sandbox.processes.start(
    '''python3 -c "from http.server import BaseHTTPRequestHandler, HTTPServer

class Handler(BaseHTTPRequestHandler):
    def do_GET(self):
        if self.path == '/preview':
            body = b'<h1>Sandbox Preview</h1><p>Protected by sandbox auth.</p>'
            self.send_response(200)
            self.send_header('Content-Type', 'text/html')
            self.send_header('Content-Length', str(len(body)))
            self.end_headers()
            self.wfile.write(body)
            return

        self.send_response(404)
        self.end_headers()

    def log_message(self, format, *args):
        pass

HTTPServer(('0.0.0.0', 3000), Handler).serve_forever()"'''
)

time.sleep(1)

exposure = sandbox.expose(
    {
        "port": 3000,
        "auth": True,
    }
)

parsed = urlparse(exposure.browser_url)
query = dict(parse_qsl(parsed.query))
query["next"] = "/preview"
browser_url = urlunparse(parsed._replace(query=urlencode(query)))

print(f"Open preview URL: {browser_url}")
```

--------------------------------

### Go request to get sandbox images

Source: https://www.hyperbrowser.ai/docs/api-reference/get-list-of-sandbox-images

Go example using net/http to GET /api/images. Replace <api-key> with your API key.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.hyperbrowser.ai/api/images"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Ruby request to get task status

Source: https://www.hyperbrowser.ai/docs/api-reference/get-meta-computer-use-task-status

Ruby example using net/http to send a GET request to the endpoint. Prints the response body.

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.hyperbrowser.ai/api/task/meta-computer-use/{id}/status")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### Create Sandbox (Python 1.0+)

Source: https://www.hyperbrowser.ai/docs/sdks/python

Starts a sandbox from an image using client.sandboxes.create(...). Requires image_name unless restoring from a snapshot; optional region, timeout, recording, and exposed ports.

```python
sandbox = client.sandboxes.create(
    {
        "image_name": "node",  # required unless restoring from a snapshot
        "region": "us-west",  # optional: sandbox region
        "timeout_minutes": 30,  # optional: max sandbox lifetime
        "enable_recording": True,  # optional: record the sandbox
        "exposed_ports": [{"port": 3000, "auth": True}],  # optional
    }
)
```

--------------------------------

### Start From A Snapshot (Python 1.0+)

Source: https://www.hyperbrowser.ai/docs/sdks/python

Starts a new sandbox from a memory checkpoint using client.sandboxes.create(...). Requires snapshot_name; snapshot_id optionally pins a specific snapshot version.

```python
sandbox = client.sandboxes.create(
    {
        "snapshot_name": "node-after-setup",  # required: snapshot name
        "snapshot_id": "snapshot-id",  # optional: pin a specific snapshot version
    }
)
```

--------------------------------

### Go request to get task status

Source: https://www.hyperbrowser.ai/docs/api-reference/get-meta-computer-use-task-status

Go example using net/http to send a GET request to the endpoint. Prints the response body.

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.hyperbrowser.ai/api/task/meta-computer-use/{id}/status"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Java Unirest request to get sandbox images

Source: https://www.hyperbrowser.ai/docs/api-reference/get-list-of-sandbox-images

Java example using Unirest to GET /api/images. Replace <api-key> with your API key.

```java
HttpResponse<String> response = Unirest.get("https://api.hyperbrowser.ai/api/images")
  .header("x-api-key", "<api-key>")
  .asString();
```

--------------------------------

### Grok Computer Use Quick Start with Python (legacy)

Source: https://www.hyperbrowser.ai/docs/agents/grok-computer-use

Use the start_and_wait() method with a StartGrokComputerUseTaskParams object for the legacy Python SDK.

```python
from hyperbrowser import Hyperbrowser
from hyperbrowser.models import StartGrokComputerUseTaskParams
import os
from dotenv import load_dotenv

load_dotenv()

client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))

result = client.agents.grok_computer_use.start_and_wait(
    params=StartGrokComputerUseTaskParams(
        task="Go to Hacker News and tell me the title of the top post", max_steps=20
    )
)

print(f"Output:\n{result.data.final_result}")
```

--------------------------------

### PHP cURL request to get sandbox images

Source: https://www.hyperbrowser.ai/docs/api-reference/get-list-of-sandbox-images

PHP example using cURL to GET /api/images. Replace <api-key> with your API key.

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.hyperbrowser.ai/api/images",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

--------------------------------

### Fetch a page with X402 TypeScript client

Source: https://www.hyperbrowser.ai/docs/integrations/x402/fetch

Save this as `fetch.ts`. It sets up an X402 client with EVM and/or Solana signers, wraps the global fetch with payment handling, and posts a fetch request to the X402 endpoint. If your keys are in `.env.agent`, replace `dotenv.config()` with `dotenv.config({ path: ".env.agent" })`. The example requests markdown and links formats for example.com and logs the result and payment settlement.

```typescript
import dotenv from "dotenv";
import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client, x402HTTPClient } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { registerExactSvmScheme } from "@x402/svm/exact/client";
import { privateKeyToAccount } from "viem/accounts";
import { createKeyPairSignerFromBytes } from "@solana/kit";
import { base58 } from "@scure/base";

dotenv.config();

async function main() {
  const evmKey = process.env.EVM_PRIVATE_KEY;
  const solanaKey = process.env.SOLANA_PRIVATE_KEY;
  if (!evmKey && !solanaKey) {
    throw new Error("Set EVM_PRIVATE_KEY or SOLANA_PRIVATE_KEY in .env");
  }

  const client = new x402Client();

  if (evmKey) {
    registerExactEvmScheme(client, {
      signer: privateKeyToAccount(evmKey as `0x${string}`),
    });
  }

  if (solanaKey) {
    const signer = await createKeyPairSignerFromBytes(base58.decode(solanaKey));
    registerExactSvmScheme(client, { signer });
  }

  const fetchWithPayment = wrapFetchWithPayment(fetch, client);
  const response = await fetchWithPayment(
    "https://api.hyperbrowser.ai/x402/web/fetch",
    {
      method: "POST",
      signal: AbortSignal.timeout(60_000),
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        url: "https://example.com",
        outputs: { formats: ["markdown", "links"] },
      }),
    }
  );

  const data = await response.json();
  if (!response.ok) {
    throw new Error(
      `Fetch failed (${response.status}): ${JSON.stringify(data)}`
    );
  }

  console.log("Fetch result:", JSON.stringify(data, null, 2));

  const httpClient = new x402HTTPClient(client);
  console.log(
    "Payment settled:",
    httpClient.getPaymentSettleResponse((name) => response.headers.get(name))
  );
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});
```

--------------------------------

### JavaScript fetch request to get sandbox images

Source: https://www.hyperbrowser.ai/docs/api-reference/get-list-of-sandbox-images

JavaScript example using fetch to GET /api/images. Replace <api-key> with your API key.

```javascript
const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.hyperbrowser.ai/api/images', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
```

--------------------------------

### Start Meta Computer Use Task with Go

Source: https://www.hyperbrowser.ai/docs/api-reference/start-a-meta-computer-use-task

Uses net/http to POST a task to the Meta Computer Use endpoint. Requires an API key.

```Go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.hyperbrowser.ai/api/task/meta-computer-use"

	payload := strings.NewReader("{\n  \"task\": \"go to example.com\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Python request to get sandbox images

Source: https://www.hyperbrowser.ai/docs/api-reference/get-list-of-sandbox-images

Python example using the requests library to GET /api/images. Replace <api-key> with your API key.

```python
import requests

url = "https://api.hyperbrowser.ai/api/images"

headers = {"x-api-key": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)
```

--------------------------------

### Run the TypeScript fetch example

Source: https://www.hyperbrowser.ai/docs/integrations/x402/fetch

Run the `fetch.ts` file with tsx to execute the X402 fetch example.

```bash
npx tsx fetch.ts
```

--------------------------------

### Node.js example with URL filters

Source: https://www.hyperbrowser.ai/docs/web/crawl

Node.js example using the Hyperbrowser SDK to start a crawl with crawlOptions including maxPages, followLinks, includePatterns, and excludePatterns.

```javascript
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

const result = await client.web.crawl.startAndWait({
  url: "https://example.com",
  crawlOptions: {
    maxPages: 50,
    followLinks: true,
    includePatterns: ["/docs/*", "/blog/*"],
    excludePatterns: ["/docs/archive/*"],
  },
});

console.log(result);
```

--------------------------------

### Grok Computer Use Quick Start with Node.js

Source: https://www.hyperbrowser.ai/docs/agents/grok-computer-use

Use the startAndWait() method to run a Grok Computer Use task and print the final result.

```javascript
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

async function main() {
  const result = await client.agents.grokComputerUse.startAndWait({
    task: "Go to Hacker News and tell me the title of the top post",
    maxSteps: 20,
  });

  console.log(`Output:\n${result.data?.finalResult}`);
}

main().catch((err) => {
  console.error(`Error: ${err.message}`);
});
```

--------------------------------

### Java Unirest request to get task status

Source: https://www.hyperbrowser.ai/docs/api-reference/get-meta-computer-use-task-status

Java example using Unirest to send a GET request to the endpoint. Requires the Unirest library.

```java
HttpResponse<String> response = Unirest.get("https://api.hyperbrowser.ai/api/task/meta-computer-use/{id}/status")
  .header("x-api-key", "<api-key>")
  .asString();
```

--------------------------------

### sandbox.processes.start(command, options?)

Source: https://www.hyperbrowser.ai/docs/sandboxes/processes

Starts a background process in the sandbox. Returns a process handle that can be used to write to stdin, wait for completion, stream output, and signal the process.

```APIDOC
## sandbox.processes.start(command, options?)

### Description
Starts a background process in the sandbox. Returns a process handle that can be used to write to stdin, wait for completion, stream output, and signal the process.

### Method
SDK Method

### Endpoint
`sandbox.processes.start(command, options?)`

### Parameters
- **command** (string) - Required - Command to run inside the sandbox.
- **options** (object) - Optional - Options for the process.
  - **runAs** (string) - Optional - Run the command as a specific sandbox user, for example `root`.

### Request Example
```javascript
const process = await sandbox.processes.start("read line; echo stdout:$line; echo stderr:$line 1>&2", { runAs: "root" });
```

### Response
#### Success Response
Returns a process handle with methods:
- **writeStdin(data)** - Writes data to the process's stdin. Accepts `{ data: string, eof: boolean }`.
- **wait()** - Waits for the process to exit and returns the result with stdout and stderr.
- **stream()** - Returns an async iterator of events (stdout, stderr, exit).
- **signal(signal)** - Sends a signal to the process (e.g., "TERM").
- **id** (string) - The process ID.

#### Response Example
```javascript
const process = await sandbox.processes.start("sleep 30", { runAs: "root" });
```
```

--------------------------------

### PHP cURL request to get task status

Source: https://www.hyperbrowser.ai/docs/api-reference/get-meta-computer-use-task-status

PHP example using cURL to send a GET request to the endpoint. Requires the cURL extension.

```php
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.hyperbrowser.ai/api/task/meta-computer-use/{id}/status",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```

--------------------------------

### Browser-Use agent quickstart in Python (legacy)

Source: https://www.hyperbrowser.ai/docs/agents/overview

Runs a Browser-Use agent with `start_and_wait()` using the Hyperbrowser Python SDK (legacy version). Requires `HYPERBROWSER_API_KEY` environment variable. Uses the `StartBrowserUseTaskParams` model for parameters. The task asks for the top post title on Hacker News, using the `gemini-2.0-flash` LLM and a maximum of 20 steps.

```Python
from hyperbrowser import Hyperbrowser
from hyperbrowser.models import StartBrowserUseTaskParams
import os
from dotenv import load_dotenv

load_dotenv()

client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))

result = client.agents.browser_use.start_and_wait(
    params=StartBrowserUseTaskParams(
        task="Go to Hacker News and tell me the title of the top post",
        llm="gemini-2.0-flash",
        max_steps=20,
    )
)

print(f"Output:\n{result.data.final_result}")
```

--------------------------------

### Ruby: Get extract job status

Source: https://www.hyperbrowser.ai/docs/api-reference/get-extract-job-status

Ruby example using net/http to send a GET request to the status endpoint with an API key header.

```Ruby
require 'uri'
require 'net/http'

url = URI("https://api.hyperbrowser.ai/api/extract/{id}/status")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

response = http.request(request)
puts response.read_body
```

--------------------------------

### Install Selenium with uv

Source: https://www.hyperbrowser.ai/docs/sessions/selenium

Install the Hyperbrowser SDK, Selenium, and python-dotenv using uv.

```bash
uv add hyperbrowser selenium python-dotenv
```

--------------------------------

### Go: Get extract job status

Source: https://www.hyperbrowser.ai/docs/api-reference/get-extract-job-status

Go example using net/http to send a GET request to the status endpoint with an API key header.

```Go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.hyperbrowser.ai/api/extract/{id}/status"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
```

--------------------------------

### Create volume, mount to sandbox, and read/write files (CLI)

Source: https://www.hyperbrowser.ai/docs/sandboxes/volumes

Uses the Hyperbrowser CLI (hx). Creates a volume, mounts it to a sandbox, then writes and reads a file through the mounted path.

```bash
# 1) Create volume
volume_id=$(hx --json vm volumes create my-workspace | jq -r '.id')

# 2) Create sandbox with mounted volume
sandbox_id=$(hx --json vm create node --mount "$volume_id:/mnt/workspace" | jq -r '.data.id')

# 3) Write/read through mounted path
hx file write "$sandbox_id" /mnt/workspace/hello.txt --data 'hello from volume'
hx file cat "$sandbox_id" /mnt/workspace/hello.txt
```

--------------------------------

### cURL: Start, check status, and get results for HyperAgent task

Source: https://www.hyperbrowser.ai/docs/agents/hyperagent

Shows the REST API workflow: POST to /api/task/hyper-agent to start a task (with a sample response), then GET the status endpoint and the full results endpoint using the job ID. Uses gpt-4o as the LLM and maxSteps 20.

```bash
# Start the task
curl -X POST https://api.hyperbrowser.ai/api/task/hyper-agent \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "task": "Go to Hacker News and tell me the title of the top post",
    "llm": "gpt-4o",
    "maxSteps": 20
  }'

# Response: {"jobId": "abc123", "liveUrl": "https://..."}

# Check status
curl https://api.hyperbrowser.ai/api/task/hyper-agent/abc123/status \
  -H "x-api-key: YOUR_API_KEY"

# Get full results
curl https://api.hyperbrowser.ai/api/task/hyper-agent/abc123 \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### Start Meta Computer Use Task with Python SDK

Source: https://www.hyperbrowser.ai/docs/api-reference/start-a-meta-computer-use-task

Uses the hyperbrowser Python SDK to start a task with a task description and max_steps. Requires an API key.

```Python
from hyperbrowser import Hyperbrowser

client = Hyperbrowser(api_key='your-api-key')

client.agents.meta_computer_use.start({
  "task": "Find the price of the product",
  "max_steps": 20
})
```

--------------------------------

### Create sandbox and get runtime URL (Python 1.0+)

Source: https://www.hyperbrowser.ai/docs/sandboxes/runtime

Creates a sandbox with the 'python' image and prints the runtime base URL. The SDK sends exec commands to the runtime URL.

```python
sandbox = client.sandboxes.create(
    {
        "image_name": "python",
    }
)

print(f"Runtime URL: {sandbox.runtime.base_url}")

# The SDK sends this to sandbox.runtime.base_url + /exec for you.
result = sandbox.exec("""python3 -c 'print("hello from runtime")'""")
print(result.stdout.strip())
```

--------------------------------

### Python (legacy) quick start with StartClaudeComputerUseTaskParams

Source: https://www.hyperbrowser.ai/docs/agents/claude-computer-use

Runs a Claude Computer Use task using the start_and_wait method with a typed params object. Requires HYPERBROWSER_API_KEY environment variable. Prints the final result.

```python
from hyperbrowser import Hyperbrowser
from hyperbrowser.models import StartClaudeComputerUseTaskParams
import os
from dotenv import load_dotenv

load_dotenv()

client = Hyperbrowser(api_key=os.getenv("HYPERBROWSER_API_KEY"))

result = client.agents.claude_computer_use.start_and_wait(
    params=StartClaudeComputerUseTaskParams(
        task="Go to Hacker News and tell me the title of the top post",
        llm="claude-sonnet-4-5",
        max_steps=20,
    )
)

print(f"Output:\n{result.data.final_result}")
```

--------------------------------

### Crawl Webpages example parameters

Source: https://www.hyperbrowser.ai/docs/integrations/model-context-protocol

Example parameters for the crawl_webpages tool. Crawls a site starting from a URL, following links up to 5 pages, with cookie acceptance.

```json
{
  "url": "https://example.com",
  "outputFormat": ["markdown", "links"],
  "followLinks": true,
  "maxPages": 5,
  "sessionOptions": {
    "acceptCookies": true
  }
}
```

--------------------------------

### hx vm process start

Source: https://www.hyperbrowser.ai/docs/sandboxes/cli

Starts a background process inside a sandbox.

```APIDOC
## hx vm process start

### Description
Starts a background process inside a sandbox.

### Method
CLI

### Command
`hx vm process start <sandbox-id> '<command>'`

### Parameters
#### Positional Arguments
- `<sandbox-id>` (string) - Required - The ID of the sandbox.
- `<command>` (string) - Required - The command to run as a background process.

#### Optional Flags
- `--json` (global flag) - Optional - Output in JSON format.

### Examples
```
hx vm process start <sandbox-id> 'python3 -m http.server 3000'
hx --json vm process start <sandbox-id> 'sleep 30'
```
```

--------------------------------

### Start From A Snapshot (Python legacy)

Source: https://www.hyperbrowser.ai/docs/sdks/python

Starts a new sandbox from a memory checkpoint using the legacy SDK with CreateSandboxParams. Requires snapshot_name; snapshot_id optionally pins a specific snapshot version.

```python
from hyperbrowser.models import CreateSandboxParams

sandbox = client.sandboxes.create(
    CreateSandboxParams(
        snapshot_name="node-after-setup",  # required: snapshot name
        snapshot_id="snapshot-id",  # optional: pin a specific snapshot version
    )
)
```

--------------------------------

### Get, Refresh, and Wait (Python 1.0+)

Source: https://www.hyperbrowser.ai/docs/sandboxes/terminal

Python 1.0+ version of the get and wait example. Creates a terminal, fetches its output, and waits for completion with a timeout.

```python
terminal = sandbox.terminal.create(
    {
        "command": "bash",
        "args": ["-lc", "echo hello-from-terminal"],
    }
)

fetched = sandbox.terminal.get(terminal.id, include_output=True)
print("".join(chunk.data for chunk in fetched.current.output or []))

status = terminal.wait(
    timeout_ms=2000,
    include_output=True,
)

print(status.running, status.exit_code)
```

--------------------------------

### Create and restore snapshots with hx vm snapshot

Source: https://www.hyperbrowser.ai/docs/sandboxes/cli

Shows how to create a memory snapshot from a running sandbox, list snapshots, and restore from a snapshot when creating a new sandbox.

```bash
hx vm snapshot create <sandbox-id> my_snapshot
```

```bash
hx vm snapshot list
hx vm snapshot list --limit 20
```

```bash
hx vm create my_snapshot --snapshot
hx vm create --snapshot-name my_snapshot --snapshot-id <snapshot-id>
```

--------------------------------

### Java: Get extract job status with Unirest

Source: https://www.hyperbrowser.ai/docs/api-reference/get-extract-job-status

Java example using Unirest to send a GET request to the status endpoint with an API key header.

```Java
HttpResponse<String> response = Unirest.get("https://api.hyperbrowser.ai/api/extract/{id}/status")
  .header("x-api-key", "<api-key>")
  .asString();
```

--------------------------------

### cURL quick start for Gemini Computer Use

Source: https://www.hyperbrowser.ai/docs/agents/gemini-computer-use

cURL commands to start a Gemini Computer Use task, check its status, and get full results. The start command returns a job ID and live URL.

```bash
# Start the task
curl -X POST https://api.hyperbrowser.ai/api/task/gemini-computer-use \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "task": "Go to Hacker News and tell me the title of the top post",
    "maxSteps": 20
  }'

# Response: {"jobId": "abc123", "liveUrl": "https://..."}

# Check status
curl https://api.hyperbrowser.ai/api/task/gemini-computer-use/abc123/status \
  -H "x-api-key: YOUR_API_KEY"

# Get full results
curl https://api.hyperbrowser.ai/api/task/gemini-computer-use/abc123 \
  -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### Create sandbox from a snapshot

Source: https://www.hyperbrowser.ai/docs/sandboxes/cli

Launch a sandbox from a snapshot using `hx vm create` with `--snapshot`, `snapshot:my_snapshot`, or `--snapshot-name`. Use `--snapshot-id` to specify the snapshot.

```bash
hx vm create my_snapshot --snapshot
hx vm create snapshot:my_snapshot --snapshot-id <snapshot-id>
hx vm create --snapshot-name my_snapshot --snapshot-id <snapshot-id>
```

--------------------------------

### Get, Refresh, and Wait (Python legacy)

Source: https://www.hyperbrowser.ai/docs/sandboxes/terminal

Python (legacy) version of the get and wait example. Uses SandboxTerminalCreateParams to create the terminal, fetches output, and waits for completion.

```python
from hyperbrowser.models import SandboxTerminalCreateParams

terminal = sandbox.terminal.create(
    SandboxTerminalCreateParams(
        command="bash",
        args=["-lc", "echo hello-from-terminal"],
    )
)

fetched = sandbox.terminal.get(terminal.id, include_output=True)
print("".join(chunk.data for chunk in fetched.current.output or []))

status = terminal.wait(
    timeout_ms=2000,
    include_output=True,
)

print(status.running, status.exit_code)
```

--------------------------------

### Start a background process with hx vm process start

Source: https://www.hyperbrowser.ai/docs/sandboxes/cli

Start a long-running process in a sandbox. The --json flag outputs JSON.

```bash
hx vm process start <sandbox-id> 'python3 -m http.server 3000'
hx --json vm process start <sandbox-id> 'sleep 30'
```

--------------------------------

### Java: Get scrape job status with Unirest

Source: https://www.hyperbrowser.ai/docs/api-reference/get-scrape-job-status

Java example using Unirest to send a GET request to the status endpoint. Requires the x-api-key header and a job ID.

```Java
HttpResponse<String> response = Unirest.get("https://api.hyperbrowser.ai/api/scrape/{id}/status")
  .header("x-api-key", "<api-key>")
  .asString();
```

--------------------------------

### PHP: Get scrape job status with cURL

Source: https://www.hyperbrowser.ai/docs/api-reference/get-scrape-job-status

PHP example using cURL to perform a GET request to the status endpoint. Requires the x-api-key header and a job ID.

```PHP
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.hyperbrowser.ai/api/scrape/{id}/status",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
```
Tokens:
Raw