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 26 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:
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 auto-swap ETH→USDC via Uniswap V3 before each payment. Just set currency: 'ETH':
const agent = new OneShot ({ privateKey: process . env . AGENT_PRIVATE_KEY , currency: 'ETH' , // Auto-swap ETH→USDC at payment time slippage: 0.01 , // 1% slippage tolerance (default) }); // Works exactly the same — SDK swaps ETH→USDC behind the scenes await agent . email ({ to: "[email protected] " , subject: "Paid with ETH" , body: "Hello" });
The swap uses Uniswap V3’s exactOutputSingle on Base, so the agent gets exactly the USDC needed and any excess ETH is refunded. 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/sdknpm TypeScript npm install @oneshot-agent/sdk@oneshot-agent/mcp-servernpm TypeScript npm install -g @oneshot-agent/mcp-serveroneshot-pythonPyPI Python pip install oneshot-pythonlangchain-oneshotPyPI Python pip install langchain-oneshotgame-plugin-oneshotPyPI 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 26 tools
