game-true402 0.1.0__tar.gz

game_true402-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.pyc

game_true402-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: game-true402
+Version: 0.1.0
+Summary: true402 safety stalls as Virtuals Protocol GAME functions — pay-per-call on-chain rug/honeypot & address safety for Base AI agents over x402 (USDC, no account, no API key).
+Project-URL: Homepage, https://true402.dev
+Project-URL: Source, https://github.com/true402/game-true402
+Project-URL: OpenAPI, https://true402.dev/openapi.json
+Author-email: true402 <contact@true402.dev>
+License: MIT
+Keywords: agent-tools,ai-agent,base,crypto,defi,game-by-virtuals,game-sdk,honeypot,rug-check,token-safety,virtuals,web3,x402
+Requires-Python: >=3.10
+Requires-Dist: eth-account>=0.11
+Requires-Dist: game-sdk>=0.1
+Requires-Dist: requests>=2.28
+Description-Content-Type: text/markdown
+
+# game-true402
+
+<!-- meta description: Give a Virtuals Protocol GAME agent an on-chain rug, honeypot and address-safety gate — pay per call over x402, USDC on Base, no account and no API key. -->
+
+<p><strong>true402 safety stalls as <a href="https://docs.game.virtuals.io/">Virtuals Protocol GAME</a> functions.</strong> Give a G.A.M.E agent a pay-per-call, on-chain rug/honeypot gate for Base tokens over <a href="https://x402.org">x402</a> — USDC on Base, no account, no API key. The wallet is the identity, and the safety stalls have a free daily trial, so the functions work out of the box with no wallet configured.</p>
+
+## §01 · Install
+
+```bash
+pip install game-true402
+```
+
+<p>This pulls the canonical Python GAME SDK (<code>game_sdk</code>) plus the x402 payer (<code>requests</code>, <code>eth-account</code>). You also need a GAME API key from <a href="https://console.game.virtuals.io/">console.game.virtuals.io</a>.</p>
+
+## §02 · Use
+
+```python
+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 the safety stalls.
+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?")
+```
+
+<p>To compose the functions into a full multi-worker agent instead, register the same list on a <code>WorkerConfig.action_space</code> and pass the worker to an <code>Agent(workers=[…])</code>, then call <code>agent.compile()</code> and <code>agent.run()</code>.</p>
+
+## §03 · The functions
+
+<p>The agent gets four functions. Each pays its stall over x402 and returns the standard GAME <code>(FunctionResultStatus, message, info)</code> tuple; the <code>info</code> dict is the full stall JSON, fed into your <code>get_state_fn</code> on the next step.</p>
+
+<ul>
+<li><code>check_token_report</code> — <strong>primary pre-trade gate.</strong> Composite <strong>avoid / caution / ok</strong> 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.</li>
+<li><code>check_token_safety</code> — structural safety score 0–100 and flags (honeypot sim, liquidity, mint/ownership). Lighter than the report. ~$0.005.</li>
+<li><code>check_address_safety</code> — 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.</li>
+<li><code>check_deployer</code> — deployer wallet reputation (age, contracts shipped, fresh-throwaway flag) to catch serial ruggers a structural scan can't see. ~$0.008.</li>
+</ul>
+
+## §04 · Configuration
+
+<p><code>true402_functions()</code> reads the environment, or you can pass an explicit <code>PayOpts</code>:</p>
+
+```python
+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.10,        # hard per-call ceiling — refuses to sign a 402 demanding more
+))
+```
+
+<ul>
+<li><code>PAYER_PRIVATE_KEY</code> — Base wallet key that signs x402 payments (needs USDC, not ETH). Unset means free-trial only.</li>
+<li><code>TRUE402_BASE_URL</code> — defaults to <code>https://true402.dev/api</code>; override to point at a self-hosted instance.</li>
+<li><code>BASE_RPC_URL</code> — defaults to <code>https://mainnet.base.org</code>; used only for a balance pre-check.</li>
+</ul>
+
+## §05 · Safety
+
+<p>The payer <strong>refuses to sign</strong> anything that isn't USDC-on-Base within <code>max_amount_usd</code> (default $0.10), 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.</p>
+
+## §06 · FAQ
+
+<ol>
+<li><p><strong>Do I need a true402 account or API key?</strong> 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.</p></li>
+<li><p><strong>Does it work without a funded wallet?</strong> Yes, up to a point. The safety stalls have a free daily trial, so the functions return real results with no <code>PAYER_PRIVATE_KEY</code> set — until the trial is exhausted, then they require payment.</p></li>
+<li><p><strong>Which function should the agent call before trading?</strong> <code>check_token_report</code>. It is the composite avoid/caution/ok gate and folds in the honeypot simulation, liquidity, ownership and deployer signal.</p></li>
+<li><p><strong>Why Python and not the Node GAME SDK?</strong> 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 <code>@true402.dev/langchain</code> payer.</p></li>
+<li><p><strong>What does the executable return to the planner?</strong> A <code>(FunctionResultStatus.DONE | .FAILED, message, info)</code> tuple. The message is an agent-readable summary; the <code>info</code> dict is the full stall JSON for your <code>get_state_fn</code>.</p></li>
+</ol>
+
+## §07 · Links
+
+<ul>
+<li>Live check in your browser: <a href="https://true402.dev/check">true402.dev/check</a></li>
+<li>API reference: <a href="https://true402.dev/docs/api">true402.dev/docs/api</a> · OpenAPI: <a href="https://true402.dev/openapi.json">true402.dev/openapi.json</a></li>
+<li>Also available: <a href="https://www.npmjs.com/package/@true402.dev/langchain">LangChain</a> · <a href="https://pypi.org/project/crewai-true402/">CrewAI</a> · <a href="https://www.npmjs.com/package/@true402.dev/mcp-server">MCP server</a></li>
+</ul>
+
+## §08 · License
+
+<p>MIT</p>

