OneShot SDK Overview

SDK

Call tools: agent.email(); goals: agent.compute(). SDK: signs payments, polls jobs, retries rate limits. Receipts carry memo and decisionContext. Quickstart.

Base Mainnet, real USDC: fund the wallet before paid calls.

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

ETH mode tops up USDC when low.

Paying with raw HTTP

402 returns PAYMENT-REQUIRED. Sign the USDC authorization; send base64 JSON in payment-signature, never Authorization. payment-signature wins over legacy x-payment.

Read authentication

The SDK signs x-agent-proof for private reads. Raw HTTP: 401 proof_required returns required_scope ("read"/"write").

Set agent to the X-Agent-ID wallet, scope to required_scope, issuedAt to integer Unix seconds, nonce to 32 random bytes, 0x-prefixed hex, never reused.

Sign EIP-712 data with that wallet:

{
  "domain": { "name": "OneShot Agent Auth", "version": "1" },
  "primaryType": "AgentReadAuth",
  "types": {
    "AgentReadAuth": [
      { "name": "agent", "type": "address" },
      { "name": "scope", "type": "string" },
      { "name": "issuedAt", "type": "uint256" },
      { "name": "nonce", "type": "bytes32" }
    ]
  },
  "message": { "agent": "0xYourWallet", "scope": "read", "issuedAt": 1760000000, "nonce": "0x…32 bytes…" }
}

Base64-encode JSON { agent, scope, issuedAt, nonce, signature } as x-agent-proof, with X-Agent-ID.

import { Wallet, randomBytes, hexlify } from 'ethers';

const wallet = new Wallet(PRIVATE_KEY);
const scope = 'read'; // use the 401's required_scope ('write' for write endpoints)
const message = { agent: wallet.address, scope, issuedAt: Math.floor(Date.now() / 1000), nonce: hexlify(randomBytes(32)) };
const signature = await wallet.signTypedData(
  { name: 'OneShot Agent Auth', version: '1' },
  {
    AgentReadAuth: [
      { name: 'agent', type: 'address' },
      { name: 'scope', type: 'string' },
      { name: 'issuedAt', type: 'uint256' },
      { name: 'nonce', type: 'bytes32' },
    ],
  },
  message,
);
const proof = Buffer.from(JSON.stringify({ ...message, signature })).toString('base64');
const headers = { 'X-Agent-ID': wallet.address, 'x-agent-proof': proof };

Python: eth_account.messages.encode_typed_data. Proofs last 5 minutes, single-use. Tokens are exempt. 401 invalid_proof: expired, already_used, wrong_scope, invalid; SDKs retry the first two once. 401 proof_required: TypeScript SDKs retry once, correcting the clock from server_time or re-signing replayed reads. Raw callers derive issuedAt from server_time.

Supported tools

Quote-based tools price each call; maxCost rejects higher quotes before signing. Pricing. agent.tool(name, options) calls any tool.

Group	Methods
Messaging	`agent.email()`, `agent.voice()` (quote), `agent.sms()` (quote), `agent.inboxList()`, `agent.inboxGet(id)`, `agent.smsInboxList()`, `agent.smsInboxGet(id)`
Research and enrichment	`agent.research()`, `agent.personFind()`, `agent.personDossier()` (2-5 min), `agent.personSocialAccounts()`, `agent.personArticles()`, `agent.personPosts()`, `agent.personInterests()`, `agent.personFollowers()`, `agent.personProfile()`, `agent.personEmail()`, `agent.personEmailStatus()`, `agent.companyFind()`, `agent.companyProfile()`, `agent.businessFind()`, `agent.businessResolve()`, `agent.recordSolicitationsFind()`
Web and browser	`agent.webSearch()`, `agent.webRead()`, `agent.browser()` (quote), `agent.createBrowserProfile()`, `agent.listBrowserProfiles()`, `agent.deleteBrowserProfile(id)`
Build	`agent.build()` (quote), `agent.updateBuild()` (quote)
Commerce	`agent.productFind()`, `agent.commerceBuy()` (quote)
Account	`agent.notifications()`, `agent.markNotificationRead(id)`, `agent.getBalance(tokenAddress)`

