game-plugin-oneshot

GAME SDK plugin that gives Virtuals Protocol agents access to OneShot real-world tools.

Install

pip install game-plugin-oneshot

Quick Start

import os
from game_sdk.game.agent import Agent
from game_plugin_oneshot import OneShotPlugin

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

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

agent.add_worker(plugin.get_worker())
agent.run()

Access-token sessions

Use a delegated token for hosted GAME agents that should not hold a wallet key:

import os
from game_plugin_oneshot import OneShotPlugin

plugin = OneShotPlugin(access_token=os.environ["ONESHOT_ACCESS_TOKEN"])
# Inside an async application:
# plugin = await OneShotPlugin.acreate(access_token=os.environ["ONESHOT_ACCESS_TOKEN"])

Create the token and configure budgets from a wallet session. Calls spend prepaid credits and respect the stored caps. Tokens cannot manage tokens, raise budgets, or sign USDC payments. Refill credits from a wallet session with OneShotClient.top_up_credits(amount). See the hosted setup guide.

Tools

All 35 OneShot tools (same set as the MCP server and langchain-oneshot):

Paid tools are priced in USDC via x402. See Pricing for current rates.

Payment

All paid tools use the x402 payment protocol to deduct USDC from your wallet on Base Mainnet. Fund your wallet with USDC before using paid tools.

Read tools (inbox, SMS inbox, notifications, balance) send a signed EIP-712 read proof (x-agent-proof) so the API can verify you control the X-Agent-ID wallet before returning private data. Handled automatically by the underlying oneshot-python client — requires oneshot-python >= 0.18.0 (already the dependency floor).

Complex Arguments

GAME Argument only supports scalar types. For tools that need structured input (commerce_buy, build, update_build), pass JSON strings; list fields on people_search accept comma-separated values:

# The 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",
})

Configuration

Requirements

• Python >= 3.10
• game-sdk >= 0.1.5
• oneshot-python >= 0.18.0

Links

• Documentation
• langchain-oneshot on PyPI — Full 34-tool LangChain integration
• oneshot-python on PyPI — Core HTTP client
• TypeScript SDK
• MCP Server
• GitHub

License

MIT

LinkedIn connection recovery

If the active account list is empty or an account is deleted_upstream or revoked, ask the human to use oneshot_linkedin_connect and authorize fresh grants. An existing account with reconnect_required needs reconnect through the owning application. Reconnect and revoke are intentionally not agent tools. Do not automatically create a new connection in response to authentication failures or timeouts.