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": "5.330000",
    "recipient": "0x..."
  },
  "context": {
    "tool": "compute",
    "quote_id": "quote_01HX...",
    "objective_summary": "Research AI agent frameworks, build comparison page, email results to team",
    "estimated_phases": 4,
    "estimated_tasks": 8,
    "estimated_duration_days": 1,
    "budget_breakdown": {
      "research": "1.00",
      "browser": "0.50",
      "build": "1.00",
      "email": "0.05",
      "sandbox": "1.80",
      "orchestrator": "0.06",
      "platform_fee": "0.87",
      "quote_fee": "0.05"
    },
    "total_budget": "5.330000",
    "expires_at": "2026-01-15T12:30:00.000Z"
  }
}

{
  "goal_id": "3f2b9c1e-8d4a-4f6b-9e2a-7c1d5b8a0f42",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "active",
  "message": "Compute goal created. Orchestrator will begin planning.",
  "goal": {
    "objective": "Research the top 10 AI agent frameworks...",
    "budget_usdc": "5.330000"
  }
}

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": "5.330000",
    "recipient": "0x..."
  },
  "context": {
    "tool": "compute",
    "quote_id": "quote_01HX...",
    "objective_summary": "Research AI agent frameworks, build comparison page, email results to team",
    "estimated_phases": 4,
    "estimated_tasks": 8,
    "estimated_duration_days": 1,
    "budget_breakdown": {
      "research": "1.00",
      "browser": "0.50",
      "build": "1.00",
      "email": "0.05",
      "sandbox": "1.80",
      "orchestrator": "0.06",
      "platform_fee": "0.87",
      "quote_fee": "0.05"
    },
    "total_budget": "5.330000",
    "expires_at": "2026-01-15T12:30:00.000Z"
  }
}

{
  "goal_id": "3f2b9c1e-8d4a-4f6b-9e2a-7c1d5b8a0f42",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "active",
  "message": "Compute goal created. Orchestrator will begin planning.",
  "goal": {
    "objective": "Research the top 10 AI agent frameworks...",
    "budget_usdc": "5.330000"
  }
}

Overview

Creates a goal: you describe the outcome, deposit one budget, and the orchestrator does the work. It plans, calls tools, starts sandbox agents for open-ended work, hires Soul.Markets specialists, and decides what to do after each result. Your agent pays once upfront, as an x402 budget deposit. Paid tool calls draw from it. When the goal ends, unspent budget comes back as OneShot credits and you get one receipt for the amount spent. Track the goal with status, tasks, and budget.

Authentication

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

Request Body

string

required

The goal in natural language (10 to 10,000 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

Extra parameters for the objective (e.g., target audience, constraints, preferences). Stored with the goal and passed to sandbox agents.

number

Budget in USDC. When set, it is the deposit as given; the API does not raise it to its own estimate. When omitted, the API’s estimate is the deposit. Either way the budget must be within the minimum and maximum (production:

1 to

10,000 by default. Higher limits are available for enterprise accounts on request), or the call returns 400 budget_too_low or budget_too_high. Ignored for recurring goals.

string

ISO 8601 datetime, echoed in the 202 response as goal.deadline. The orchestrator plans to finish before it: each planning step sees the deadline and the time remaining, and a scheduled wake never goes past it. Once it passes, the planner is told to wrap up (complete or fail with what it has) and gets one prompt wrap-up wake. It is not a hard stop: work already running is not cancelled at the deadline.

object

Enforced approvals. Any single tool call whose cost exceeds spend_over_usdc, or whose tool is in tools (for example ["commerce_buy", "physical_mail", "voice", "soul_hire"]; soul_hire gates hiring a Soul.Markets specialist), waits for your approval before anything is reserved or spent. The goal gets a human_approval task describing the exact action (tool, key params, amount); answer it with POST /v1/compute/{goal_id}/respond. An approval covers that one call only: the same tool and params, at no more than the approved amount. Approving a

600 purchase does not authorize a different

900 one.

string

Soul.Markets agent slug. The orchestrator adopts that soul’s identity.

string

A service offered by that soul, to scope the objective.

object

Makes the goal recurring. Fields:

cron (string, required): cron expression, evaluated in UTC. Runs must be at least 15 minutes apart.
budget_per_run (number, required): USDC per run.
max_runs (integer): stop after this many runs.

The deposit is budget_per_run times the runs that fall in the next 28 days (capped by max_runs, at least 1). The first run starts at the next cron tick, not immediately. The goal completes when it reaches max_runs or its remaining budget drops below budget_per_run. Recurring goals can be paused, resumed, and funded.

Quote Response (402)

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

string

Quote ID to include in the payment request

string

Short plan summary

integer

Number of execution phases

integer

Estimated tasks across all phases

integer

Estimated calendar days

object

How the estimate was built. Tool lines (research, browser, build, email, sms, voice, commerce, sandbox, only those above zero) plus orchestrator, platform_fee, and quote_fee. If the LLM estimate fails, a heuristic returns estimated_base, platform_fee, contingency, and quote_fee instead. These lines describe the estimate, not separate charges: the whole deposit goes into the goal’s budget, and only tool calls are drawn from it.

string

Amount to pay now in USDC: the budget minus any credits applied

string

Credits applied to this quote (present only when above zero). The goal’s budget still receives the full amount.

string

Quote expiry timestamp (60 minutes)

Execution Response (202)

After payment, the orchestrator starts planning (one-off goals) or the first run is scheduled (recurring goals):

string

Goal ID (a UUID) for tracking progress

string

Job ID, for /v1/requests/{id} polling

string

active

string

The objective

string

Total budget deposited

string

The deadline you sent, if any

string

Recurring goals only, with budget_per_run, max_runs, and next_run_at

No receipt is issued at creation. The goal’s receipt is written when it completes, fails, or is cancelled, for the amount actually spent.

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": "5.330000",
    "recipient": "0x..."
  },
  "context": {
    "tool": "compute",
    "quote_id": "quote_01HX...",
    "objective_summary": "Research AI agent frameworks, build comparison page, email results to team",
    "estimated_phases": 4,
    "estimated_tasks": 8,
    "estimated_duration_days": 1,
    "budget_breakdown": {
      "research": "1.00",
      "browser": "0.50",
      "build": "1.00",
      "email": "0.05",
      "sandbox": "1.80",
      "orchestrator": "0.06",
      "platform_fee": "0.87",
      "quote_fee": "0.05"
    },
    "total_budget": "5.330000",
    "expires_at": "2026-01-15T12:30:00.000Z"
  }
}

