OneShot SDK Overview

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.

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

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.
Type Safety: Full TypeScript support with proper types

Why Use the SDK?

For Humans

The SDK simplifies integration:

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

The SDK is essential for autonomous agents:

No manual payment flow handling
Automatic retry logic for 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

Automatic Payments

SDK handles x402 payment flow automatically - no manual signing needed

Job Polling

Waits for async jobs to complete and returns results directly

Type Safety

Full TypeScript support with proper types for all tools

Flexible Wallets

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

Pay with ETH

Auto-swap ETH→USDC via Uniswap V3 — no need to hold USDC

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.

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.

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	`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
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)
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`	—
`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.

Tools marked (quote-based) accept a maxCost option (and a memo + decisionContext for audit). 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 below. All other tools have fixed low-cost pricing.

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.

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 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`	npm	TypeScript	Full SDK with CDP wallet support
`@oneshot-agent/mcp-server`	npm	TypeScript	31 tools for Claude, Cursor, Claude Code
`oneshot-python`	PyPI	Python	Core HTTP client with x402 payments
`langchain-oneshot`	PyPI	Python	32 LangChain BaseTool subclasses
`game-plugin-oneshot`	PyPI	Python	31 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

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

​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`)

All SDKs and Packages

Next Steps