> ## 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.

# Virtuals GAME SDK (Python)

> Give Virtuals Protocol agents real-world tools via the GAME SDK plugin

## Overview

`game-plugin-oneshot` is a Python package that exposes 31 OneShot tools as a [Virtuals Protocol](https://virtuals.io) GAME worker. It handles x402 payment signing automatically so your GAME agents can send emails, make phone calls, run research, buy products, and build websites.

<Info>
  This plugin builds on `langchain-oneshot` under the hood — it reuses the same HTTP + x402 payment flow, so all payments are signed locally via `eth-account`.
</Info>

## Installation

```bash theme={null}
pip install game-plugin-oneshot
```

### Requirements

* Python 3.10+
* A wallet private key (for x402 payment signing)
* USDC on Base Mainnet
* A [Virtuals GAME API key](https://app.virtuals.io)

### Dependencies

| Package             | Purpose                                            |
| ------------------- | -------------------------------------------------- |
| `game-sdk`          | Virtuals GAME Agent / Worker interfaces            |
| `langchain-oneshot` | HTTP client + x402 payment signing                 |
| `eth-account`       | EIP-712 typed data signing (via langchain-oneshot) |

## Quick Start

```python theme={null}
import os
from game_sdk.game.agent import Agent
from game_plugin_oneshot import OneShotPlugin

plugin = OneShotPlugin(
    private_key=os.environ["WALLET_PRIVATE_KEY"],
)

# Create a GAME agent
agent = Agent(
    api_key=os.environ["GAME_API_KEY"],
    name="my-agent",
    agent_description="An agent that can interact with the real world",
)

# Add OneShot tools as a worker
agent.add_worker(plugin.get_worker())
agent.run()
```

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

## Available Tools

<Info>See [Pricing](/pricing) for current tool costs.</Info>

| Tool                             | Description                                          |
| -------------------------------- | ---------------------------------------------------- |
| `oneshot_email`                  | Send emails to real recipients                       |
| `oneshot_sms`                    | Send SMS text messages                               |
| `oneshot_voice`                  | Make phone calls with AI voice                       |
| `oneshot_sms_inbox_list`         | List inbound SMS messages                            |
| `oneshot_sms_inbox_get`          | Get a specific inbound SMS                           |
| `oneshot_inbox_list`             | List inbound emails                                  |
| `oneshot_inbox_get`              | Get a specific inbound email                         |
| `oneshot_notifications`          | List agent notifications                             |
| `oneshot_mark_notification_read` | Mark a notification as read                          |
| `oneshot_research`               | Deep research reports with sources                   |
| `oneshot_web_search`             | Search the web for results                           |
| `oneshot_web_read`               | Read a URL as markdown + screenshot                  |
| `oneshot_people_search`          | Find people by title, company, skills                |
| `oneshot_enrich_profile`         | Enrich a person from LinkedIn/email/name             |
| `oneshot_find_email`             | Find a person's work email at a company              |
| `oneshot_verify_email`           | Check email deliverability                           |
| `oneshot_deep_research_person`   | Full person dossier — career, interests, connections |
| `oneshot_social_profiles`        | Discover a person's social accounts                  |
| `oneshot_article_search`         | Find articles/publications about a person            |
| `oneshot_person_newsfeed`        | Recent social posts with engagement                  |
| `oneshot_person_interests`       | Analyze a person's interests                         |
| `oneshot_person_interactions`    | Map followers, following, and replies                |
| `oneshot_commerce_search`        | Search for products                                  |
| `oneshot_commerce_buy`           | Purchase products online                             |
| `oneshot_browser`                | Autonomous browser — navigate, click, extract        |
| `oneshot_browser_create_profile` | Create persistent browser profile                    |
| `oneshot_browser_list_profiles`  | List all browser profiles                            |
| `oneshot_browser_delete_profile` | Delete a browser profile                             |
| `oneshot_build`                  | Generate and deploy websites                         |
| `oneshot_update_build`           | Update an existing website                           |
| `oneshot_get_balance`            | Get USDC wallet balance                              |

<Info>
  The plugin exposes all 31 OneShot tools — the same set as the MCP server and `langchain-oneshot`.
</Info>

## How Payments Work

All paid tools use the [x402 protocol](https://x402.org). The flow is fully automatic:

1. Your GAME agent invokes a tool (e.g. `oneshot_email`)
2. The plugin POSTs to the OneShot API
3. The API returns **402 Payment Required** with a USDC quote
4. The plugin signs a `TransferWithAuthorization` (EIP-3009) locally using your private key
5. The plugin re-POSTs with the signed payment in the `x-payment` header
6. The API processes the job and returns the result

<Warning>
  Your private key never leaves your machine. All signing happens locally via `eth-account`.
</Warning>

## Complex Arguments

GAME `Argument` only supports scalar types (string, int, float, bool). For tools that need structured input like `commerce_buy` and `build`, pass JSON strings:

```python theme={null}
# The GAME agent will generate these automatically,
# but for manual testing:
import json

shipping = json.dumps({
    "first_name": "John",
    "last_name": "Doe",
    "street": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "zip_code": "78701",
    "phone": "+15551234567",
})

product = json.dumps({
    "name": "Acme SaaS",
    "description": "Project management for teams",
})
```

<Tip>
  You don't need to handle this manually — the GAME agent's LLM will generate JSON strings for structured arguments automatically. This section is for debugging and manual testing.
</Tip>

## Configuration

```python theme={null}
plugin = OneShotPlugin(private_key="0x...")

# Custom API URL
plugin = OneShotPlugin(private_key="0x...", base_url="https://custom-api.example.com")
```

| Parameter     | Default    | Description                      |
| ------------- | ---------- | -------------------------------- |
| `private_key` | *required* | Hex-encoded Ethereum private key |
| `base_url`    | `None`     | Override API URL                 |

## Environment Variables

```bash theme={null}
# Required
WALLET_PRIVATE_KEY=0x...    # Ethereum private key for x402 payments
GAME_API_KEY=...            # Virtuals GAME API key

# Optional
ONESHOT_BASE_URL=...        # Override API endpoint
```

## Links

<CardGroup cols={2}>
  <Card title="PyPI Package" icon="python" href="https://pypi.org/project/game-plugin-oneshot/">
    View on PyPI
  </Card>

  <Card title="Virtuals Protocol" icon="gamepad" href="https://virtuals.io">
    Virtuals Protocol platform
  </Card>

  <Card title="TypeScript SDK" icon="npm" href="/sdk/overview">
    TypeScript SDK docs
  </Card>

  <Card title="LangChain SDK" icon="python" href="/sdk/langchain">
    LangChain integration
  </Card>
</CardGroup>