OneShot SDK Overview

What is the OneShot SDK?

The SDK adds email, research, voice, web, and commerce tools to the agent you already run, on your current model, framework, and hosting. Call agent.email() from your own code and use the result in your workflow. The SDK signs payments and polls jobs. OneShot provides guaranteed execution: it owns execution, error recovery, and retries through completion. Paid actions come with signed receipts and spend tracking. Attach memo + decisionContext to any paid call and both are stored on the receipt, for debugging and supervisor agents (see Audit Trail). Add your first tool, or explore the supported tools.

The SDK operates on Base Mainnet with real USDC. Fund your agent wallet before making paid tool calls.

Why Use the SDK?

It collapses the payment flow into one call, for you and for the agent.

For Humans

One call replaces the manual payment flow:

// Without SDK: Handle 402 responses, sign payments, poll jobs manually
// With SDK: One line
await agent.email({ to: "[email protected]", subject: "Hi", body: "Hello" });

For AI Agents

An autonomous agent gets:

The payment flow, handled for them
Automatic retries on rate limits
Clean error messages
Minimal token usage in prompts

Quick Example

CDP Wallet (Recommended)
Private Key

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: "[email protected]",
  subject: "Hello from OneShot",
  body: "This was sent autonomously!",
});

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);

Key Features

The SDK handles payment and polling, and the API enforces spend limits. Your agent code holds only the call.

Automatic Payments

The SDK runs the x402 payment flow, including signing

Job Polling

Waits for async jobs and returns their results

Type Safety

TypeScript types for all tools

Flexible Wallets

Coinbase CDP Server Wallets (recommended, no private keys) or a raw key via ethers.js

Pay with ETH

Tops up USDC from ETH via Uniswap V3 when the balance runs low, so you don’t need to hold USDC

Spend Budgets

Daily and per-call caps enforced server-side, so the agent stops before the wallet empties

Read Authentication

Read calls prove you control the wallet, and the SDK signs that proof for you. Read endpoints (email/SMS inbox, notifications, balance, and browser profiles) return private, per-agent data. A wallet address is public; without the proof, anyone could read your inbox by supplying your address. 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 and a short freshness window (5 min) prevent replay.

Provide wallet credentials (a raw private key or a Coinbase CDP Server Wallet via cdp: true) and the SDK handles the rest.

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 that they must send a valid x-agent-proof, so upgrade before then.

Supported Tools

Every tool is a method on agent. Tool names link to their API reference. (quote-based) marks tools whose price varies per call. They accept a client-side maxCost guard, and the SDK throws before signing if the quote exceeds it.

Communication

Tool	Method	Description
Email	`agent.email()`	Send emails with attachments
Voice	`agent.voice()`	Place a phone call (quote-based)
SMS	`agent.sms()`	Send SMS messages (quote-based)

Inbox & Notifications

Tool	Method	Description
Email Inbox	`agent.inboxList()`	List inbound emails
Email Message	`agent.inboxGet(id)`	Get a specific email by ID
SMS Inbox	`agent.smsInboxList()`	List inbound SMS messages
SMS Message	`agent.smsInboxGet(id)`	Get a specific SMS by ID
Notifications	`agent.notifications()`	List agent notifications
Mark Read	`agent.markNotificationRead(id)`	Mark notification as read

Person Intelligence

Tool	Method	Description
People Search	`agent.peopleSearch()`	Search for people by criteria
Profile Enrichment	`agent.enrichProfile()`	Enrich from LinkedIn/email
Email Finder	`agent.findEmail()`	Find email for a person
Email Verification	`agent.verifyEmail()`	Verify email deliverability
Company Search	`agent.companySearch()`	Search companies by name, domain, industry, location, size
Company Enrichment	`agent.enrichCompany()`	Enrich a company from domain, name, LinkedIn URL, or ticker
Local Search	`agent.localSearch()`	Discover local businesses by category × location
Local Resolve	`agent.localResolve()`	Business name + address → domain, phone, status, confidence
Government Solicitations	`agent.govSolicitations()`	Federal Sources Sought / Presolicitation notices by NAICS with the contracting officer’s contact
Deep Research Person	`agent.deepResearchPerson()`	Full dossier on a person (2-5 min)
Social Profiles	`agent.socialProfiles()`	Find all social accounts for a person
Article Search	`agent.articleSearch()`	Find articles about a person
Person Newsfeed	`agent.personNewsfeed()`	Recent social posts with engagement
Person Interests	`agent.personInterests()`	Analyze interests across categories
Person Interactions	`agent.personInteractions()`	Map followers, following, replies