game_true402-0.1.0/README.md

@@ -0,0 +1,91 @@
+# game-true402
+
+<!-- meta description: Give a Virtuals Protocol GAME agent an on-chain rug, honeypot and address-safety gate — pay per call over x402, USDC on Base, no account and no API key. -->
+
+<p><strong>true402 safety stalls as <a href="https://docs.game.virtuals.io/">Virtuals Protocol GAME</a> functions.</strong> Give a G.A.M.E agent a pay-per-call, on-chain rug/honeypot gate for Base tokens over <a href="https://x402.org">x402</a> — USDC on Base, no account, no API key. The wallet is the identity, and the safety stalls have a free daily trial, so the functions work out of the box with no wallet configured.</p>
+
+## §01 · Install
+
+```bash
+pip install game-true402
+```
+
+<p>This pulls the canonical Python GAME SDK (<code>game_sdk</code>) plus the x402 payer (<code>requests</code>, <code>eth-account</code>). You also need a GAME API key from <a href="https://console.game.virtuals.io/">console.game.virtuals.io</a>.</p>
+
+## §02 · Use
+
+```python
+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 the safety stalls.
+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?")
+```
+
+<p>To compose the functions into a full multi-worker agent instead, register the same list on a <code>WorkerConfig.action_space</code> and pass the worker to an <code>Agent(workers=[…])</code>, then call <code>agent.compile()</code> and <code>agent.run()</code>.</p>
+
+## §03 · The functions
+
+<p>The agent gets four functions. Each pays its stall over x402 and returns the standard GAME <code>(FunctionResultStatus, message, info)</code> tuple; the <code>info</code> dict is the full stall JSON, fed into your <code>get_state_fn</code> on the next step.</p>
+
+<ul>
+<li><code>check_token_report</code> — <strong>primary pre-trade gate.</strong> Composite <strong>avoid / caution / ok</strong> 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.</li>
+<li><code>check_token_safety</code> — structural safety score 0–100 and flags (honeypot sim, liquidity, mint/ownership). Lighter than the report. ~$0.005.</li>
+<li><code>check_address_safety</code> — 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.</li>
+<li><code>check_deployer</code> — deployer wallet reputation (age, contracts shipped, fresh-throwaway flag) to catch serial ruggers a structural scan can't see. ~$0.008.</li>
+</ul>
+
+## §04 · Configuration
+
+<p><code>true402_functions()</code> reads the environment, or you can pass an explicit <code>PayOpts</code>:</p>
+
+```python
+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.10,        # hard per-call ceiling — refuses to sign a 402 demanding more
+))
+```
+
+<ul>
+<li><code>PAYER_PRIVATE_KEY</code> — Base wallet key that signs x402 payments (needs USDC, not ETH). Unset means free-trial only.</li>
+<li><code>TRUE402_BASE_URL</code> — defaults to <code>https://true402.dev/api</code>; override to point at a self-hosted instance.</li>
+<li><code>BASE_RPC_URL</code> — defaults to <code>https://mainnet.base.org</code>; used only for a balance pre-check.</li>
+</ul>
+
+## §05 · Safety
+
+<p>The payer <strong>refuses to sign</strong> anything that isn't USDC-on-Base within <code>max_amount_usd</code> (default $0.10), 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.</p>
+
+## §06 · FAQ
+
+<ol>
+<li><p><strong>Do I need a true402 account or API key?</strong> 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.</p></li>
+<li><p><strong>Does it work without a funded wallet?</strong> Yes, up to a point. The safety stalls have a free daily trial, so the functions return real results with no <code>PAYER_PRIVATE_KEY</code> set — until the trial is exhausted, then they require payment.</p></li>
+<li><p><strong>Which function should the agent call before trading?</strong> <code>check_token_report</code>. It is the composite avoid/caution/ok gate and folds in the honeypot simulation, liquidity, ownership and deployer signal.</p></li>
+<li><p><strong>Why Python and not the Node GAME SDK?</strong> 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 <code>@true402.dev/langchain</code> payer.</p></li>
+<li><p><strong>What does the executable return to the planner?</strong> A <code>(FunctionResultStatus.DONE | .FAILED, message, info)</code> tuple. The message is an agent-readable summary; the <code>info</code> dict is the full stall JSON for your <code>get_state_fn</code>.</p></li>
+</ol>
+
+## §07 · Links
+
+<ul>
+<li>Live check in your browser: <a href="https://true402.dev/check">true402.dev/check</a></li>
+<li>API reference: <a href="https://true402.dev/docs/api">true402.dev/docs/api</a> · OpenAPI: <a href="https://true402.dev/openapi.json">true402.dev/openapi.json</a></li>
+<li>Also available: <a href="https://www.npmjs.com/package/@true402.dev/langchain">LangChain</a> · <a href="https://pypi.org/project/crewai-true402/">CrewAI</a> · <a href="https://www.npmjs.com/package/@true402.dev/mcp-server">MCP server</a></li>
+</ul>
+
+## §08 · License
+
+<p>MIT</p>

