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

# OneShot SDK Overview

> The OneShot SDK handles actions, payments, and receipts for AI agents. Send emails, research topics, enrich data, and make purchases. The SDK signs payments and tracks spend automatically.

## What is the OneShot SDK?

The OneShot SDK handles the boring parts of agent commerce: signing payments, retrying on 402, polling async jobs, and tracking what your agent spent. You call `agent.email()`, the SDK handles the rest and gives you a receipt.

<Info>
  The SDK operates on **Base Mainnet** with real USDC. Fund your agent wallet before making paid tool calls.
</Info>

* **Automatic x402 Payments**: Signs and submits payment authorizations automatically
* **Pay with ETH or USDC**: Hold ETH and the SDK auto-swaps to USDC via Uniswap V3 at payment time
* **Flexible Wallets**: Coinbase CDP Server Wallets (recommended, no private keys) or raw private key via ethers.js
* **Job Polling**: Waits for async jobs to complete
* **Built-in Audit Trail**: Attach `memo` + `decisionContext` to every paid call — stored on the receipt for debugging and supervisor agents. See [Audit Trail](/sdk/audit-context).
* **Type Safety**: Full TypeScript support with proper types

## Why Use the SDK?

### For Humans

The SDK simplifies integration:

```typescript theme={null}
// Without SDK: Handle 402 responses, sign payments, poll jobs manually
// With SDK: One line
await agent.email({ to: "user@example.com", subject: "Hi", body: "Hello" });
```

### For AI Agents

The SDK is **essential** for autonomous agents:

* No manual payment flow handling
* Automatic retry logic for [rate limits](/rate-limits)
* Clean error messages
* Minimal token usage in prompts

## Quick Example

<Tabs>
  <Tab title="CDP Wallet (Recommended)">
    ```typescript theme={null}
    import { OneShot } from "@oneshot-agent/sdk";

    // Coinbase CDP Server Wallet — no private key needed
    // Reads CDP_API_KEY_ID, CDP_API_KEY_SECRET, CDP_WALLET_SECRET from env
    const agent = await OneShot.create({ cdp: true });

    // Send email (handles quote + payment + send automatically)
    await agent.email({
      to: "user@example.com",
      subject: "Hello from OneShot",
      body: "This was sent autonomously!",
    });
    ```
  </Tab>

  <Tab title="Private Key">
    ```typescript theme={null}
    import { OneShot } from "@oneshot-agent/sdk";

    // Raw private key — existing behavior
    const agent = new OneShot({
      privateKey: process.env.AGENT_PRIVATE_KEY,
    });

    // Deep research
    const report = await agent.research({
      topic: "Latest AI agent frameworks",
      depth: "deep",
    });

    console.log(report.report_content);
    ```
  </Tab>
</Tabs>

## Key Features

<CardGroup cols={2}>
  <Card title="Automatic Payments" icon="dollar-sign">
    SDK handles x402 payment flow automatically - no manual signing needed
  </Card>

  <Card title="Job Polling" icon="clock">
    Waits for async jobs to complete and returns results directly
  </Card>

  <Card title="Type Safety" icon="shield">
    Full TypeScript support with proper types for all tools
  </Card>

  <Card title="Flexible Wallets" icon="wallet">
    Coinbase CDP Server Wallets (no private keys) or raw key via ethers.js
  </Card>

  <Card title="Pay with ETH" icon="ethereum">
    Auto-swap ETH→USDC via Uniswap V3 — no need to hold USDC
  </Card>
</CardGroup>

## Read Authentication

Read endpoints — email/SMS inbox, notifications, balance, and browser profiles — return private, per-agent data. Because a wallet address is public, the API needs proof you actually control it, not just knowledge of the address (otherwise anyone could read your inbox by supplying your wallet).

On every read call the SDK signs a short-lived **EIP-712 read proof** and sends it in the `x-agent-proof` header:

* **Typed data**: domain `{ name: "OneShot Agent Auth", version: "1" }`, type `AgentReadAuth { agent: address, scope: "read", issuedAt: uint256, nonce: bytes32 }`.
* The server recovers the signer locally (`ecrecover`) and rejects the request unless the signer equals the `X-Agent-ID` wallet. A fresh nonce + short freshness window (5 min) prevent replay.

This is fully automatic — provide your wallet credentials (raw private key **or** a Coinbase CDP Server Wallet via `cdp: true`) and the SDK signs the proof for you.

<Info>
  Requires **TypeScript SDK ≥ 0.25.0** or **`oneshot-python` ≥ 0.17.0** (and `@oneshot-agent/sdk ≥ 0.25.0` for the MCP server). Older SDKs and raw HTTP callers keep working until the API turns on enforcement, after which they must send a valid `x-agent-proof` — upgrade to stay ahead of it.
</Info>

## Supported Tools

Tools are grouped by category. Click a tool name to jump to its API reference. **(quote-based)** marks tools whose price varies per call and that accept a client-side `maxCost` guard — the SDK throws before signing if the quote exceeds your limit.

### Communication

| Tool                               | Method          | Description                      |
| ---------------------------------- | --------------- | -------------------------------- |
| [Email](/api-reference/email/send) | `agent.email()` | Send emails with attachments     |
| [Voice](/api-reference/voice/call) | `agent.voice()` | Place a phone call (quote-based) |
| [SMS](/api-reference/sms/send)     | `agent.sms()`   | Send SMS messages (quote-based)  |

### Inbox & Notifications

| Tool                                               | Method                           | Description                |
| -------------------------------------------------- | -------------------------------- | -------------------------- |
| [Email Inbox](/api-reference/inbox/list)           | `agent.inboxList()`              | List inbound emails        |
| [Email Message](/api-reference/inbox/get)          | `agent.inboxGet(id)`             | Get a specific email by ID |
| [SMS Inbox](/api-reference/sms/inbox-list)         | `agent.smsInboxList()`           | List inbound SMS messages  |
| [SMS Message](/api-reference/sms/inbox-get)        | `agent.smsInboxGet(id)`          | Get a specific SMS by ID   |
| [Notifications](/api-reference/notifications/list) | `agent.notifications()`          | List agent notifications   |
| [Mark Read](/api-reference/notifications/read)     | `agent.markNotificationRead(id)` | Mark notification as read  |

### Person Intelligence

| Tool                                                                | Method                       | Description                           |
| ------------------------------------------------------------------- | ---------------------------- | ------------------------------------- |
| [People Search](/api-reference/research/person-intelligence)        | `agent.peopleSearch()`       | Search for people by criteria         |
| [Profile Enrichment](/api-reference/enrich/profile)                 | `agent.enrichProfile()`      | Enrich from LinkedIn/email            |
| [Email Finder](/api-reference/enrich/email)                         | `agent.findEmail()`          | Find email for a person               |
| [Email Verification](/api-reference/verify/email)                   | `agent.verifyEmail()`        | Verify email deliverability           |
| [Deep Research Person](/api-reference/research/person-intelligence) | `agent.deepResearchPerson()` | Full dossier on a person (2-5 min)    |
| [Social Profiles](/api-reference/research/person-intelligence)      | `agent.socialProfiles()`     | Find all social accounts for a person |
| [Article Search](/api-reference/research/person-intelligence)       | `agent.articleSearch()`      | Find articles about a person          |
| [Person Newsfeed](/api-reference/research/person-intelligence)      | `agent.personNewsfeed()`     | Recent social posts with engagement   |
| [Person Interests](/api-reference/research/person-intelligence)     | `agent.personInterests()`    | Analyze interests across categories   |
| [Person Interactions](/api-reference/research/person-intelligence)  | `agent.personInteractions()` | Map followers, following, replies     |

### Web & Research

