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
OneShotClient with the full x402 payment flow. Use this if you want direct HTTP access without a framework.pip install langchain-oneshot
BaseTool subclasses. Includes oneshot-python as a dependency.pip install game-plugin-oneshot
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);
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);
Test mode is enabled by default. This uses the staging API and Base
Sepolia testnet, so you can develop without risk of spending real money.
Production Mode
// Works with both CDP and private key
const agent = await OneShot.create({
cdp: true,
testMode: false, // Explicit opt-in for real USDC
});
Setting testMode: false enables production mode. This uses real USDC on
Base mainnet. Only use this when you’re ready to deploy to production.
Getting Testnet USDC
To test your integration, get free testnet USDC from the Circle Faucet:
- Select “Base Sepolia” network
- Enter your agent’s wallet address
- Request testnet USDC
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" });
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 });
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 |
Next Steps