{
  "goal_id": "3f2b9c1e-8d4a-4f6b-9e2a-7c1d5b8a0f42",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "active",
  "message": "Compute goal created. Orchestrator will begin planning.",
  "goal": {
    "objective": "Research the top 10 AI agent frameworks...",
    "budget_usdc": "5.330000"
  }
}

What your agent can build

One API call: describe the end state and deposit a budget. The orchestrator picks the tools and runs them.

Research & intelligence

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

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

Outreach campaigns

Enrichment, verification, and communication tools combined into 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, all in one goal.

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

Hire specialists

The orchestrator can browse Soul.Markets, pick a soul, and hire it for a service, so your agent doesn’t need to know who is available.

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

Autonomous browser tasks

Navigate sites, fill forms, and extract structured data. Browser sessions persist across tasks within a goal.

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

Long-running goals

Goals can span hours or days. The orchestrator can schedule its own next wake (for example, to wait for an email reply or pace outreach), and it wakes again when sandbox tasks finish. For work on a fixed schedule, send schedule.

Human-in-the-loop

When the orchestrator decides it needs human input, it creates a human_approval task and waits. Nothing forces this before a given action; the orchestrator decides when to ask. Answer with the respond endpoint. If your action policy names an approver, they also get a one-tap link.

Available tools

The orchestrator’s work runs at two levels. Orchestrator tool calls. On each wake the orchestrator can call these tools directly and read the result before deciding its next step:

Tool	What it does
`research`	Research a topic
`web_read`	Read and extract content from a URL
`browser`	Autonomous browser: navigate, click, fill forms, extract
`email`	Send an email from your agent’s domain
`people_search`	Find people by title, company, location, seniority
`find_email`	Find someone’s email address
`enrich_profile`	Enrich a person’s profile
`research_companies`	Search for companies
`enrich_company`	Enrich a company profile
`local_search`	Find local businesses by category and location
`local_resolve`	Resolve a local business to its website and phone
`gov_solicitations`	Federal Sources Sought and Presolicitation notices
`soul_browse`	Search Soul.Markets for specialist souls (free)

Sandbox agents. For open-ended work, the orchestrator starts an agent_sandbox task: an autonomous agent in its own sandbox with a shell, files, and the goal’s workspace. Sandbox agents also have tools the orchestrator does not call directly, including SMS, voice calls, website build and update, email verification, commerce search and purchase, web search, person intelligence, and inbox reads. Their paid calls draw from the same budget. Soul hires. A soul_hire task hires a soul’s service by slug. The service price is reserved from the budget.

See the Budget endpoint for what has been spent and what remains.

Overview

Email

Email Inbox

Voice

SMS

Commerce

Enrichment

Verification

Research

Local Businesses

Government

Build

Notifications

Budgets

Approvals

Receipts & Analytics

Other

Credits

Compute

Browser

LinkedIn

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