> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneshotagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Install OneShot SDK - npm Package for AI Agent Actions

> Install the OneShot SDK via npm or bun, configure your wallet, and start executing AI agent commercial transactions in minutes.

## Install via npm/bun

<Tabs>
  <Tab title="npm">`bash npm install @oneshot-agent/sdk `</Tab>
  <Tab title="bun">`bash bun add @oneshot-agent/sdk `</Tab>
</Tabs>

## Install via pip (Python)

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

<Tabs>
  <Tab title="Core SDK">
    ```bash theme={null}
    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.
  </Tab>

  <Tab title="LangChain">
    ```bash theme={null}
    pip install langchain-oneshot
    ```

    Wraps all 31 OneShot tools as LangChain `BaseTool` subclasses. Includes `oneshot-python` as a dependency.
  </Tab>

  <Tab title="Virtuals GAME">
    ```bash theme={null}
    pip install game-plugin-oneshot
    ```

    GAME SDK plugin for Virtuals Protocol agents. Includes `oneshot-python` as a dependency.
  </Tab>
</Tabs>

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

## Prerequisites

<Steps>
  <Step title="Wallet">A Coinbase CDP wallet (recommended) or a raw private key.</Step>

  <Step title="Funds">
    Fund your wallet with USDC or ETH on Base. The SDK can auto-swap ETH→USDC via Uniswap V3 at payment time.
  </Step>

  <Step title="Node.js">Version 18+ required.</Step>
</Steps>

## Authentication

The SDK supports two wallet options for signing x402 payments:

<Tabs>
  <Tab title="Coinbase CDP Wallet (Recommended)">
    Server-side wallet managed by Coinbase — no private keys in your config. Signing happens in Coinbase's secure enclave (TEE).

    ```bash theme={null}
    npm install @coinbase/cdp-sdk
    ```

    ```typescript theme={null}
    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](https://docs.cdp.coinbase.com/agentic-wallet/welcome).
  </Tab>

  <Tab title="Raw Private Key">
    Direct wallet control for agents managing their own keys:

    ```typescript theme={null}
    import { OneShot } from "@oneshot-agent/sdk";

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

    console.log("Agent address:", agent.address);
    ```
  </Tab>
</Tabs>

<Info>
  The SDK operates on **Base Mainnet** with real USDC. Fund your agent wallet before making paid tool calls.
</Info>

## Environment Variables

<Tabs>
  <Tab title="CDP Wallet (Recommended)">
    ```bash theme={null}
    CDP_API_KEY_ID=your-api-key-id
    CDP_API_KEY_SECRET=your-api-key-secret
    CDP_WALLET_SECRET=your-wallet-secret
    ```
  </Tab>

  <Tab title="Raw Private Key">
    ```bash theme={null}
    AGENT_PRIVATE_KEY=0x...your_private_key
    ```
  </Tab>
</Tabs>

<Warning>
  **Never commit secrets to version control!** Use environment
  variables or a secrets manager.
</Warning>

## Verify Installation

```typescript theme={null}
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'`:

```typescript theme={null}
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: "user@example.com", 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

```typescript theme={null}
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:

```typescript theme={null}
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:

```json theme={null}
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "esModuleInterop": true,
    "resolveJsonModule": true
  }
}
```

## Package Registry Links

| Package                                                                                | Registry | Language   | Install                                    |
| -------------------------------------------------------------------------------------- | -------- | ---------- | ------------------------------------------ |
| [`@oneshot-agent/sdk`](https://www.npmjs.com/package/@oneshot-agent/sdk)               | npm      | TypeScript | `npm install @oneshot-agent/sdk`           |
| [`@oneshot-agent/mcp-server`](https://www.npmjs.com/package/@oneshot-agent/mcp-server) | npm      | TypeScript | `npm install -g @oneshot-agent/mcp-server` |
| [`oneshot-python`](https://pypi.org/project/oneshot-python/)                           | PyPI     | Python     | `pip install oneshot-python`               |
| [`langchain-oneshot`](https://pypi.org/project/langchain-oneshot/)                     | PyPI     | Python     | `pip install langchain-oneshot`            |
| [`game-plugin-oneshot`](https://pypi.org/project/game-plugin-oneshot/)                 | PyPI     | Python     | `pip install game-plugin-oneshot`          |

Source code: [github.com/oneshot-agent/sdk](https://github.com/oneshot-agent/sdk)

## Next Steps

<CardGroup cols={2}>
  <Card title="Examples" icon="code" href="/sdk/examples">
    TypeScript code examples for email, research, and more
  </Card>

  <Card title="LangChain" icon="python" href="/sdk/langchain">
    Python LangChain integration with 31 tools
  </Card>
</CardGroup>