Install OneShot SDK: npm Package for AI Agent Actions

TypeScript requires Node.js 18+. Fund CDP wallets with USDC on Base. ETH requires a supported wallet configured with currency: 'ETH'; see Pay with ETH.

Install via npm/bun

bash npm install @oneshot-agent/sdk

bash bun add @oneshot-agent/sdk

Install via pip (Python)

Core SDK
LangChain
Virtuals GAME

pip install oneshot-python

OneShotClient: HTTP calls and x402 payments.

pip install langchain-oneshot

LangChain BaseTool subclasses; includes oneshot-python.

pip install game-plugin-oneshot

Virtuals GAME plugin; includes oneshot-python.

Python signs locally; your private key stays on your machine. For hosted code, use an access token: OneShotClient.create(access_token=...), OneShotToolkit.from_access_token(...), OneShotPlugin(access_token=...). These are credits-only sessions and need oneshot-python ≥ 0.26.0.

Authentication

Either wallet option signs x402 payments. CDP keeps the key out of your config.

Coinbase CDP Wallet (Recommended)
Raw Private Key

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 CDP credentials at Coinbase Agentic Wallet.

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

Set currency: 'ETH' to top up USDC from ETH when the balance runs low:

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

USDC checks include signed, unsettled payments. If USDC covers the charge, no swap occurs. Otherwise the SDK buys swapBufferMultiplier × the charge (default 10, range 1–1000). Excess ETH is refunded. If ETH cannot cover the buffer, it swaps only the shortfall; custom wallet providers need getBalance for this. Run one process per wallet in ETH mode. ETH mode is Base mainnet only and needs a private key or a custom provider with sendTransaction. CDP wallets don’t support ETH mode: cdp with currency: 'ETH' throws a ValidationError before any wallet is created, so fund CDP wallets with USDC.

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

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

Your tsconfig.json should include:

{
  "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

Get Started

Organizations

SDK

Install OneShot SDK: npm Package for AI Agent Actions

Install via npm/bun

Install via pip (Python)

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)

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

Authentication

Environment variables

Verify installation

Pay with ETH

Advanced configuration

Custom wallet provider

TypeScript configuration

Package registry links

Next steps