game_true402-0.1.0/game_true402/__init__.py

@@ -0,0 +1,36 @@
+"""true402 safety stalls as Virtuals Protocol GAME (G.A.M.E) custom Functions.
+
+Give a GAME agent a pay-per-call, on-chain rug/honeypot gate for Base tokens over x402 (USDC on Base,
+no account, no API key — the wallet is the identity).
+
+    from game_true402 import true402_functions
+    from game_sdk.game.worker import Worker
+
+    worker = Worker(
+        api_key=GAME_API_KEY,
+        description="Vets tokens before trading.",
+        instruction="Always vet a token with check_token_report before acting.",
+        get_state_fn=lambda function_result, current_state: (current_state or {}),
+        action_space=true402_functions(),   # reads PAYER_PRIVATE_KEY from the env
+    )
+"""
+from .functions import (
+    address_safety_function,
+    deployer_check_function,
+    token_report_function,
+    token_safety_function,
+    true402_functions,
+)
+from .x402 import PayOpts, pay_stall, sign_payment
+
+__version__ = "0.1.0"
+__all__ = [
+    "true402_functions",
+    "token_report_function",
+    "token_safety_function",
+    "address_safety_function",
+    "deployer_check_function",
+    "PayOpts",
+    "pay_stall",
+    "sign_payment",
+]

