Skip to main content
POST
/
v1
/
tools
/
browser
curl -X POST https://win.oneshotagent.com/v1/tools/browser \
  -H "Content-Type: application/json" \
  -H "X-Agent-ID: 0xYourWalletAddress" \
  -d '{
    "task": "Go to producthunt.com, find the top 5 AI products launched today, and extract their names, descriptions, and upvote counts",
    "output_schema": {
      "products": [{
        "name": "string",
        "description": "string",
        "upvotes": "number"
      }]
    }
  }'

{
  "error": "payment_required",
  "message": "Payment required for browser automation.",
  "payment_request": {
    "chain_id": 8453,
    "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "0.150000",
    "recipient": "0x..."
  },
  "context": {
    "tool": "browser",
    "quote_id": "quote_abc123",
    "task_summary": "Navigate to ProductHunt, find top AI products, extract structured data",
    "estimated_steps": 8,
    "max_steps": 25,
    "estimated_cost": "0.150000",
    "complexity_score": 0.6,
    "expires_at": "2026-01-15T12:30:00Z"
  }
}

​
Overview

Your agent tells the Browser API what to do in plain English. It navigates pages, pulls structured data, fills out forms, clicks buttons, and runs multi-step workflows on your behalf. You get a cost estimate before paying.

​
Authentication

Requires x402 payment. First call analyzes the task and returns a quote (402), second call with payment executes asynchronously.

​
Request Body

​
task
string
required
Natural language description of the browser task (minimum 10 characters, max 50,000).Examples:
  • “Go to example.com/pricing and extract all plan names, prices, and features into a table”
  • “Navigate to the contact page and fill out the form with our company info”
  • “Search for ‘AI startups’ on ProductHunt and extract the top 10 results”
​
output_schema
object
JSON schema for the expected output. If you pass this, the browser extracts data matching your schema.
{
  "products": [{
    "name": "string",
    "price": "number",
    "features": ["string"]
  }]
}
​
start_url
string
Starting URL for the browser task. If omitted, the agent decides where to begin based on the task description.
​
allowed_domains
string[]
Restrict browsing to specific domains. The agent will not navigate outside these domains.
​
session_id
string
UUID to resume a previous browser session (preserves cookies, login state).
​
max_steps
integer
Maximum number of browser steps (1-100). Defaults to the environment maximum. Lower values reduce cost.

​
Quote Response (402)

The first request analyzes the task and returns a cost estimate:
​
context.quote_id
string
Quote ID to include in payment request
​
context.task_summary
string
Summary of what the browser will do
​
context.estimated_steps
integer
Estimated number of browser steps needed
​
context.max_steps
integer
Maximum steps allowed for this task
​
context.estimated_cost
string
Total estimated cost in USDC
​
context.complexity_score
number
Task complexity score (0-1)
​
context.expires_at
string
Quote expiration timestamp (30 minutes)

​
Execution Response (202)

After payment, the browser task runs asynchronously:
​
request_id
string
Job ID for polling status at /v1/requests/{id}
​
status
string
processing while the browser task runs
​
browser.estimated_steps
integer
Estimated steps from the quote
​
browser.estimated_cost
string
Estimated cost from the quote

​
Completed Job Result

Poll /v1/requests/{request_id} for the result:
​
result.output
string | object
Extracted data or task result. Structured JSON if you passed output_schema.
​
result.steps
array
List of steps taken: [{ number, goal, url }]
​
result.cost
number
Actual cost incurred
​
result.output_files
string[]
URLs of any files downloaded or screenshots captured
curl -X POST https://win.oneshotagent.com/v1/tools/browser \
  -H "Content-Type: application/json" \
  -H "X-Agent-ID: 0xYourWalletAddress" \
  -d '{
    "task": "Go to producthunt.com, find the top 5 AI products launched today, and extract their names, descriptions, and upvote counts",
    "output_schema": {
      "products": [{
        "name": "string",
        "description": "string",
        "upvotes": "number"
      }]
    }
  }'

{
  "error": "payment_required",
  "message": "Payment required for browser automation.",
  "payment_request": {
    "chain_id": 8453,
    "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "0.150000",
    "recipient": "0x..."
  },
  "context": {
    "tool": "browser",
    "quote_id": "quote_abc123",
    "task_summary": "Navigate to ProductHunt, find top AI products, extract structured data",
    "estimated_steps": 8,
    "max_steps": 25,
    "estimated_cost": "0.150000",
    "complexity_score": 0.6,
    "expires_at": "2026-01-15T12:30:00Z"
  }
}

​
Pricing

Charged per step, with a base initialization fee:
ComponentCost
Initialization$0.01
Per step0.002−0.002 - 0.006
MarginApplied on top
Minimum feeEnforced per request
Actual cost depends on how many steps the task needs.
Pass output_schema to get structured JSON back instead of raw text.
allowed_domains keeps the browser on-target and cuts both cost and runtime.