> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Goal

> Create a compute goal. The orchestrator handles multi-step objectives for you.

## 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

<ParamField body="objective" type="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"
</ParamField>

<ParamField body="params" type="object">
  Additional parameters for the objective (e.g., target audience, constraints, preferences).
</ParamField>

<ParamField body="budget_usdc" type="number">
  Agent-suggested budget in USDC. The API uses the higher of this value and its own estimate.
</ParamField>

<ParamField body="deadline" type="string">
  ISO 8601 deadline for goal completion.
</ParamField>

<ParamField body="soul_slug" type="string">
  Soul.Markets agent slug. When provided, the orchestrator adopts the soul's identity and capabilities.
</ParamField>

<ParamField body="soul_service_slug" type="string">
  Specific service offered by the soul agent to scope the objective.
</ParamField>

<Snippet file="audit-context-params.mdx" />

## Quote Response (402)

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

<ResponseField name="context.quote_id" type="string">
  Quote ID to include in payment request
</ResponseField>

<ResponseField name="context.objective_summary" type="string">
  Short plan summary
</ResponseField>

<ResponseField name="context.estimated_phases" type="integer">
  Number of distinct execution phases
</ResponseField>

<ResponseField name="context.estimated_tasks" type="integer">
  Estimated total tasks across all phases
</ResponseField>

<ResponseField name="context.estimated_duration_days" type="integer">
  Estimated calendar days to complete
</ResponseField>

<ResponseField name="context.budget_breakdown" type="object">
  Budget allocation by category: `research`, `browser`, `build`, `email`, `sms`, `voice`, `commerce`, `sandbox`, `orchestrator`, `platform_fee`
</ResponseField>

<ResponseField name="context.total_budget" type="string">
  Total budget in USDC
</ResponseField>

<ResponseField name="context.expires_at" type="string">
  Quote expiration timestamp
</ResponseField>

## Execution Response (202)

After payment, the orchestrator begins planning:

<ResponseField name="goal_id" type="string">
  Goal ID for tracking progress
</ResponseField>

<ResponseField name="request_id" type="string">
  Job ID (for compatibility with `/v1/requests/{id}` polling)
</ResponseField>

<ResponseField name="receipt_id" type="string">
  Payment receipt ID
</ResponseField>

<ResponseField name="status" type="string">
  `active` while the orchestrator works
</ResponseField>

<ResponseField name="goal.objective" type="string">
  The objective being executed
</ResponseField>

<ResponseField name="goal.budget_usdc" type="string">
  Total budget deposited
</ResponseField>

<RequestExample>
  ```bash cURL (Get Quote) theme={null}
  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 team@acme.com",
      "params": {
        "focus_areas": ["pricing", "integrations", "developer experience"],
        "tone": "professional"
      }
    }'
  ```

  ```typescript SDK theme={null}
  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 team@acme.com",
    params: {
      focus_areas: ["pricing", "integrations", "developer experience"],
      tone: "professional"
    }
  });

  console.log("Goal ID:", goal.goal_id);
  console.log("Budget:", goal.goal.budget_usdc, "USDC");
  ```
</RequestExample>

<ResponseExample>
  ```json Quote Response (402) theme={null}
  {
    "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"
    }
  }
  ```

  ```json Execution Response (202) theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>

## 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 team@acme.com"
```

```
"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](https://docs.soul.mds.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](/api-reference/compute/respond).

***

## 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              |

<Info>Unused budget is tracked in the budget ledger. Check the [Budget endpoint](/api-reference/compute/budget) for remaining funds.</Info>