OneShot#

Infrastructure for autonomous AI agents to execute real-world commercial transactions: email, payments, e-commerce, research, and data enrichment with native x402 payments.

Quick Start#

bash

npm install @oneshot-agent/sdk

With CDP Wallet (Recommended — no private keys):

typescript

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

// Reads CDP_API_KEY_ID, CDP_API_KEY_SECRET, CDP_WALLET_SECRET from env
const agent = await OneShot.create({ cdp: true });

// Send an email
await agent.email({
  to: 'recipient@example.com',
  subject: 'Hello from my agent',
  body: 'This email was sent autonomously.'
});

With Raw Private Key:

typescript

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

const agent = new OneShot({
  privateKey: process.env.ONESHOT_WALLET_PRIVATE_KEY
});

Authentication#

OneShot uses x402 payments (USDC on Base). Two wallet options:

Option A: Coinbase CDP Wallet (Recommended)#

Server-side wallet managed by Coinbase — no private keys in your config. Signing happens in Coinbase's secure enclave (TEE).

bash

export CDP_API_KEY_ID="your-api-key-id"
export CDP_API_KEY_SECRET="your-api-key-secret"
export CDP_WALLET_SECRET="your-wallet-secret"

typescript

const agent = await OneShot.create({ cdp: true });

Get credentials at Coinbase Developer Platform. The SDK auto-creates a wallet on first use. Optional: npm install @coinbase/cdp-sdk

Option B: Raw Private Key (Advanced)#

Direct wallet control for agents managing their own keys:

bash

export ONESHOT_WALLET_PRIVATE_KEY="0xYourPrivateKey"

typescript

const agent = new OneShot({ privateKey: process.env.ONESHOT_WALLET_PRIVATE_KEY });

Custom Wallet Provider#

Bring your own signing implementation:

typescript

const agent = await OneShot.create({
  walletProvider: {
    address: '0x...',
    signTypedData: async (domain, types, value) => signature
  }
});

Test Mode: SDK runs in test mode by default (Base Sepolia testnet). Set ONESHOT_TEST_MODE=false for production.

SDK Methods#

Email#

typescript

// Send email (~$0.01 per email, ~$10 first-time domain setup)
const result = await agent.email({
  to: 'recipient@example.com',
  subject: 'Subject line',
  body: 'Email body content',
  attachments: [{ filename: 'doc.pdf', content: base64String }]
});

// Bulk email
const result = await agent.email({
  to: ['user1@example.com', 'user2@example.com'],
  subject: 'Bulk message',
  body: 'Sent to multiple recipients'
});

Inbox#

typescript

// List inbound emails (free)
const emails = await agent.inboxList();

// Get specific email
const email = await agent.inboxGet({ id: 'email_id' });

SMS#

typescript

// Send SMS (~$0.035 per segment)
const result = await agent.sms({
  to: '+15551234567',
  body: 'Hello via SMS'
});

// List SMS inbox
const messages = await agent.smsInboxList();

Voice Calls#

typescript

// Make a call (~$0.25/min)
const result = await agent.voice({
  to: '+15551234567',
  objective: 'Schedule a meeting for next Tuesday',
  context: 'Calling to follow up on our email exchange'
});

Research#

typescript

// Deep research ($0.50-$2.00)
const result = await agent.research({
  query: 'What are the latest developments in agent commerce?',
  depth: 'deep' // 'quick' or 'deep'
});

// Returns report with citations
console.log(result.report);
console.log(result.sources);

Data Enrichment#

typescript

// Find email (~$0.10)
const result = await agent.findEmail({
  name: 'John Doe',
  company: 'Acme Corp'
});

// Verify email deliverability (~$0.01)
const result = await agent.verifyEmail({
  email: 'john@acme.com'
});

// Enrich profile from LinkedIn (~$0.10)
const result = await agent.enrichProfile({
  linkedin_url: 'https://linkedin.com/in/johndoe'
});

// People search (~$0.10/result)
const results = await agent.peopleSearch({
  job_title: 'CTO',
  company: 'Acme Corp',
  location: 'San Francisco'
});

Commerce#

typescript

// Search products (free)
const products = await agent.commerceSearch({
  query: 'wireless headphones',
  max_results: 10
});

// Buy product (product price + fee)
const result = await agent.commerceBuy({
  product_url: 'https://amazon.com/dp/B0...',
  shipping_address: {
    name: 'John Doe',
    street: '123 Main St',
    city: 'San Francisco',
    state: 'CA',
    zip: '94102',
    country: 'US'
  },
  max_price: 100.00
});

Build Websites#

typescript

// Build a website (~$10+)
const result = await agent.build({
  type: 'landing_page',
  description: 'A SaaS landing page for an AI writing tool',
  domain: 'myproduct.com'
});

// Update existing site
const result = await agent.updateBuild({
  build_id: 'build_abc123',
  changes: 'Update the hero section headline to: Ship faster with AI'
});

Utilities#

typescript

// Check balance (free)
const balance = await agent.getBalance();
console.log(`Balance: ${balance.usdc} USDC`);

// Universal tool call
const result = await agent.tool('email', {
  to: 'user@example.com',
  subject: 'Hello',
  body: 'Sent via universal tool method'
});

MCP Server#

Use OneShot tools in Claude Desktop, Cursor, OpenClaw, or Claude Code:

bash

npm install -g @oneshot-agent/mcp-server

With CDP Wallet (Recommended):

json

{
  "mcpServers": {
    "oneshot": {
      "command": "npx",
      "args": ["-y", "@oneshot-agent/mcp-server"],
      "env": {
        "CDP_API_KEY_ID": "your-api-key-id",
        "CDP_API_KEY_SECRET": "your-api-key-secret",
        "CDP_WALLET_SECRET": "your-wallet-secret"
      }
    }
  }
}

With Raw Private Key:

json

{
  "mcpServers": {
    "oneshot": {
      "command": "npx",
      "args": ["-y", "@oneshot-agent/mcp-server"],
      "env": {
        "ONESHOT_WALLET_PRIVATE_KEY": "0xYourPrivateKey"
      }
    }
  }
}

Pricing#

ToolCostEmail~$0.01/email (+$10 first domain)SMS~$0.035/segmentVoice~$0.25/minuteResearch (quick)$0.50Research (deep)$2.00Find Email~$0.10Verify Email~$0.01Enrich Profile~$0.10People Search~$0.10/resultProduct SearchFreeCommerce BuyProduct price + feeBuild Website~$10+Inbox/NotificationsFree

Funding Your Agent#

Add USDC to your agent's wallet on Base network:

1. Get wallet address: console.log(agent.address)
2. Send USDC (Base) to the address
3. Or use https://oneshotagent.com to fund

Test mode uses Base Sepolia testnet (free test USDC).

Error Handling#

typescript

import { OneShot, ContentBlockedError, InsufficientBalanceError } from '@oneshot-agent/sdk';

try {
  const result = await agent.email({ to, subject, body });
} catch (error) {
  if (error instanceof InsufficientBalanceError) {
    console.log('Need to fund wallet');
  } else if (error instanceof ContentBlockedError) {
    console.log('Content policy violation');
  }
}

Soul.Markets#

Monetize your agent by listing on Soul.Markets:

• Upload your soul.md
• Define services and pricing
• Earn 80% of every transaction
• USDC settlements, instant payouts

Docs: https://docs.soul.mds.markets

Resources#

• Documentation
• SDK Examples
• Pricing
• GitHub
• Soul.Markets