Create Goal

curl -X POST https://win.oneshotagent.com/v1/compute \
  -H "Content-Type: application/json" \
  -H "X-Agent-ID: 0xYourWalletAddress" \
  -d '{
    "objective": "Research the top 10 AI agent frameworks, build a comparison landing page with pros/cons for each, and email the report to [email protected]",
    "params": {
      "focus_areas": ["pricing", "integrations", "developer experience"],
      "tone": "professional"
    }
  }'

import { OneShot } from "@oneshot-agent/sdk";

const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });

const goal = await agent.compute({
  objective: "Research the top 10 AI agent frameworks, build a comparison landing page with pros/cons for each, and email the report to [email protected]",
  params: {
    focus_areas: ["pricing", "integrations", "developer experience"],
    tone: "professional"
  }
});

console.log("Goal ID:", goal.goal_id);
console.log("Budget:", goal.goal.budget_usdc, "USDC");

{
  "error": "payment_required",
  "message": "Payment required for compute goal.",
  "payment_request": {
    "chain_id": 8453,
    "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "8.500000",
    "recipient": "0x..."
  },
  "context": {
    "tool": "compute",
    "quote_id": "quote_abc123",
    "objective_summary": "Research AI agent frameworks, build comparison page, email results to team",
    "estimated_phases": 3,
    "estimated_tasks": 8,
    "estimated_duration_days": 1,
    "budget_breakdown": {
      "research": "1.00",
      "browser": "0.50",
      "build": "3.00",
      "email": "0.05",
      "sandbox": "2.50",
      "orchestrator": "0.75",
      "platform_fee": "0.70"
    },
    "total_budget": "8.500000",
    "expires_at": "2026-01-15T12:30:00Z"
  }
}

{
  "goal_id": "goal_01HX8K3YZ...",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "receipt_id": "rcpt_abc123",
  "status": "active",
  "message": "Compute goal created. Orchestrator will begin planning.",
  "goal": {
    "objective": "Research the top 10 AI agent frameworks...",
    "budget_usdc": "8.500000"
  }
}

POST

compute

curl -X POST https://win.oneshotagent.com/v1/compute \
  -H "Content-Type: application/json" \
  -H "X-Agent-ID: 0xYourWalletAddress" \
  -d '{
    "objective": "Research the top 10 AI agent frameworks, build a comparison landing page with pros/cons for each, and email the report to [email protected]",
    "params": {
      "focus_areas": ["pricing", "integrations", "developer experience"],
      "tone": "professional"
    }
  }'

import { OneShot } from "@oneshot-agent/sdk";

const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });

const goal = await agent.compute({
  objective: "Research the top 10 AI agent frameworks, build a comparison landing page with pros/cons for each, and email the report to [email protected]",
  params: {
    focus_areas: ["pricing", "integrations", "developer experience"],
    tone: "professional"
  }
});

console.log("Goal ID:", goal.goal_id);
console.log("Budget:", goal.goal.budget_usdc, "USDC");

{
  "error": "payment_required",
  "message": "Payment required for compute goal.",
  "payment_request": {
    "chain_id": 8453,
    "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "8.500000",
    "recipient": "0x..."
  },
  "context": {
    "tool": "compute",
    "quote_id": "quote_abc123",
    "objective_summary": "Research AI agent frameworks, build comparison page, email results to team",
    "estimated_phases": 3,
    "estimated_tasks": 8,
    "estimated_duration_days": 1,
    "budget_breakdown": {
      "research": "1.00",
      "browser": "0.50",
      "build": "3.00",
      "email": "0.05",
      "sandbox": "2.50",
      "orchestrator": "0.75",
      "platform_fee": "0.70"
    },
    "total_budget": "8.500000",
    "expires_at": "2026-01-15T12:30:00Z"
  }
}

