Skip to main content

​
What is the OneShot SDK?

The OneShot SDK is the commercial action layer for AI agents. It provides a unified interface for autonomous agents to execute commercial transactions (email, payments, research, and more) with native x402 billing — all in one API call.
  • Automatic x402 Payments: Signs and submits payment authorizations automatically
  • Wallet Management: Uses ethers.js for secure key handling
  • Job Polling: Waits for async jobs to complete
  • 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
  • Clean error messages
  • Minimal token usage in prompts

​
Quick Example

import { OneShot } from '@oneshot/sdk';

// Initialize with a Private Key (not a wallet address)
// This allows the agent to sign payments autonomously
const agent = new OneShot({
  privateKey: process.env.AGENT_PRIVATE_KEY // e.g. "0xac09..."
});

// Send email (handles quote + payment + send automatically)
await agent.email({
  to: '[email protected]',
  subject: 'Hello from OneShot',
  body: 'This was sent autonomously!'
});

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

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

Wallet Management

Built on ethers.js for secure private key handling

​
Supported Tools

  • Email: Send emails with automatic domain provisioning
  • Research: AI-powered deep research with sources
  • Universal Tool: Call any OneShot tool with agent.tool(name, options)

​
Next Steps

Installation

Install and configure the SDK

Examples

See complete code examples