Overview
game-plugin-oneshot is a Python package that exposes 7 OneShot tools as a Virtuals Protocol 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.
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.
Installation
pip install game-plugin-oneshot
Requirements
- Python 3.10+
- A wallet private key (for x402 payment signing)
- USDC on Base (Sepolia for testing, Mainnet for production)
- A Virtuals GAME API key
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
import os
from game_sdk.game.agent import Agent
from game_plugin_oneshot import OneShotPlugin
# Create the plugin (test mode = Base Sepolia, free)
plugin = OneShotPlugin(
private_key=os.environ["WALLET_PRIVATE_KEY"],
test_mode=True,
)
# 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()
Test mode is on by default. Get free test USDC from the Circle Faucet (select Base Sepolia). | Tool | Description | Cost (USDC) |
|---|
oneshot_email | Send emails to real recipients | ~$0.01 |
oneshot_sms | Send SMS text messages | ~$0.035 |
oneshot_voice | Make phone calls with AI voice | ~$0.25/min |
oneshot_research | Deep research reports with sources | 0.50–2.00 |
oneshot_commerce_search | Search for products | Free |
oneshot_commerce_buy | Purchase products online | Product price + fee |
oneshot_build | Generate and deploy websites | ~$10+ |
The plugin exposes 7 of the 26 OneShot tools — the ones most useful for autonomous GAME agents. Inbox, notifications, and balance tools are omitted since GAME agents don’t typically need them.
How Payments Work
All paid tools use the x402 protocol. The flow is fully automatic:
- Your GAME agent invokes a tool (e.g.
oneshot_email)
- The plugin POSTs to the OneShot API
- The API returns 402 Payment Required with a USDC quote
- The plugin signs a
TransferWithAuthorization (EIP-3009) locally using your private key
- The plugin re-POSTs with the signed payment in the
x-payment header
- The API processes the job and returns the result
Your private key never leaves your machine. All signing happens locally via eth-account.
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:
# 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",
})
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.
Configuration
# Test mode (default) — Base Sepolia, no real money
plugin = OneShotPlugin(private_key="0x...", test_mode=True)
# Production — Base Mainnet, real USDC
plugin = OneShotPlugin(private_key="0x...", test_mode=False)
# 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 |
test_mode | True | Use Base Sepolia testnet (free) |
base_url | None | Override API URL |
Environment Variables
# 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
