game-true402

  Stable · production-ready — semver-stable public API (v1.0).

true402 stalls as Virtuals Protocol GAME functions. Give a G.A.M.E agent a pay-per-call, on-chain rug/honeypot gate for Base tokens, plus SEO/search data (backlinks, keyword volume, ranked keywords, keyword ideas), over x402 — USDC on Base, no account, no API key. The wallet is the identity, and most of the on-chain safety stalls have a free daily trial, so those functions work out of the box with no wallet configured; check_deployer and the SEO/search stalls are paid from the first call.

§01 · Install

pip install game-true402

This pulls the canonical Python GAME SDK (game_sdk) plus the x402 payer (requests, eth-account). You also need a GAME API key from console.game.virtuals.io.

§02 · Use

import os
from game_sdk.game.worker import Worker
from game_true402 import true402_functions

# Reads PAYER_PRIVATE_KEY from the env (a Base wallet holding a little USDC).
# Omit the key to rely on the free daily trial for most safety stalls (not check_deployer).
worker = Worker(
    api_key=os.environ["GAME_API_KEY"],
    description="A cautious on-chain trader that vets tokens before buying.",
    instruction="Always run check_token_report before acting on a token.",
    get_state_fn=lambda function_result, current_state: (current_state or {}),
    action_space=true402_functions(),
)

worker.run("Is token 0x… safe to buy on Base?")

To compose the functions into a full multi-worker agent instead, register the same list on a WorkerConfig.action_space and pass the worker to an Agent(workers=[…]), then call agent.compile() and agent.run().

§03 · The functions

The agent gets ten functions. Each pays its stall over x402 and returns the standard GAME (FunctionResultStatus, message, info) tuple; the info dict is the full stall JSON, fed into your get_state_fn on the next step.

On-chain safety (free daily trial on most — check_deployer is paid from the first call):

• check_token_report — primary pre-trade gate. Composite avoid / caution / ok verdict from a real on-chain buy/sell honeypot simulation (proves sellability, not just a static scan) plus liquidity, ownership/mint and recent rug activity. Call before buying. ~$0.01.
• check_token_safety — structural safety score 0–100 and flags (honeypot sim, liquidity, mint/ownership). Lighter than the report. ~$0.005.
• check_address_safety — screen any address before you send to / approve / call it: EOA-vs-contract, ETH+USDC balance, activity, ownership, upgradeable-proxy (EIP-1967) detection. ~$0.005.
• check_deployer — deployer wallet reputation (age, contracts shipped, fresh-throwaway flag) to catch serial ruggers a structural scan can't see. No free trial — paid from the first call. ~$0.008.
• check_liquidity_history — what has already happened to the token's liquidity: every removal true402 observed, with amount, block and transaction hash, plus the other tokens drained in the same transaction. A live simulation cannot see this — a pool drained last month looks healthy today if it was re-seeded. ~$0.005.
• preflight_transaction — the last check before signing. Send the unsigned transaction and get a simulation (does it revert?), the decoded intent (unlimited approval?) and the counterparty's removal history. Takes no private key and no signature, so it cannot broadcast or front-run. ~$0.008.

SEO/search data (no free trial — paid from the first call):

• check_backlinks — a domain's backlink profile: referring domains and pages, the dofollow split that actually carries authority, an authority rank and a spam score. The one SEO signal an agent can't compute from a page fetch. ~$0.10.
• get_keyword_volume — search volume, CPC and competition for up to 200 keywords in one call. Priced per call, not per keyword: batch every keyword you need into one keywords list, since calling it once per keyword buys the same data for up to 200x the money. ~$0.15.
• get_ranked_keywords — which keywords a domain already ranks for in organic search, with position and the exact URL that ranks. Works on any domain, so it's competitor research as much as self-audit. ~$0.05.
• get_keyword_ideas — related and long-tail keyword ideas for a seed term, each with search volume and search intent — measured candidates, not ones a language model invented. ~$0.05.