game_true402-0.1.0/game_true402/functions.py

@@ -0,0 +1,160 @@
+"""true402 safety stalls as Virtuals Protocol GAME (G.A.M.E) custom Functions.
+
+    from game_true402 import true402_functions
+    action_space = true402_functions()   # reads PAYER_PRIVATE_KEY from the env
+
+Each stall is a GAME `Function` whose `executable` pays the stall over x402 (USDC on Base) and
+returns the standard `(FunctionResultStatus, message, info)` 3-tuple. The GAME planner passes each
+declared `Argument` to the executable BY NAME, so the executables accept keyword args plus `**kwargs`
+(the SDK injects extra keys). `token_report` is the primary pre-trade gate.
+"""
+from __future__ import annotations
+
+import json
+from typing import Callable, Optional
+
+from game_sdk.game.custom_types import Argument, Function, FunctionResultStatus
+
+from .x402 import PayOpts, pay_stall
+
+
+def _summarize(data: object) -> str:
+    """Best-effort human/agent-readable one-liner from a stall's JSON, without inventing fields."""
+    if not isinstance(data, dict):
+        return str(data)[:300]
+    parts = []
+    for key in ("verdict", "score", "risk", "riskLevel", "reputation", "recommendation"):
+        if key in data and data[key] is not None:
+            parts.append(f"{key}={data[key]}")
+    return ", ".join(parts) if parts else json.dumps(data)[:300]
+
+
+def _make_executable(path: str, input_key: str, opts_provider: Callable[[], PayOpts]):
+    """Build a GAME executable that reads `input_key` from the passed-by-name args and pays the stall."""
+
+    def executable(**kwargs):
+        value = kwargs.get(input_key)
+        if not value or not isinstance(value, str):
+            return (
+                FunctionResultStatus.FAILED,
+                f"missing required '{input_key}' (a 0x Base address)",
+                {},
+            )
+        try:
+            data = pay_stall(path, {input_key: value}, opts_provider())
+        except Exception as exc:  # noqa: BLE001 — surface any failure to the planner
+            return (
+                FunctionResultStatus.FAILED,
+                f"{path} check for {value} failed: {exc}",
+                {},
+            )
+        info = data if isinstance(data, dict) else {"result": data}
+        return (
+            FunctionResultStatus.DONE,
+            f"{path} → {_summarize(data)}",
+            info,
+        )
+
+    return executable
+
+
+def token_report_function(opts_provider: Callable[[], PayOpts]) -> Function:
+    """PRIMARY pre-trade gate — composite avoid/caution/ok verdict for a Base ERC-20."""
+    return Function(
+        fn_name="check_token_report",
+        fn_description=(
+            "Pre-trade rug/honeypot gate for a Base ERC-20 token. Runs a real on-chain buy/sell "
+            "honeypot simulation (proves sellability, not just a static scan) plus liquidity, "
+            "ownership/mint and recent rug activity, and returns a composite avoid/caution/ok "
+            "verdict. Call this BEFORE buying any token. Pays ~$0.01 USDC on Base over x402."
+        ),
+        args=[
+            Argument(
+                name="token",
+                type="string",
+                description="The Base ERC-20 token contract address to vet (0x…).",
+            ),
+        ],
+        executable=_make_executable("/v1/base/token-report", "token", opts_provider),
+    )
+
+
+def token_safety_function(opts_provider: Callable[[], PayOpts]) -> Function:
+    """Structural safety score 0-100 + flags (lighter than token_report)."""
+    return Function(
+        fn_name="check_token_safety",
+        fn_description=(
+            "Structural safety score (0–100) and flags for a Base ERC-20 token: honeypot simulation, "
+            "liquidity, mint/ownership/blacklist. Lighter than check_token_report. "
+            "Pays ~$0.005 USDC on Base over x402."
+        ),
+        args=[
+            Argument(
+                name="token",
+                type="string",
+                description="The Base ERC-20 token contract address to score (0x…).",
+            ),
+        ],
+        executable=_make_executable("/v1/token-safety", "token", opts_provider),
+    )
+
+
+def address_safety_function(opts_provider: Callable[[], PayOpts]) -> Function:
+    """Screen any Base address before send / approve / call."""
+    return Function(
+        fn_name="check_address_safety",
+        fn_description=(
+            "Screen any Base address before you send to, approve, or call it: EOA-vs-contract, "
+            "ETH+USDC balance, activity, ownership and upgradeable-proxy (EIP-1967) detection. "
+            "Pays ~$0.005 USDC on Base over x402."
+        ),
+        args=[
+            Argument(
+                name="address",
+                type="string",
+                description="Any Base address to screen (0x…) — an EOA or a contract.",
+            ),
+        ],
+        executable=_make_executable("/v1/base/address-safety", "address", opts_provider),
+    )
+
+
+def deployer_check_function(opts_provider: Callable[[], PayOpts]) -> Function:
+    """Deployer wallet reputation — catches serial ruggers a structural scan can't see."""
+    return Function(
+        fn_name="check_deployer",
+        fn_description=(
+            "Deployer reputation for a Base token: resolves who created it and that wallet's track "
+            "record (age, contracts shipped, fresh-throwaway flag) to catch serial ruggers a "
+            "structural check can't see. Pays ~$0.008 USDC on Base over x402."
+        ),
+        args=[
+            Argument(
+                name="token",
+                type="string",
+                description="The Base ERC-20 token contract address whose deployer to check (0x…).",
+            ),
+        ],
+        executable=_make_executable("/v1/base/deployer-check", "token", opts_provider),
+    )
+
+
+def true402_functions(opts: Optional[PayOpts] = None) -> list[Function]:
+    """The four true402 safety Functions, ready to drop into a GAME Worker `action_space`.
+
+    Pass a `PayOpts`, or leave `None` to read PAYER_PRIVATE_KEY / TRUE402_BASE_URL / BASE_RPC_URL from
+    the environment. The safety stalls have a free daily trial, so the functions return real results
+    even with no wallet configured — until the trial is exhausted, then they require payment.
+    `check_token_report` is the primary pre-trade gate.
+    """
+    resolved = opts or PayOpts.from_env()
+
+    def opts_provider() -> PayOpts:
+        return resolved
+
+    return [
+        token_report_function(opts_provider),
+        token_safety_function(opts_provider),
+        address_safety_function(opts_provider),
+        deployer_check_function(opts_provider),
+    ]

