Install OneShot SDK - npm Package for AI Agent Actions

Install via npm/bun

bash npm install @oneshot-agent/sdk

bash bun add @oneshot-agent/sdk

Install via pip (Python)

If you’re building in Python, install the core SDK or the LangChain integration:

Core SDK
LangChain
Virtuals GAME

pip install oneshot-python

The core SDK gives you OneShotClient with the full x402 payment flow. Use this if you want direct HTTP access without a framework.

pip install langchain-oneshot

Wraps all 31 OneShot tools as LangChain BaseTool subclasses. Includes oneshot-python as a dependency.

pip install game-plugin-oneshot

GAME SDK plugin for Virtuals Protocol agents. Includes oneshot-python as a dependency.

All Python packages use eth-account for local EIP-712 signing and httpx for HTTP. Your private key never leaves your machine.

Prerequisites

Wallet

A Coinbase CDP wallet (recommended) or a raw private key.

Funds

Fund your wallet with USDC or ETH on Base. The SDK can auto-swap ETH→USDC via Uniswap V3 at payment time.

Node.js

Version 18+ required.

Authentication

The SDK supports two wallet options for signing x402 payments:

Coinbase CDP Wallet (Recommended)
Raw Private Key

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

npm install @coinbase/cdp-sdk

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

console.log("Agent address:", agent.address);

Get your CDP credentials at Coinbase Agentic Wallet.

Direct wallet control for agents managing their own keys:

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

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

console.log("Agent address:", agent.address);

The SDK operates on Base Mainnet with real USDC. Fund your agent wallet before making paid tool calls.

Environment Variables

CDP Wallet (Recommended)
Raw Private Key

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

AGENT_PRIVATE_KEY=0x...your_private_key

Never commit secrets to version control! Use environment variables or a secrets manager.

Verify Installation

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

// Either method works
const agent = await OneShot.create({ cdp: true });
// or: new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY })

console.log("Agent address:", agent.address);

Pay with ETH

Don’t have USDC? The SDK can top up USDC from ETH via Uniswap V3 whenever your balance runs low. Just set currency: 'ETH':

const agent = new OneShot({
  privateKey: process.env.AGENT_PRIVATE_KEY,
  currency: 'ETH',        // Swap ETH→USDC only when USDC runs low
  slippage: 0.01,          // 1% slippage tolerance (default)
  swapBufferMultiplier: 10, // buy 10 payments' worth per swap (default)
});

// Works exactly the same — SDK swaps ETH→USDC behind the scenes
await agent.email({ to: "[email protected]", subject: "Paid with ETH", body: "Hello" });

Before each payment the SDK checks the wallet’s USDC (counting payments it has signed but that have not settled yet) and skips the swap when it covers the charge. When a swap is needed it buys swapBufferMultiplier × the charge (default 10, range 1–1000) via Uniswap V3’s exactOutputSingle on Base, so one swap covers many calls and any excess ETH is refunded; when the wallet provider exposes getBalance and its ETH cannot cover the buffer, it swaps just the shortfall (a send-only custom provider always gets the buffered amount). Run one process per wallet in ETH mode (each process keeps its own in-flight ledger). ETH mode is Base mainnet only. Requires a wallet provider that supports sendTransaction (private key or custom provider — CDP wallets don’t support ETH mode yet).

Advanced Configuration

const agent = await OneShot.create({
  cdp: true,
  baseUrl: "https://win.oneshotagent.com", // Optional: override API endpoint
  rpcUrl: "https://rpc.example.com", // Optional: override RPC endpoint
});

Custom Wallet Provider

You can also bring your own WalletProvider implementation:

import { OneShot, type WalletProvider } from "@oneshot-agent/sdk";

const myProvider: WalletProvider = {
  address: "0x...",
  signTypedData: async (domain, types, value) => {
    // Your EIP-712 signing logic
    return signature;
  },
};

const agent = await OneShot.create({ walletProvider: myProvider });

OneShot follows the x402 philosophy: it is designed to be chain and wallet agnostic. The SDK handles the cryptographic signing required for payment authorizations automatically.

TypeScript Configuration

If using TypeScript, ensure your tsconfig.json includes:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "esModuleInterop": true,
    "resolveJsonModule": true
  }
}

Package Registry Links

Package	Registry	Language	Install
`@oneshot-agent/sdk`	npm	TypeScript	`npm install @oneshot-agent/sdk`
`@oneshot-agent/mcp-server`	npm	TypeScript	`npm install -g @oneshot-agent/mcp-server`
`oneshot-python`	PyPI	Python	`pip install oneshot-python`
`langchain-oneshot`	PyPI	Python	`pip install langchain-oneshot`
`game-plugin-oneshot`	PyPI	Python	`pip install game-plugin-oneshot`

Source code: github.com/oneshot-agent/sdk

Next Steps

Examples

TypeScript code examples for email, research, and more

LangChain

Python LangChain integration with 34 tools

​Install via npm/bun

​Install via pip (Python)

​Prerequisites

​Authentication

​Environment Variables

​Verify Installation

​Pay with ETH

​Advanced Configuration

​Custom Wallet Provider

​TypeScript Configuration

​Package Registry Links

​Next Steps

Examples

LangChain

Install via npm/bun

Install via pip (Python)

Prerequisites

Authentication

Environment Variables

Verify Installation

Pay with ETH

Advanced Configuration

Custom Wallet Provider

TypeScript Configuration

Package Registry Links

Next Steps