§04 · Configuration

true402_functions() reads the environment, or you can pass an explicit PayOpts:

from game_true402 import true402_functions, PayOpts

action_space = true402_functions(PayOpts(
    payer_private_key="0x…",   # a Base wallet with a little USDC (gas is sponsored; USDC only)
    max_amount_usd=0.25,        # hard per-call ceiling — refuses to sign a 402 demanding more
))

• PAYER_PRIVATE_KEY — Base wallet key that signs x402 payments (needs USDC, not ETH). Unset means free-trial only.
• TRUE402_BASE_URL — defaults to https://true402.dev/api; override to point at a self-hosted instance.
• BASE_RPC_URL — defaults to https://mainnet.base.org; used only for a balance pre-check.

§05 · Safety

The payer refuses to sign anything that isn't USDC-on-Base within max_amount_usd (default $0.25, above the server's own $0.20 per-request ceiling so a legitimately-priced stall is never blocked), so a rogue or compromised endpoint can't make your agent authorize an unexpected asset, network, or amount. The private key signs locally and never leaves the process. This is the same verified x402 payer used by the CrewAI and LangChain integrations — signatures recover to the payer address.

§06 · FAQ

1. Do I need a true402 account or API key? No. Payment is the auth: the agent POSTs, gets an HTTP 402 with payment terms, signs an EIP-3009 USDC authorization, and retries. The wallet is the identity.

2. Does it work without a funded wallet? Yes, up to a point, for most of the on-chain safety functions (check_token_report, check_token_safety, check_address_safety, check_liquidity_history, preflight_transaction). They have a free daily trial, so they return real results with no PAYER_PRIVATE_KEY set — until the trial is exhausted, then they require payment. check_deployer has no free trial and needs a funded wallet from the first call, same as the SEO/search functions (check_backlinks, get_keyword_volume, get_ranked_keywords, get_keyword_ideas).

3. Which function should the agent call before trading? check_token_report. It is the composite avoid/caution/ok gate and folds in the honeypot simulation, liquidity, ownership and deployer signal.

4. Why Python and not the Node GAME SDK? GAME's Python SDK is the canonical reference, and its executables run synchronously — a clean match for the synchronous x402 payer, with no async wrapping. A TypeScript build can wrap the same stalls via the @true402.dev/langchain payer.

5. What does the executable return to the planner? A (FunctionResultStatus.DONE | .FAILED, message, info) tuple. The message is an agent-readable summary; the info dict is the full stall JSON for your get_state_fn.

§07 · Links

• Live check in your browser: true402.dev/check
• API reference: true402.dev/docs/api · OpenAPI: true402.dev/openapi.json
• Also available: LangChain · CrewAI · MCP server

Checking tokens by hand? Send any Base token address to @True402bot on Telegram — same on-chain checks, free, no wallet.

§08 · License

MIT

Also available for

MCP (Claude Code / Desktop, Cursor, Hermes) · Hermes Agent · OpenClaw · ElizaOS · LangChain · CrewAI · Vercel AI SDK · Coinbase AgentKit · Virtuals GAME · CLI — same on-chain checks, one install command each: true402.dev/integrations

Paying, exactly

The rules below are the service's, not this package's — they bite whatever client you use, and they are the ones that surprise people writing their own payer.

• Pay the EXACT amount quoted in the 402. Underpaying is rejected. Overpaying is refused with 403 and never credited — settlement submits the signed value and there is no refund path, so a surplus would simply be swept. Equality is also what binds an authorization to the resource it was quoted for.
• One authorization buys exactly one response. A replay is refused, not double-charged.
• You are charged on success only. Settlement is submitted only when the endpoint returns 2xx; if it errors or times out, your signed authorization is never submitted, so there is nothing to refund.
• Some endpoints serve a few free calls per day per client IP, with no wallet. The per-operation description in the OpenAPI spec says which.

Full rules: true402.dev/terms · what is logged and kept: true402.dev/privacy