Autonomous Agent SDK for executing real-world commercial transactions with automatic x402 payments.
npm install @oneshot-agent/sdkUse the MCP server instead for zero-code integration:
npx -y @oneshot-agent/mcp-serverSee the MCP Server documentation for setup instructions.
import { OneShot } from '@oneshot-agent/sdk';
const agent = new OneShot({
privateKey: process.env.AGENT_PRIVATE_KEY!
});
// Send email
await agent.email({
to: 'user@example.com',
subject: 'Hello',
body: 'Hello World!'
});
// Make a voice call
const call = await agent.voice({
objective: 'Call the restaurant to make a reservation for 2 at 7pm',
target_number: '+14155551234'
});
console.log(call.transcript);
// Send SMS
await agent.sms({
message: 'Your order has shipped!',
to_number: '+14155551234'
});
// Build a website
const site = await agent.build({
type: 'saas',
product: {
name: 'TaskFlow',
description: 'AI-powered task management for remote teams'
}
});
console.log('Live at:', site.production_url);
// Research
const report = await agent.research({ topic: 'AI agents', depth: 'deep' });
// Check balance
const balance = await agent.getBalance(agent.usdcAddress);The SDK operates on Base Mainnet with real USDC. Fund your agent wallet with USDC on Base before making paid tool calls.
agent.usdcAddress; // 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
agent.chainId; // 8453| Method | Description |
|---|---|
| Communication | |
email() |
Send emails with attachments |
voice() |
Make phone calls |
sms() |
Send SMS messages |
inboxList() |
List inbound emails |
inboxGet() |
Get email by ID |
smsInboxList() |
List inbound SMS |
smsInboxGet() |
Get SMS by ID |
notifications() |
List agent notifications |
markNotificationRead() |
Mark notification as read |
| Research & People | |
research() |
Deep web research |
peopleSearch() |
Search people by criteria |
enrichProfile() |
Enrich from LinkedIn/email |
findEmail() |
Find email for a person |
verifyEmail() |
Verify email deliverability |
deepResearchPerson() |
Full dossier on a person |
socialProfiles() |
Find all social accounts |
articleSearch() |
Find articles about a person |
personNewsfeed() |
Recent social posts with engagement |
personInterests() |
Analyze interests across categories |
personInteractions() |
Map followers, following, replies |
| Web & Commerce | |
webSearch() |
Search the web |
webRead() |
Read any URL as markdown + screenshot |
commerceBuy() |
Purchase products |
commerceSearch() |
Search products |
| Browser | |
browser() |
Autonomous browser — navigate, click, extract |
createBrowserProfile() |
Create a persistent browser profile |
listBrowserProfiles() |
List saved browser profiles |
deleteBrowserProfile() |
Delete a browser profile |
| Build | |
build() |
Build and deploy production websites |
updateBuild() |
Update an existing website |
| Compute (Agentic Goals) | |
compute() |
Launch autonomous multi-step goal |
getComputeGoal() |
Get goal status and progress |
getComputeTasks() |
List tasks for a goal |
getComputeBudget() |
Check remaining budget for a goal |
respondToComputeTask() |
Provide input to a pending task |
pauseComputeGoal() |
Pause a running goal |
resumeComputeGoal() |
Resume a paused goal |
cancelComputeGoal() |
Cancel a goal |
fundComputeGoal() |
Add funds to a goal's budget |
| Analytics & Balance | |
getBalance() |
Check token balance |
getUnifiedBalance() |
Get balance across all chains |
spendBreakdown() |
Spending breakdown by tool/period |
rocs() |
Return on compute stats |
receiptsList() |
List payment receipts |
tagReceiptValue() |
Tag a receipt with business value |
interface OneShotConfig {
privateKey: string; // Required
baseUrl?: string; // Override API URL
rpcUrl?: string; // Override RPC URL
debug?: boolean; // Enable logging
logger?: (msg: string) => void;
}All methods accept these common options:
interface ToolOptions {
maxCost?: number; // Max USDC willing to pay (see supported tools below)
timeout?: number; // Timeout in seconds
signal?: AbortSignal; // Cancel before payment (see Cancellation section)
wait?: boolean; // Wait for async jobs (default: true)
onStatusUpdate?: (status: string, requestId: string) => void;
}The maxCost option is a client-side guard — the SDK compares the quoted price against your limit and throws before signing any payment if it exceeds it. This is supported on tools with variable pricing:
| Method | maxCost |
|---|---|
commerceBuy() |
Supported |
voice() |
Supported |
sms() |
Supported |
build() / updateBuild() |
Supported |
browser() |
Supported |
| All other tools | Not applicable (fixed low-cost pricing) |
import {
ValidationError,
ToolError,
JobError,
JobTimeoutError,
ContentBlockedError,
EmergencyNumberError
} from '@oneshot-agent/sdk';
try {
await agent.voice({
objective: 'Make a call',
target_number: '+14155551234'
});
} catch (error) {
if (error instanceof ContentBlockedError) {
// Content blocked by safety filters
console.log(`Blocked: ${error.message}`);
console.log(`Categories: ${error.categories.join(', ')}`);
} else if (error instanceof EmergencyNumberError) {
// Attempted to call/SMS emergency number
console.log(`Emergency number blocked: ${error.blockedNumber}`);
} else if (error instanceof ValidationError) {
console.log(`Invalid: ${error.field}`);
} else if (error instanceof ToolError) {
console.log(`API error: ${error.statusCode}`);
} else if (error instanceof JobTimeoutError) {
console.log(`Timeout: ${error.jobId}`);
}
}// Build a SaaS landing page
const site = await agent.build({
type: 'saas',
product: {
name: 'TaskFlow',
description: 'AI-powered task management for remote teams. Automate workflows, track progress, and collaborate seamlessly.',
industry: 'Productivity',
pricing: 'Free tier, Pro $12/mo, Team $29/mo'
},
lead_capture: { enabled: true },
brand: {
primary_color: '#4F46E5',
tone: 'professional'
}
});
console.log('Website URL:', site.production_url);
console.log('Preview:', site.preview_url);
// Update existing website
const updated = await agent.updateBuild({
build_id: site.request_id,
product: {
name: 'TaskFlow 2.0',
description: 'Now with AI automation! Task management reimagined.',
pricing: 'Free tier, Pro $15/mo, Team $35/mo'
}
});Build types: saas, portfolio, agency, personal, product, funnel, restaurant, event
// Simple call
const call = await agent.voice({
objective: 'Call to schedule a dentist appointment for next Tuesday',
target_number: '+14155551234',
caller_persona: 'A polite assistant scheduling an appointment',
context: 'Patient prefers morning appointments',
maxCost: 5
});
console.log('Transcript:', call.transcript);
console.log('Summary:', call.summary);
console.log('Success:', call.success_evaluation);
// Conference call (multiple numbers)
const conference = await agent.voice({
objective: 'Connect the buyer and seller to negotiate the final price',
target_number: ['+14155551234', '+14155555678'],
caller_persona: 'A professional meeting facilitator'
});// Single recipient
await agent.sms({
message: 'Your appointment is confirmed for tomorrow at 10am',
to_number: '+14155551234'
});
// Multiple recipients (up to 10)
await agent.sms({
message: 'Team meeting moved to 3pm',
to_number: ['+14155551234', '+14155555678', '+14155559012']
});
// Check SMS inbox
const inbox = await agent.smsInboxList({ limit: 10 });
for (const msg of inbox.messages) {
console.log(`From ${msg.from}: ${msg.body}`);
}
// Get specific message
const msg = await agent.smsInboxGet('msg_abc123');await agent.email({
to: ['alice@example.com', 'bob@example.com'],
subject: 'Report',
body: 'See attached.',
attachments: [{
filename: 'report.pdf',
content: base64Content,
content_type: 'application/pdf'
}]
});const results = await agent.peopleSearch({
job_titles: ['CEO', 'CTO'],
companies: ['Stripe'],
limit: 10
});
const profile = await agent.enrichProfile({
linkedin_url: results.results[0].linkedin_url
});const order = await agent.commerceBuy({
product_url: 'https://amazon.com/dp/B07ZPC9QD4',
shipping_address: {
first_name: 'John',
last_name: 'Doe',
street: '123 Main St',
city: 'San Francisco',
state: 'CA',
zip_code: '94102',
country: 'US',
phone: '4155550100'
},
maxCost: 100
});// List notifications
const notifications = await agent.notifications({ unread: true, limit: 20 });
for (const n of notifications.notifications) {
console.log(`[${n.type}] ${n.title}: ${n.message}`);
}
// Mark as read
await agent.markNotificationRead('notification-uuid');Use AbortSignal to cancel operations before payment is made. Once payment is signed, the operation will execute regardless of cancellation.
const controller = new AbortController();
// Cancel after 5 seconds if still in quote phase
setTimeout(() => controller.abort(), 5000);
try {
await agent.voice({
objective: 'Make a reservation',
target_number: '+14155551234',
signal: controller.signal
});
} catch (error) {
if (error.message === 'Operation cancelled before payment') {
console.log('Cancelled before paying - no charge');
}
}Important: The signal can cancel:
- Quote requests (before receiving price)
- The decision phase (after quote, before payment)
The signal cannot cancel:
- Operations after payment is signed (call/SMS will still execute)
- Server-side job execution
- Documentation
- MCP Server — Claude Desktop, Cursor, Claude Code
- Python SDK (LangChain) — 26 tools as LangChain BaseTool
- Python SDK (Core) — HTTP client with x402 payments
- Pricing
- GitHub
MIT