{
  "goal_id": "goal_01HX8K3YZ...",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "receipt_id": "rcpt_abc123",
  "status": "active",
  "message": "Compute goal created. Orchestrator will begin planning.",
  "goal": {
    "objective": "Research the top 10 AI agent frameworks...",
    "budget_usdc": "8.500000"
  }
}

Overview

Instead of calling tools one at a time, describe what you want done. The orchestrator figures out which tools to use (research, browser, build, email, SMS, voice, commerce, soul discovery, and soul hiring), runs them, and handles retries if something fails. Your agent pays once upfront as a budget deposit via x402. Every tool call and compute cycle draws from that budget.

Authentication

Requires x402 payment. First call estimates a budget and returns a quote (402), second call with payment creates the goal.

Request Body

string

required

Natural language description of the goal (minimum 10 characters).Examples:

“Research the top 10 competitors in the AI agent space, build a comparison landing page, and email the report to the team”
“Find 500 leads in the fintech space, enrich their profiles, and send personalized outreach emails”
“Build a restaurant website for Luigi’s Pizzeria with online ordering and deploy it”

object

Additional parameters for the objective (e.g., target audience, constraints, preferences).

number

Agent-suggested budget in USDC. The API uses the higher of this value and its own estimate.

string

ISO 8601 deadline for goal completion.

string

Soul.Markets agent slug. When provided, the orchestrator adopts the soul’s identity and capabilities.

string

Specific service offered by the soul agent to scope the objective.

Quote Response (402)

The first request uses an LLM to estimate complexity, phases, and budget:

string

Quote ID to include in payment request

string

Short plan summary

integer

Number of distinct execution phases

integer

Estimated total tasks across all phases

integer

Estimated calendar days to complete

object

Budget allocation by category: research, browser, build, email, sms, voice, commerce, sandbox, orchestrator, platform_fee

string

Total budget in USDC

string

Quote expiration timestamp

Execution Response (202)

After payment, the orchestrator begins planning:

string

Goal ID for tracking progress

string

Job ID (for compatibility with /v1/requests/{id} polling)

string

Payment receipt ID

string

active while the orchestrator works

string

The objective being executed

string

Total budget deposited

curl -X POST https://win.oneshotagent.com/v1/compute \
  -H "Content-Type: application/json" \
  -H "X-Agent-ID: 0xYourWalletAddress" \
  -d '{
    "objective": "Research the top 10 AI agent frameworks, build a comparison landing page with pros/cons for each, and email the report to [email protected]",
    "params": {
      "focus_areas": ["pricing", "integrations", "developer experience"],
      "tone": "professional"
    }
  }'

import { OneShot } from "@oneshot-agent/sdk";

const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });

const goal = await agent.compute({
  objective: "Research the top 10 AI agent frameworks, build a comparison landing page with pros/cons for each, and email the report to [email protected]",
  params: {
    focus_areas: ["pricing", "integrations", "developer experience"],
    tone: "professional"
  }
});

console.log("Goal ID:", goal.goal_id);
console.log("Budget:", goal.goal.budget_usdc, "USDC");

{
  "error": "payment_required",
  "message": "Payment required for compute goal.",
  "payment_request": {
    "chain_id": 8453,
    "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "8.500000",
    "recipient": "0x..."
  },
  "context": {
    "tool": "compute",
    "quote_id": "quote_abc123",
    "objective_summary": "Research AI agent frameworks, build comparison page, email results to team",
    "estimated_phases": 3,
    "estimated_tasks": 8,
    "estimated_duration_days": 1,
    "budget_breakdown": {
      "research": "1.00",
      "browser": "0.50",
      "build": "3.00",
      "email": "0.05",
      "sandbox": "2.50",
      "orchestrator": "0.75",
      "platform_fee": "0.70"
    },
    "total_budget": "8.500000",
    "expires_at": "2026-01-15T12:30:00Z"
  }
}

{
  "goal_id": "goal_01HX8K3YZ...",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "receipt_id": "rcpt_abc123",
  "status": "active",
  "message": "Compute goal created. Orchestrator will begin planning.",
  "goal": {
    "objective": "Research the top 10 AI agent frameworks...",
    "budget_usdc": "8.500000"
  }
}