| Tool                                               | Method                           | Description                                                 |
| -------------------------------------------------- | -------------------------------- | ----------------------------------------------------------- |
| [Research](/api-reference/research)                | `agent.research()`               | Deep web research with sources                              |
| [Web Search](/api-reference/web-search)            | `agent.webSearch()`              | Search the web, get results instantly                       |
| [Web Read](/api-reference/web-read)                | `agent.webRead()`                | Read any URL as markdown + screenshot                       |
| [Browser](/api-reference/browser/create)           | `agent.browser()`                | Autonomous browser — navigate, click, extract (quote-based) |
| [Browser Profile](/api-reference/browser/profiles) | `agent.createBrowserProfile()`   | Create persistent browser profile (cookies/sessions)        |
| [List Profiles](/api-reference/browser/profiles)   | `agent.listBrowserProfiles()`    | List all browser profiles                                   |
| [Delete Profile](/api-reference/browser/profiles)  | `agent.deleteBrowserProfile(id)` | Delete a browser profile                                    |

### Commerce

| Tool                                              | Method                   | Description                     |
| ------------------------------------------------- | ------------------------ | ------------------------------- |
| [Commerce Search](/api-reference/commerce/search) | `agent.commerceSearch()` | Search for products             |
| [Commerce Buy](/api-reference/commerce/buy)       | `agent.commerceBuy()`    | Purchase products (quote-based) |

### Build

| Tool                                        | Method                | Description                                        |
| ------------------------------------------- | --------------------- | -------------------------------------------------- |
| [Build](/api-reference/build/create)        | `agent.build()`       | Build and deploy production websites (quote-based) |
| [Update Build](/api-reference/build/update) | `agent.updateBuild()` | Update an existing website (quote-based)           |

### Utility

| Tool           | Method                           | Description                   |
| -------------- | -------------------------------- | ----------------------------- |
| Wallet Balance | `agent.getBalance(tokenAddress)` | Get USDC wallet balance       |
| Universal Tool | `agent.tool(name, options)`      | Call any OneShot tool by name |

### Compute — autonomous goal orchestration

| Method                                                                                                 | Endpoint                       | Paid?              |
| ------------------------------------------------------------------------------------------------------ | ------------------------------ | ------------------ |
| `agent.compute(options)` / Python `client.compute(...)`                                                | POST `/v1/compute`             | ✅ x402 quote-based |
| `agent.getComputeGoal(goalId)` / Python `client.get_compute_goal(goal_id)`                             | GET `/v1/compute/:id`          | —                  |
| `agent.getComputeTasks(goalId)` / Python `client.get_compute_tasks(goal_id)`                           | GET `/v1/compute/:id/tasks`    | —                  |
| `agent.getComputeBudget(goalId)` / Python `client.get_compute_budget(goal_id)`                         | GET `/v1/compute/:id/budget`   | —                  |
| `agent.cancelComputeGoal(goalId, reason?)` / Python `client.cancel_compute_goal(goal_id, reason=None)` | POST `/v1/compute/:id/cancel`  | —                  |
| `agent.respondToComputeTask(goalId, input)` / Python `client.respond_to_compute_task(...)`             | POST `/v1/compute/:id/respond` | —                  |
| `agent.pauseComputeGoal(goalId, reason?)` / Python `client.pause_compute_goal(goal_id, reason=None)`   | POST `/v1/compute/:id/pause`   | —                  |
| `agent.resumeComputeGoal(goalId)` / Python `client.resume_compute_goal(goal_id)`                       | POST `/v1/compute/:id/resume`  | —                  |
| `agent.fundComputeGoal(goalId, amount)` / Python `client.fund_compute_goal(goal_id, amount)`           | POST `/v1/compute/:id/fund`    | ✅ x402 quote-based |

The Python SDK has feature parity with the TypeScript SDK. Every method has an `a*` async mirror in Python (`acompute`, `aget_compute_goal`, …) for use inside `asyncio` programs.

