Initialize
- CDP Wallet (Recommended)
- Private Key
import { OneShot } from "@oneshot-agent/sdk";
// No private keys — signing in Coinbase's secure enclave
const agent = await OneShot.create({ cdp: true });
import { OneShot } from "@oneshot-agent/sdk";
const agent = new OneShot({
privateKey: process.env.AGENT_PRIVATE_KEY,
});
// Simple email
await agent.email({
to: "[email protected]",
subject: "Hello from OneShot",
body: "This email was sent autonomously!",
});
// Email with attachments
await agent.email({
to: "[email protected]",
subject: "Report attached",
body: "Please find the report attached.",
attachments: [
{
filename: "report.pdf",
content: base64Content,
content_type: "application/pdf",
},
],
});
// Custom sender — display name, mailbox, and domain.
// Renders as: From: Jane Doe <[email protected]>
await agent.email({
to: "[email protected]",
subject: "Hello",
body: "Sent from a custom sender.",
from_name: "Jane Doe", // display name (optional)
from_mailbox: "jane", // one of the domain's addresses; defaults to its main one
from_domain: "acme.com", // a domain you bought or connected
});
from_domain must be a domain you bought or connected, and from_mailbox one
of its addresses (default: its main address). from_name is the display name
recipients see; omit it to send from the bare address.Mailboxes or addresses: the domain purchase picks the mode and names the
addresses.
quoteDomain(name, { mailbox_mode: "mailbox", addresses: ["jane"] })
gives each address a hosted inbox, warmed before it sends, with a one-time
mailbox_provisioning_fee per address on the quote. The default relay
addresses send and receive with no inbox, free. The mode is fixed once
bought: a different one on a later quote returns 409 mailbox_mode_conflict.
An address the domain lacks makes email() return confirmation_required
with the quote that adds it; nothing is sent.Bulk email
import { OneShot } from "@oneshot-agent/sdk";
const agent = new OneShot({
privateKey: process.env.AGENT_PRIVATE_KEY,
});
// Send to multiple recipients
await agent.email({
to: ["[email protected]", "[email protected]", "[email protected]"],
subject: "Weekly Team Update",
body: "Here is this week's progress report...",
});
// Each recipient gets an individual email (not CC/BCC)
The SDK handles bulk quoting. Service fees scale with the number of
recipients.
Voice calls
import { OneShot } from "@oneshot-agent/sdk";
const agent = new OneShot({
privateKey: process.env.AGENT_PRIVATE_KEY,
});
// Simple call - make a restaurant reservation
const result = await agent.voice({
objective: "Make a dinner reservation for 2 at 7pm tonight",
target_number: "+14155551234",
caller_persona: "A polite assistant making a reservation",
context: "Italian restaurant, prefer outdoor seating",
});
console.log("Transcript:", result.transcript);
console.log("Summary:", result.summary);
console.log("Success:", result.success_evaluation);
// Conference call - connect multiple parties
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",
});
SMS
import { OneShot } from "@oneshot-agent/sdk";
const agent = new OneShot({
privateKey: process.env.AGENT_PRIVATE_KEY,
});
// Single recipient
const result = await agent.sms({
message: "Your order has shipped! Track it at example.com/track/123",
to_number: "+14155551234",
});
// Multiple recipients (up to 10)
const bulkResult = await agent.sms({
message: "Team meeting moved to 3pm",
to_number: ["+14155551234", "+14155555678", "+14155559012"],
});
// Check SMS inbox for replies
const inbox = await agent.smsInboxList({ limit: 10 });
for (const msg of inbox.messages) {
console.log(`From ${msg.from}: ${msg.body}`);
}
// Get a specific message
const message = await agent.smsInboxGet("msg_abc123");
Deep research
// Quick research (5-10 sources, 2-3 minutes)
const quickReport = await agent.research({
topic: "Latest developments in AI agents",
depth: "quick",
});
console.log(quickReport.report_content);
console.log(`Sources: ${quickReport.sources_count}`);
// Comprehensive research (20+ sources, 5-10 minutes)
const deepReport = await agent.research({
topic: "Blockchain scalability solutions",
depth: "deep",
});
console.log(deepReport.report_content);
Poll inbox
// List recent emails
const inbox = await agent.inboxList({
include_body: true,
limit: 10,
});
for (const email of inbox.emails) {
console.log(`From: ${email.from}`);
console.log(`Subject: ${email.subject}`);
console.log(`Body: ${email.body}`);
// Process attachments
if (email.attachments) {
for (const att of email.attachments) {
const buffer = Buffer.from(att.content, "base64");
// Process attachment...
}
}
}
// Get emails since a specific time
const recentInbox = await agent.inboxList({
since: "2024-01-01T00:00:00Z",
include_body: true,
});
// Get a specific email by ID
const specificEmail = await agent.inboxGet("email-id-here");
People search and enrichment
// Search for people by criteria
const results = await agent.personFind({
job_titles: ["CEO", "CTO", "VP Engineering"],
company_domains: ["stripe.com", "anthropic.com"],
location: ["San Francisco"],
limit: 20,
});
console.log(`Found ${results.total_found} people`);
for (const person of results.results) {
console.log(`${person.full_name} - ${person.title} at ${person.company}`);
// Enrich profile for more details
const profile = await agent.personProfile({
linkedin_url: person.linkedin_url,
});
console.log(`Skills: ${profile.profile.skills?.join(", ")}`);
}
seniority takes any of owner, founder, c_suite, partner, vp, head, director, manager, senior, entry, intern. Common variants ("Vice President", "C-Level", "executive") are accepted, and a value that matches no level fails the search with invalid_input. industry is free text.
An empty results array means the search ran and nobody matched. If the search could not be run, the call throws a JobError with a retryable code (service_unavailable, service_auth, rate_limited) instead of returning an empty result.
Find and verify email
// Find email for a person
const found = await agent.personEmail({
name: "Dario Amodei",
company: "Anthropic",
});
if (found.found) {
console.log(`Found email: ${found.email}`);
// Verify before sending
const verification = await agent.personEmailStatus({
email: found.email,
});
if (verification.deliverable) {
await agent.email({
to: found.email,
subject: "Hello",
body: "Your message here...",
});
}
}
Commerce: search and buy
// Search for products
const products = await agent.productFind({
query: "USB-C hub multiport",
limit: 5,
});
console.log(`Found ${products.count} products`);
// Buy the first result
const order = await agent.commerceBuy({
product_url: products.products[0].product_url,
shipping_address: {
first_name: "John",
last_name: "Doe",
street: "123 Main St",
city: "San Francisco",
state: "CA",
zip_code: "94102",
country: "US",
phone: "4155550100",
email: "[email protected]",
},
quantity: 1,
maxCost: 100, // Fail if total exceeds the cap
});
console.log(`Order submitted: ${order.request_id}`);
Web search
Search the web and get structured results synchronously, without polling:// Quick web search
const results = await agent.webSearch({
query: "best AI agent frameworks 2026",
max_results: 10,
});
for (const result of results.results) {
console.log(`${result.title}: ${result.url}`);
}
Web read
Read a web page as markdown, with a screenshot:// Read a web page
const page = await agent.webRead({
url: "https://news.ycombinator.com",
});
console.log(page.markdown); // Page content as markdown
console.log(page.screenshot_url); // Private org artifacts require an org session; see /api-reference/web-read.
console.log(page.metadata.title); // Page title
Browser automation
// Extract structured data from a website
const result = await agent.browser({
task: "Go to producthunt.com and extract the top 5 AI products launched today",
output_schema: {
products: [{
name: "string",
description: "string",
upvotes: "number"
}]
}
});
console.log("Products:", result.output.products);
console.log("Steps taken:", result.steps.length);
console.log("Cost:", result.cost, "USDC");
// Resume a previous browser session (preserves cookies/login state)
const followUp = await agent.browser({
task: "Click on the first product and extract the full description",
session_id: result.session_id,
});
Person intelligence
Look up a person by name+company, email, phone or profile URL. Each method runs async and returns when the job finishes.// Person profile, known social accounts, articles, posts and written summary (takes 2-5 minutes)
const dossier = await agent.personDossier({
email: "[email protected]",
name: "Satya Nadella",
company: "Microsoft",
timeout: 300, // seconds; the dossier takes a few minutes
});
// Emails and phones are nested inside result.profile.data
const enrichment = dossier.result.profile.data;
console.log("Work email:", enrichment.best_work_email);
console.log("Personal email:", enrichment.best_personal_email);
console.log("All emails:", enrichment.altemails);
console.log("Phone:", enrichment.fullphone?.[0]?.fullphone);
console.log("Company:", enrichment.company);
console.log("LinkedIn:", enrichment.linkedin_url);
// Check each section state before consuming its data
console.log("Profile, known social accounts, articles, posts and written summary:", dossier.result);
// Find their accounts on LinkedIn, Twitter, GitHub, etc
const socials = await agent.personSocialAccounts({
email: "[email protected]",
});
console.log(socials.result);
// Articles and interviews mentioning them
const articles = await agent.personArticles({
name: "Satya Nadella",
company: "Microsoft",
sort: "recent",
limit: 5,
});
console.log(articles.result);
// Recent posts with likes, replies, shares
const feed = await agent.personPosts({
name: "Satya Nadella",
company: "Microsoft",
});
console.log(feed.result);
// What they care about (sports, tech, politics, etc)
const interests = await agent.personInterests({
email: "[email protected]",
});
console.log(interests.result);
// Who they follow and who follows them
const interactions = await agent.personFollowers({
profile_url: "https://x.com/satyanadella",
type: "followers,following",
max_results: 50,
});
console.log(interactions.result);
Universal tool method
// Email quote
const quote = await agent.tool("email/quote", {
from_address: "[email protected]",
to_address: "[email protected]",
subject: "Test",
body: "Hello",
});
console.log(`Cost: $${quote.total_cost}`);
// Email send (with quote ID)
const send = await agent.toolWithQuote(
"email/send",
{
from_address: "[email protected]",
to_address: "[email protected]",
subject: "Test",
body: "Hello",
},
quote.quote_id,
);
Get balance
const agent = new OneShot({
privateKey: process.env.AGENT_PRIVATE_KEY,
});
console.log("Agent address:", agent.address);
const balance = await agent.getBalance(agent.usdcAddress);
console.log(`Wallet balance: ${balance} USDC`);
if (parseFloat(balance) < 1.0) {
console.warn("Low balance! Please fund your wallet.");
}
The
agent.usdcAddress getter returns the USDC contract address on Base Mainnet: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.Spend budgets
Cap the agent’s spend per day and per call. The API enforces the cap, so it survives restarts and applies across every process using this wallet:import { OneShot, BudgetExceededError } from "@oneshot-agent/sdk";
const agent = await OneShot.create({
cdp: true,
budgets: { daily: 50, perTransaction: 5, alertAt: 0.8 },
alerts: { email: "[email protected]" },
});
try {
await agent.research({ topic: "competitor pricing", memo: "weekly scan" });
} catch (err) {
if (err instanceof BudgetExceededError) {
// reason: "daily" | "per_transaction"; nothing was charged
console.warn(`Budget ${err.reason} hit — $${err.spent} spent today, resumes ${err.resetsAt}`);
} else {
throw err;
}
}
const status = await agent.budgets();
console.log(`${(status.pct_used! * 100).toFixed(0)}% of today's budget used`);
Error handling
import {
OneShot,
ContentBlockedError,
EmergencyNumberError,
BudgetExceededError,
} from "@oneshot-agent/sdk";
try {
await agent.sms({
message: "Your appointment is confirmed",
to_number: "+14155551234",
});
} catch (error) {
if (error instanceof ContentBlockedError) {
// Message flagged by content safety
console.error("Content blocked:", error.categories);
} else if (error instanceof EmergencyNumberError) {
// Attempted to contact emergency services
console.error("Emergency number blocked:", error.blockedNumber);
} else if (error instanceof BudgetExceededError) {
// The agent's own spend budget stopped the call; nothing was charged
console.error(`Budget ${error.reason} exceeded, resets ${error.resetsAt}`);
} else if (error.message.includes("Insufficient balance")) {
console.error("Not enough funds in wallet");
} else if (error.message.includes("domain_unavailable")) {
console.error("Domain is not available");
} else {
console.error("Error:", error.message);
}
}
Build production websites
import { OneShot } from "@oneshot-agent/sdk";
const agent = new OneShot({
privateKey: process.env.AGENT_PRIVATE_KEY,
});
// Build a SaaS landing page
const result = 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 live at:", result.production_url);
console.log("Preview:", result.preview_url);
Update existing website
import { OneShot } from "@oneshot-agent/sdk";
const agent = new OneShot({
privateKey: process.env.AGENT_PRIVATE_KEY,
});
// Update with new content
const result = await agent.updateBuild({
build_id: "550e8400-e29b-41d4-a716-446655440000", // from original build
product: {
name: "TaskFlow 2.0",
description: "Now with AI automation! Task management reimagined for modern teams.",
pricing: "Free tier, Pro $15/mo, Team $35/mo"
}
});
console.log("Updated:", result.production_url);
Complete agent example
import { OneShot } from "@oneshot-agent/sdk";
class EmailAgent {
private agent: OneShot;
private lastCheck: string;
private constructor(agent: OneShot) {
this.agent = agent;
this.lastCheck = new Date().toISOString();
}
static async create() {
// CDP wallet — no private keys in config
const agent = await OneShot.create({ cdp: true });
return new EmailAgent(agent);
}
async start() {
console.log(`Agent started: ${this.agent.address}`);
// Poll inbox every minute
setInterval(() => this.pollInbox(), 60000);
}
async pollInbox() {
try {
const inbox = await this.agent.inboxList({
since: this.lastCheck,
include_body: true,
limit: 50,
});
if (inbox.count > 0) {
console.log(`Received ${inbox.count} new email(s)`);
for (const email of inbox.emails) {
await this.processEmail(email);
}
this.lastCheck = new Date().toISOString();
}
} catch (error) {
console.error("Error polling inbox:", error);
}
}
async processEmail(email: any) {
console.log(`Processing email from ${email.from}`);
const reply = await this.generateReply(email);
await this.agent.email({
to: email.from,
subject: `Re: ${email.subject}`,
body: reply,
});
console.log(`Replied to ${email.from}`);
}
async generateReply(email: any): Promise<string> {
// Use your LLM here to generate a reply
return `Thank you for your email. I'll get back to you soon!`;
}
}
// Start the agent
const agent = await EmailAgent.create();
agent.start();
Next steps
API Reference
API reference
SDK Source
SDK source
Optional phone lookup
const people = await agent.personFind({ job_titles: ['CTO'], limit: 3, includePhone: true, maxCost: 1, waitForPhones: true });
const profile = await agent.personProfile({ email: '[email protected]', includePhone: true, maxCost: 1, waitForPhones: true });
const dossier = await agent.personDossier({ email: '[email protected]', includePhone: true, maxCost: 1, waitForPhones: true, timeout: 600 });
waitForPhones waits without purchasing phones. onStatusUpdate('completed', requestId)
fires after this wait, before resolution; phones_pending: true may remain on timeout.
people = client.person_find(job_titles=["CTO"], limit=3, include_phone=True, max_cost=1, wait_for_phones=True)
profile = await client.aperson_profile(email="[email protected]", include_phone=True, max_cost=1, wait_for_phones=True)
dossier = await client.aperson_dossier(email="[email protected]", include_phone=True, max_cost=1, wait_for_phones=True, timeout_sec=600)