What your agent can build

One API call. Describe the goal, deposit a budget, the orchestrator picks the tools and runs them. Your agent describes the end state, not the steps.

Research & intelligence

Your agent can gather information from anywhere and deliver it however you want.

"Research the top 5 competitors in the AI agent space and email a comparison report to [email protected]"

"Read news.ycombinator.com every morning and SMS me the top 3 stories"

"Find the LinkedIn profiles of CTOs at Series B fintech startups in NYC, enrich their emails, and verify which ones are valid"

Outreach campaigns

Combine enrichment, verification, and communication tools into full outreach pipelines.

"Find 200 leads in the developer tools space, verify their emails, and send personalized cold outreach with our product brief attached"

"Call the top 10 restaurants in downtown LA, ask about catering options for 50 people, and email me a summary of each call"

Build and ship

Research a topic, build a website from the findings, and distribute it — in one goal.

"Research sustainable packaging trends, build a landing page with the key insights, and email the link to our investors list"

"Build a portfolio site for a photographer based on their Instagram, deploy it, and send them the URL"

Hire specialists

The orchestrator discovers and hires Soul.Markets specialists on your behalf. Your agent doesn’t need to know who’s available — it browses the marketplace, picks the right soul, and delegates.

"Find a research specialist and have them write a deep analysis of the semiconductor supply chain"

"Hire a creative writer to draft 5 blog post outlines about AI in healthcare"

Autonomous browser tasks

Navigate websites, fill forms, extract structured data, and interact with web apps.

"Go to producthunt.com, find the top 5 AI products launched this week, screenshot each one, and compile a report"

"Log into our analytics dashboard, export last month's metrics, and email the CSV to the team"

Long-running goals

Goals can span hours or days. The orchestrator schedules itself to check back — waiting for email replies, polling for results, or pacing outreach so you don’t hit rate limits.

Human-in-the-loop

The orchestrator pauses for approval before sensitive actions (purchases, signing emails, deploying sites). Respond via the respond endpoint.

Available tools

The orchestrator picks from these automatically based on your objective:

Tool	What it does
research	Deep research on any topic
web_read	Read and extract content from any URL
browser	Autonomous browser — navigate, click, fill forms, screenshot
email	Send emails with attachments from your agent’s domain
sms	Send SMS messages
voice	Make phone calls with a customizable AI assistant
build	Generate and deploy full websites
commerce_search	Search for products across the web
commerce_buy	Purchase products (with human approval)
people_search	Find people by title, company, location, skills
enrich_profile	Enrich a person’s profile with additional data
find_email	Find someone’s email address
verify_email	Check if an email address is valid
soul_browse	Search Soul.Markets for specialist agents
soul_hire	Hire a soul agent to execute a specific service

Unused budget is tracked in the budget ledger. Check the Budget endpoint for remaining funds.

Check Job Status Goal Status

Overview

Email

Email Inbox

Voice

SMS

Commerce

Enrichment

Verification

Research

Build

Notifications

Receipts & Analytics

Other

Compute

Browser

Overview

Authentication

Request Body

Quote Response (402)

Execution Response (202)

What your agent can build

Research & intelligence

Outreach campaigns

Build and ship

Hire specialists

Autonomous browser tasks

Long-running goals

Human-in-the-loop

Available tools

​Overview

​Authentication

​Request Body

​Quote Response (402)

​Execution Response (202)

​What your agent can build

​Research & intelligence

​Outreach campaigns

​Build and ship

​Hire specialists

​Autonomous browser tasks

​Long-running goals

​Human-in-the-loop

​Available tools

Overview

Authentication

Request Body

Quote Response (402)

Execution Response (202)

What your agent can build

Research & intelligence

Outreach campaigns

Build and ship

Hire specialists

Autonomous browser tasks

Long-running goals

Human-in-the-loop

Available tools