Person profile: name+company, email, phone or LinkedIn/X/GitHub URL. Login/2FA: agent.startBrowserProfileSetup() returns a single-use setup_url that expires in 10 minutes; agent.createBrowserProfileSetupLink() renews it. Done sets completed_at; Cancel ends setup without it.

Compute

agent.compute(options) (x402 quote) creates a goal. Free: getComputeGoal, getComputeTasks, getComputeOutputs, getComputeOutput(goalId, key), getComputeBudget, cancelComputeGoal, respondToComputeTask, pauseComputeGoal, resumeComputeGoal. fundComputeGoal(goalId, amount) is an x402 quote. Pause, resume and fund need a recurring goal (schedule). Unspent budget returns as credits when goals end. Python: same methods in snake case; access tokens need oneshot-python ≥ 0.26.0. Compute.

Server-side cost cap (`X-Max-Cost-USDC`)

Rejects higher quotes before payment: 400 exceeds_caller_budget. TypeScript maxCost, Python max_cost.

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}'

{
  "error": "exceeds_caller_budget",
  "message": "Quote $2.500000 exceeds X-Max-Cost-USDC cap $2.00",
  "quote": { "total": "2.500000", "cap": "2.00" }
}

Spend budgets

Caps each UTC day and call across every process on one wallet. Contract.

const agent = await OneShot.create({
  cdp: true,
  budgets: {
    daily: 50,           // max USDC per UTC day
    perTransaction: 5,   // max USDC for any single call
    alertAt: 0.8,        // notify at 80% of daily
    pauseAt: 1.0,        // stop paying at 100%
  },
  alerts: { email: "[email protected]" },
});

client = OneShotClient(
    "0x...",
    budgets={"daily": 50, "per_transaction": 5, "alert_at": 0.8, "pause_at": 1.0},
    alert_email="[email protected]",
)

alertAt sends budget_warning (plus email if set); at pauseAt, paid calls fail until UTC midnight:

import { BudgetExceededError } from "@oneshot-agent/sdk";

try {
  await agent.research({ topic: "..." });
} catch (err) {
  if (err instanceof BudgetExceededError) {
    console.log(`${err.reason} budget hit — $${err.spent} spent, resumes ${err.resetsAt}`);
  }
}

const b = await agent.budgets();
// { daily_usdc: 50, spent_today_usdc: "41.20", pct_used: 0.824, resets_at: "…" }

from oneshot import BudgetExceededError

try:
    client.research(topic="...")
except BudgetExceededError as e:
    print(f"{e.reason} budget hit — ${e.spent} spent, resumes {e.resets_at}")

client.get_budgets()

Omit budgets: unchanged. No budget: unlimited. Unconfirmed sync: BudgetSyncError, no paid call. Invalid config: ValidationError. MCP: ONESHOT_BUDGET_*; oneshot_budget_status is read-only.

SDKs and packages

Package
`@oneshot-agent/sdk`
`@oneshot-agent/mcp-server`
`oneshot-python`
`langchain-oneshot`
`game-plugin-oneshot`

Get Started

Organizations

SDK

OneShot SDK Overview

SDK

Paying with raw HTTP

Read authentication

Supported tools

Compute

Server-side cost cap (`X-Max-Cost-USDC`)

Spend budgets

SDKs and packages

Next steps

Installation

Examples

LangChain (Python)

MCP Server

Virtuals GAME SDK

Agent Skills

Pricing

Optional phone lookup

​SDK

​Paying with raw HTTP

​Read authentication

​Supported tools

​Compute

​Server-side cost cap (X-Max-Cost-USDC)

​Spend budgets

​SDKs and packages

​Next steps

Installation

Examples

LangChain (Python)

MCP Server

Virtuals GAME SDK

Agent Skills

Pricing

​Optional phone lookup

SDK

Paying with raw HTTP

Read authentication

Supported tools

Compute

Server-side cost cap (`X-Max-Cost-USDC`)

Spend budgets

SDKs and packages

Next steps

Optional phone lookup