Web & Research

Tool	Method	Description
Research	`agent.research()`	Deep web research with sources
Web Search	`agent.webSearch()`	Search the web, get results instantly
Web Read	`agent.webRead()`	Read any URL as markdown + screenshot
Browser	`agent.browser()`	Autonomous browser: navigate, click, extract (quote-based)
Browser Profile	`agent.createBrowserProfile()`	Create persistent browser profile (cookies/sessions)
Account Login / 2FA	`agent.startBrowserProfileSetup()` / `getBrowserProfileSetup()` / `finishBrowserProfileSetup()`	Connect an account through a private live browser
List Profiles	`agent.listBrowserProfiles()`	List all browser profiles
Delete Profile	`agent.deleteBrowserProfile(id)`	Delete a browser profile

Commerce

Tool	Method	Description
Commerce Search	`agent.commerceSearch()`	Search for products
Commerce Buy	`agent.commerceBuy()`	Purchase products (quote-based)

Build

Tool	Method	Description
Build	`agent.build()`	Build and deploy production websites (quote-based)
Update Build	`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`	No
`agent.getComputeTasks(goalId)` / Python `client.get_compute_tasks(goal_id)`	GET `/v1/compute/:id/tasks`	No
`agent.getComputeBudget(goalId)` / Python `client.get_compute_budget(goal_id)`	GET `/v1/compute/:id/budget`	No
`agent.cancelComputeGoal(goalId, reason?)` / Python `client.cancel_compute_goal(goal_id, reason=None)`	POST `/v1/compute/:id/cancel`	No
`agent.respondToComputeTask(goalId, input)` / Python `client.respond_to_compute_task(...)`	POST `/v1/compute/:id/respond`	No
`agent.pauseComputeGoal(goalId, reason?)` / Python `client.pause_compute_goal(goal_id, reason=None)`	POST `/v1/compute/:id/pause`	No
`agent.resumeComputeGoal(goalId)` / Python `client.resume_compute_goal(goal_id)`	POST `/v1/compute/:id/resume`	No
`agent.fundComputeGoal(goalId, amount)` / Python `client.fund_compute_goal(goal_id, amount)`	POST `/v1/compute/:id/fund`	✅ x402 quote-based

Goal IDs are UUIDs. Reads (goal, tasks, budget) send a signed read proof and lifecycle calls (cancel, respond, pause, resume) a signed write proof; the SDK adds both. Pause, resume, and fund work on recurring goals only (created with schedule). Unspent budget comes back as OneShot credits when a goal ends. See Create Goal. The Python SDK matches the TypeScript SDK, including access-token sessions (OneShotClient.create(access_token=...), oneshot-python ≥ 0.26.0). Every Python method has an a* async mirror (acompute, aget_compute_goal, …) for asyncio programs.

Tools marked (quote-based) accept a maxCost option (and memo + decisionContext for audit). If the quoted price exceeds maxCost, the SDK throws before signing any payment. Non-SDK callers can set the same cap with the X-Max-Cost-USDC header; see Server-side cost cap below. All other tools have fixed low-cost pricing.

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

A request priced over its X-Max-Cost-USDC cap fails before any payment is requested. Non-SDK callers (raw HTTP, MCP server, Python SDK, custom integrations) set the header themselves. If the quoted total exceeds the cap, the API returns 400 exceeds_caller_budget instead of a 402 payment requirement.

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:

{
  "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 are returned 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 when you pass the maxCost / max_cost option.

Spend Budgets

maxCost guards one call. A spend budget guards the wallet: a daily cap (UTC day) and a per-call cap, stored per agent and enforced by the API against the receipt ledger. The total therefore holds across every process, restart, and serverless invocation using the same wallet. Concurrent paid calls are serialized through an atomic in-flight reservation (Redis). If Redis is unavailable, the guard falls back to a best-effort ledger check instead of blocking payments.

const agent = await OneShot.create({
  cdp: true,
  budgets: {
    daily: 50,           // max USDC per UTC day
    perTransaction: 5,   // max USDC for any single call
    alertAt: 0.8,        // notify at 80% of daily
    pauseAt: 1.0,        // stop paying at 100%
  },
  alerts: { email: "[email protected]" },
});

client = OneShotClient(
    "0x...",
    budgets={"daily": 50, "per_transaction": 5, "alert_at": 0.8, "pause_at": 1.0},
    alert_email="[email protected]",
)

The config syncs once, before the first paid call. At alertAt you get a budget_warning notification (in-app, plus email if set). At pauseAt, paid calls fail with a typed error until the window resets at the next UTC midnight:

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

try {
  await agent.research({ topic: "..." });
} catch (err) {
  if (err instanceof BudgetExceededError) {
    console.log(`${err.reason} budget hit — $${err.spent} spent, resumes ${err.resetsAt}`);
  }
}

const b = await agent.budgets();
// { daily_usdc: 50, spent_today_usdc: "41.20", pct_used: 0.824, resets_at: "…" }

from oneshot import BudgetExceededError

try:
    client.research(topic="...")
except BudgetExceededError as e:
    print(f"{e.reason} budget hit — ${e.spent} spent, resumes {e.resets_at}")

client.get_budgets()

Omit budgets to leave the server-side setting untouched. Agents without a budget are unlimited. The sync fails closed: if the server can’t confirm the budget, the paid call raises BudgetSyncError and is not made (the sync retries on the next call), because proceeding would silently drop the guardrail. An invalid config throws ValidationError at construction. The MCP server reads the same config from ONESHOT_BUDGET_* environment variables. Every agent framework package exposes a read-only oneshot_budget_status tool, so the agent can plan around its remaining budget but never raise it. Full contract: Spend Budgets API.

Requires TypeScript SDK ≥ 0.27.0 or oneshot-python ≥ 0.20.0. The budget endpoints always require the signed read proof.

All SDKs and Packages

Five packages, one API. Pick by language and framework.

Package	Registry	Language	Tools
`@oneshot-agent/sdk`	npm	TypeScript	Full SDK with CDP wallet support
`@oneshot-agent/mcp-server`	npm	TypeScript	Every tool for Claude, Cursor, Claude Code
`oneshot-python`	PyPI	Python	Core HTTP client with x402 payments
`langchain-oneshot`	PyPI	Python	35 LangChain BaseTool subclasses
`game-plugin-oneshot`	PyPI	Python	Tools for Virtuals GAME agents

Source: github.com/oneshot-agent/sdk

Next Steps

Installation

Install and configure the SDK (TypeScript + Python)

Examples

TypeScript code examples

LangChain (Python)

Python integration with 31 LangChain tools

MCP Server

Use OneShot in Claude Desktop, Cursor, Claude Code

Virtuals GAME SDK

GAME plugin for Virtuals Protocol agents

Agent Skills

Install OneShot skills into Claude Code, Cursor, and 70+ agents

Pricing

Pay-per-use pricing details

​What is the OneShot SDK?

​Why Use the SDK?

​For Humans

​For AI Agents

​Quick Example

​Key Features

Automatic Payments

Job Polling

Type Safety

Flexible Wallets

Pay with ETH

Spend Budgets

​Read Authentication

​Supported Tools

​Communication

​Inbox & Notifications

​Person Intelligence

​Web & Research

​Commerce

​Build

​Utility

​Compute: autonomous goal orchestration

​Server-side cost cap (X-Max-Cost-USDC)

​Spend Budgets

​All SDKs and Packages

​Next Steps

Installation

Examples

LangChain (Python)

MCP Server

Virtuals GAME SDK

Agent Skills

Pricing

What is the OneShot SDK?

Why Use the SDK?

For Humans

For AI Agents

Quick Example

Key Features

Read Authentication

Supported Tools

Communication

Inbox & Notifications

Person Intelligence

Web & Research

Commerce

Build

Utility

Compute: autonomous goal orchestration

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

Spend Budgets

All SDKs and Packages

Next Steps