game-plugin-oneshot

A GAME SDK plugin that gives Virtuals Protocol agents OneShot's 48 real-world tools plus one per lookup tool: email, SMS, calls, research, enrichment, commerce, website builds. Paid tools charge USDC from your wallet on Base Mainnet, so fund it first.

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

Hosted GAME agents that should not hold a wallet key use a delegated token instead:

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 set budgets from a wallet session. Calls spend prepaid credits within 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

The plugin exposes 48 OneShot tools plus one oneshot_<name> function per lookup tool. The lookup tools are read from the generated manifest in oneshot-python (oneshot.lookup_tools()), so a new lookup tool appears here without a plugin change. Core tools:

Paid tools are priced in USDC via x402. Current rates are on the Pricing page.

Payment

Paid tools deduct USDC from your wallet on Base Mainnet, settled with the x402 payment protocol. Fund the wallet with USDC first.

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. The underlying oneshot-python client handles this automatically. It requires oneshot-python >= 0.18.0, which is already the dependency floor.

Complex Arguments

Structured input goes in as strings, because GAME Argument supports only scalar types. commerce_buy, build, and update_build take JSON strings, and list fields on people_search take 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

LinkedIn connection recovery

If the active account list is empty or an account is connection_deleted or revoked, ask the human to use oneshot_linkedin_connect and authorize fresh grants. An existing account with reconnect_required must be reconnected through the owning application. Reconnect and revoke are deliberately not agent tools. Do not create a new connection automatically after authentication failures or timeouts.

Requirements

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

Links

• Documentation
• langchain-oneshot on PyPI: the LangChain integration
• oneshot-python on PyPI: core HTTP client
• TypeScript SDK
• MCP Server
• GitHub

License

MIT

Optional phone lookup

person_find, person_profile, and person_dossier accept include_phone, off by default. It adds $0.10 × the requested search limit (default 100 → $10), or $0.10 for profile/dossier, for up to that many people with no promised hit. Existing source numbers and published business or record numbers remain available without opting in. Fallbacks and callbacks cost nothing extra; a completed no-match is charged and a failed job is refunded. GAME accepts the string "true" or "false". The full quote is checked before payment.