game_true402-0.1.0/game_true402/x402.py

@@ -0,0 +1,169 @@
+"""Pay any true402 stall over x402 and return its JSON.
+
+The whole protocol, in one function: POST → 402 with payment terms → sign an EIP-3009 USDC
+authorization → retry with an X-PAYMENT header → 200. No accounts, no API keys; the wallet is the
+identity. USDC on Base, gas sponsored by the facilitator (the payer needs only USDC, not ETH).
+
+Safety: the client REFUSES to sign anything that isn't USDC-on-Base within a caller-set cap, so a
+rogue/compromised endpoint (or a MITM past TLS) can't make the agent authorize an unexpected
+asset/network or an excessive amount.
+"""
+from __future__ import annotations
+
+import json
+import os
+import secrets
+import time
+from dataclasses import dataclass
+from typing import Any
+
+import requests
+from eth_account import Account
+from eth_account.messages import encode_typed_data
+
+BASE_USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
+BASE_NETWORK = "eip155:8453"
+BASE_CHAIN_ID = 8453
+DEFAULT_BASE_URL = "https://true402.dev/api"
+DEFAULT_RPC_URL = "https://mainnet.base.org"
+_BALANCE_OF_SELECTOR = "0x70a08231"
+
+
+@dataclass
+class PayOpts:
+    """Configuration for paying true402 stalls."""
+
+    payer_private_key: str
+    """A Base wallet private key holding a little USDC (the payer)."""
+    base_url: str = DEFAULT_BASE_URL
+    rpc_url: str = DEFAULT_RPC_URL
+    max_amount_usd: float = 0.10
+    """Hard ceiling, in USDC, on a single signed payment. The client refuses a 402 demanding more."""
+    timeout: float = 30.0
+
+    @classmethod
+    def from_env(cls, **overrides: Any) -> "PayOpts":
+        """Build from PAYER_PRIVATE_KEY / TRUE402_BASE_URL / BASE_RPC_URL env vars."""
+        key = overrides.pop("payer_private_key", None) or os.environ.get("PAYER_PRIVATE_KEY", "")
+        return cls(
+            payer_private_key=key,
+            base_url=overrides.pop("base_url", None) or os.environ.get("TRUE402_BASE_URL", DEFAULT_BASE_URL),
+            rpc_url=overrides.pop("rpc_url", None) or os.environ.get("BASE_RPC_URL", DEFAULT_RPC_URL),
+            **overrides,
+        )
+
+
+def _usdc_balance(rpc_url: str, holder: str, timeout: float) -> int:
+    data = _BALANCE_OF_SELECTOR + holder[2:].rjust(64, "0")
+    body = {"jsonrpc": "2.0", "id": 1, "method": "eth_call", "params": [{"to": BASE_USDC, "data": data}, "latest"]}
+    r = requests.post(rpc_url, json=body, timeout=timeout, headers={"content-type": "application/json"})
+    r.raise_for_status()
+    return int(r.json()["result"], 16)
+
+
+def sign_payment(accept: dict, opts: PayOpts) -> str:
+    """Sign an EIP-3009 authorization for the given 402 `accepts[]` entry → base64 X-PAYMENT value."""
+    key = opts.payer_private_key
+    if not key:
+        raise ValueError("no payer_private_key set — cannot pay (set PAYER_PRIVATE_KEY or PayOpts.payer_private_key)")
+    if not key.startswith("0x"):
+        key = "0x" + key
+    account = Account.from_key(key)
+
+    network = accept.get("network")
+    if network and network != BASE_NETWORK:
+        raise ValueError(f'unexpected payment network "{network}" (expected {BASE_NETWORK}) — refusing to sign')
+    asset = accept.get("asset", "")
+    if asset.lower() != BASE_USDC.lower():
+        raise ValueError(f"unexpected payment asset {asset} (expected Base USDC) — refusing to sign")
+
+    value = int(accept.get("amount") or accept.get("maxAmountRequired") or "0")
+    cap_atomic = round(opts.max_amount_usd * 1e6)
+    if value > cap_atomic:
+        raise ValueError(f"402 demands {value} USDC base units, over the ${opts.max_amount_usd} cap — refusing to sign")
+
+    held = _usdc_balance(opts.rpc_url, account.address, opts.timeout)
+    if held < value:
+        raise ValueError(f"payer {account.address} holds {held} < {value} USDC base units — fund it")
+
+    now = int(time.time())
+    valid_before = now + int(accept.get("maxTimeoutSeconds") or 120)
+    nonce = "0x" + secrets.token_hex(32)
+    extra = accept.get("extra") or {}
+    authorization = {
+        "from": account.address,
+        "to": accept["payTo"],
+        "value": value,
+        "validAfter": now - 60,
+        "validBefore": valid_before,
+        "nonce": bytes.fromhex(nonce[2:]),
+    }
+    signable = encode_typed_data(
+        domain_data={
+            "name": extra.get("name", "USD Coin"),
+            "version": extra.get("version", "2"),
+            "chainId": BASE_CHAIN_ID,
+            "verifyingContract": BASE_USDC,
+        },
+        message_types={
+            "TransferWithAuthorization": [
+                {"name": "from", "type": "address"},
+                {"name": "to", "type": "address"},
+                {"name": "value", "type": "uint256"},
+                {"name": "validAfter", "type": "uint256"},
+                {"name": "validBefore", "type": "uint256"},
+                {"name": "nonce", "type": "bytes32"},
+            ],
+        },
+        message_data=authorization,
+    )
+    signature = Account.sign_message(signable, key).signature.hex()
+    if not signature.startswith("0x"):
+        signature = "0x" + signature
+
+    payment = {
+        "x402Version": 2,
+        "scheme": "exact",
+        "network": network,
+        "payload": {
+            "signature": signature,
+            "authorization": {
+                "from": authorization["from"],
+                "to": authorization["to"],
+                "value": str(value),
+                "validAfter": str(authorization["validAfter"]),
+                "validBefore": str(authorization["validBefore"]),
+                "nonce": nonce,
+            },
+        },
+    }
+    import base64
+
+    return base64.b64encode(json.dumps(payment).encode()).decode()
+
+
+def pay_stall(path: str, payload: dict, opts: PayOpts) -> Any:
+    """POST `payload` to a true402 stall path (e.g. '/v1/base/token-report'), paying over x402 if asked.
+
+    If the first response is 200 (a free-trial call), returns it without paying. If it's 402, signs and
+    retries. Raises on any other status or on a refused/insufficient payment.
+    """
+    url = opts.base_url.rstrip("/") + path
+    headers = {"content-type": "application/json"}
+    first = requests.post(url, json=payload, headers=headers, timeout=opts.timeout)
+    if first.status_code == 200:
+        return first.json()  # served free (free trial) — no payment needed
+    if first.status_code != 402:
+        raise RuntimeError(f"expected HTTP 402 from {path}, got {first.status_code}: {first.text[:200]}")
+
+    challenge = first.json()
+    accepts = challenge.get("accepts") or []
+    accept = next((a for a in accepts if a.get("scheme") == "exact"), None)
+    if not accept:
+        raise RuntimeError('no x402 "exact" payment requirement in the 402')
+
+    x_payment = sign_payment(accept, opts)
+    paid = requests.post(url, json=payload, headers={**headers, "X-PAYMENT": x_payment}, timeout=opts.timeout)
+    if paid.status_code != 200:
+        raise RuntimeError(f"paid request to {path} failed (HTTP {paid.status_code}): {paid.text[:200]}")
+    return paid.json()

game_true402-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "game-true402"
+version = "0.1.0"
+description = "true402 safety stalls as Virtuals Protocol GAME functions — pay-per-call on-chain rug/honeypot & address safety for Base AI agents over x402 (USDC, no account, no API key)."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+keywords = ["virtuals", "game-sdk", "game-by-virtuals", "x402", "base", "rug-check", "honeypot", "token-safety", "crypto", "ai-agent", "agent-tools", "defi", "web3"]
+authors = [{ name = "true402", email = "contact@true402.dev" }]
+dependencies = [
+    "game_sdk>=0.1",
+    "requests>=2.28",
+    "eth-account>=0.11",
+]
+
+[project.urls]
+Homepage = "https://true402.dev"
+Source = "https://github.com/true402/game-true402"
+"OpenAPI" = "https://true402.dev/openapi.json"
+
+[tool.hatch.build.targets.wheel]
+packages = ["game_true402"]