<Info>
  Tools marked **(quote-based)** accept a `maxCost` option (and a `memo` + `decisionContext` for [audit](/sdk/audit-context)). The SDK compares the quoted price to `maxCost` and throws **before signing any payment** if it exceeds the limit. Non-SDK callers can set the same cap with the `X-Max-Cost-USDC` header — see [Server-side cost cap](#server-side-cost-cap-x-max-cost-usdc) below. All other tools have fixed low-cost pricing.
</Info>

## Server-side cost cap (`X-Max-Cost-USDC`)

For non-SDK callers (raw HTTP, MCP server, Python SDK, custom integrations), set a per-request budget cap by sending the `X-Max-Cost-USDC` header. If the quoted total exceeds your cap, the request is rejected with `400 exceeds_caller_budget` instead of a `402` payment requirement — no payment authorization is ever requested.

```bash theme={null}
curl -X POST https://win.oneshotagent.com/v1/tools/voice/call \
  -H "X-Agent-ID: 0x..." \
  -H "X-Max-Cost-USDC: 2.00" \
  -H "Content-Type: application/json" \
  -d '{"objective":"book a table","target_number":"+14155551234","max_duration_minutes":3}'
```

Rejected response shape:

```json theme={null}
{
  "error": "exceeds_caller_budget",
  "message": "Quote $2.500000 exceeds X-Max-Cost-USDC cap $2.00",
  "quote": { "total": "2.500000", "cap": "2.00" }
}
```

Both numbers come back so the caller can decide whether to retry with a higher cap. The TS SDK (`@oneshot-agent/sdk`) and the Python SDK (`oneshot-python` ≥ 0.11.0) set this header automatically when you pass the `maxCost` / `max_cost` option — you don't need to send it manually.

## All SDKs and Packages

| Package                                                                                | Registry | Language   | Tools                                    |
| -------------------------------------------------------------------------------------- | -------- | ---------- | ---------------------------------------- |
| [`@oneshot-agent/sdk`](https://www.npmjs.com/package/@oneshot-agent/sdk)               | npm      | TypeScript | Full SDK with CDP wallet support         |
| [`@oneshot-agent/mcp-server`](https://www.npmjs.com/package/@oneshot-agent/mcp-server) | npm      | TypeScript | 31 tools for Claude, Cursor, Claude Code |
| [`oneshot-python`](https://pypi.org/project/oneshot-python/)                           | PyPI     | Python     | Core HTTP client with x402 payments      |
| [`langchain-oneshot`](https://pypi.org/project/langchain-oneshot/)                     | PyPI     | Python     | 32 LangChain BaseTool subclasses         |
| [`game-plugin-oneshot`](https://pypi.org/project/game-plugin-oneshot/)                 | PyPI     | Python     | 31 tools for Virtuals GAME agents        |

Source: [github.com/oneshot-agent/sdk](https://github.com/oneshot-agent/sdk)

## Next Steps

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/sdk/installation">
    Install and configure the SDK (TypeScript + Python)
  </Card>

  <Card title="Examples" icon="code" href="/sdk/examples">
    TypeScript code examples
  </Card>

  <Card title="LangChain (Python)" icon="python" href="/sdk/langchain">
    Python integration with 31 LangChain tools
  </Card>

  <Card title="MCP Server" icon="plug" href="/sdk/mcp">
    Use OneShot in Claude Desktop, Cursor, Claude Code
  </Card>

  <Card title="Virtuals GAME SDK" icon="gamepad" href="/sdk/virtuals">
    GAME plugin for Virtuals Protocol agents
  </Card>

  <Card title="Agent Skills" icon="wand-magic-sparkles" href="/sdk/agent-skills">
    Install OneShot skills into Claude Code, Cursor, and 70+ agents
  </Card>

  <Card title="Pricing" icon="dollar-sign" href="/pricing">
    Pay-per-use pricing details
  </Card>
</CardGroup>