tensorfeed 3.0.0__tar.gz → 3.1.0__tar.gz

{tensorfeed-3.0.0 → tensorfeed-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tensorfeed
-Version: 3.0.0
+Version: 3.1.0
 Summary: Python SDK for the TensorFeed.ai API: AI news, status, model pricing, premium routing + history series + webhook watches, LangChain/CrewAI tool factories, agent payments via USDC on Base (optional web3 auto-send)
 Author-email: "TensorFeed.ai" <feedback@tensorfeed.ai>
 License-Expression: MIT
@@ -137,19 +137,29 @@ print(preview["recommendation"])
 ## Premium Tier (paid, USDC on Base)
 
 ```python
+import os
+from eth_account import Account                      # pip install eth-account
+from eth_account.messages import encode_defunct
 from tensorfeed import TensorFeed, PaymentRequired
 
 tf = TensorFeed()
+acct = Account.from_key(os.environ["TENSORFEED_PRIVATE_KEY"])  # NEVER hardcode
 
 # Step 1: get a 30-minute quote. sender_wallet is the Base wallet you will
 # send the USDC from (required); quote['wallet'] below is where you send it.
-quote = tf.buy_credits(amount_usd=1.00, sender_wallet="0xYourBaseWallet")
+# The server only quotes for a message signed by sender_wallet, so pass a
+# signer: the SDK builds the message and calls it once.
+quote = tf.buy_credits(
+    amount_usd=1.00,
+    sender_wallet=acct.address,
+    sign_message=lambda m: acct.sign_message(encode_defunct(text=m)).signature.hex(),
+)
 print(f"Send {quote['amount_usd']} USDC on Base to {quote['wallet']}")
 print(f"Memo: {quote['memo']} (expires in {quote['ttl_seconds']}s)")
 print(f"Will get: {quote['credits']} credits")
 
-# Step 2: send the USDC tx with your wallet
-# (auto-send via web3 is on the roadmap; for v1.1 you sign and send manually)
+# Step 2: send the USDC tx from sender_wallet
+# (or let tf.purchase_credits() below do steps 1 to 3 for you)
 
 # Step 3: confirm with the tx hash
 result = tf.confirm(tx_hash="0xYOUR_TX_HASH", nonce=quote["memo"])
@@ -206,6 +216,34 @@ tf.delete_watch(watch_id)         # remove when done
 print(tf.balance())
 ```
 
+### Signing the quote request
+
+`buy_credits()` requires proof that you control `sender_wallet`: an EIP-191 (`personal_sign`) signature by that wallet over this exact message, lines joined with `\n`:
+
+```
+I am requesting a TensorFeed credit quote for this wallet.
+
+wallet: <sender_wallet, 0x address>
+timestamp: <ISO 8601, within 10 minutes of now>
+nonce: <16 to 64 hex chars, fresh per quote>
+```
+
+Pass `sign_message=` (any callable that takes the message string and returns a 0x hex signature) and the SDK fills in the timestamp and a random nonce. If your signer lives elsewhere (a hardware wallet, a remote signing service), build the message yourself and pass both halves:
+
+```python
+from tensorfeed import build_quote_message
+
+message = build_quote_message(wallet)          # timestamp=now, nonce=random
+signature = my_remote_signer.personal_sign(message)
+quote = tf.buy_credits(
+    amount_usd=1.00, sender_wallet=wallet, message=message, signature=signature
+)
+```
+
+Each signed message is good for one quote. The server answers `sender_proof_expired` for a stale timestamp, `sender_proof_invalid` when the signature does not match the wallet, and `sender_proof_replayed` for a reused nonce. Calling `buy_credits()` with no signer and no message raises `ValueError` before any request is sent.
+
+Only an externally owned account (a plain private key) can produce this signature. Smart contract wallets cannot, and should pay per call through the x402 `X-PAYMENT` flow instead.
+
 ## Auto-Send (optional, web3 extra)
 
 The base SDK keeps you dependency-free, but if you want to skip the manual tx step, install with the `web3` extra:
@@ -214,7 +252,7 @@ The base SDK keeps you dependency-free, but if you want to skip the manual tx st
 pip install 'tensorfeed[web3]'
 ```
 
-Then `tf.purchase_credits()` quotes, signs, broadcasts, and confirms in one call:
+Then `tf.purchase_credits()` quotes, signs, broadcasts, and confirms in one call. The same key signs the quote request message and the USDC transfer:
 
 ```python
 import os
@@ -317,7 +355,8 @@ except TensorFeedError as e:
 | `tf.routing_preview(task=)` | Top-1 routing recommendation (5/day/IP) |
 | `tf.health()` | API health check |
 | `tf.payment_info()` | Wallet, pricing, supported payment flows |
-| `tf.buy_credits(amount_usd=, sender_wallet=)` | Generate a 30-min payment quote |
+| `tf.buy_credits(amount_usd=, sender_wallet=, sign_message=)` | Generate a 30-min payment quote (or pass `message=` and `signature=` instead of `sign_message=`) |
+| `build_quote_message(wallet, timestamp=, nonce=)` | Build the exact quote message `sender_wallet` signs |
 | `tf.confirm(tx_hash=, nonce=)` | Verify USDC tx, mint credit token |
 
 ### Token-required
@@ -367,7 +406,7 @@ Premium API responses are licensed for inference use only. Use of TensorFeed pre
 
 ## No refunds; credits do not expire
 
-All credit purchases are final and non-refundable per Section 17.5 of the [Terms](https://tensorfeed.ai/terms#premium). Credits never expire and are jointly redeemable on tensorfeed.ai and terminalfeed.io. The recommended pattern is to buy in small increments (for example, $1 USDC for 50 credits) until call volume is calibrated, then top up as needed.
+All credit purchases are final and non-refundable per Section 17.5 of the [Terms](https://tensorfeed.ai/terms#premium). Credits never expire while the token holds them, and a zero-balance token is deleted 30 days after its last use. The recommended pattern is to buy in small increments (for example, $1 USDC for 50 credits) until call volume is calibrated, then top up as needed.
 
 ## Sanctions
 

{tensorfeed-3.0.0 → tensorfeed-3.1.0}/README.md

@@ -104,19 +104,29 @@ print(preview["recommendation"])
 ## Premium Tier (paid, USDC on Base)
 
 ```python
+import os
+from eth_account import Account                      # pip install eth-account
+from eth_account.messages import encode_defunct
 from tensorfeed import TensorFeed, PaymentRequired
 
 tf = TensorFeed()
+acct = Account.from_key(os.environ["TENSORFEED_PRIVATE_KEY"])  # NEVER hardcode
 
 # Step 1: get a 30-minute quote. sender_wallet is the Base wallet you will
 # send the USDC from (required); quote['wallet'] below is where you send it.
-quote = tf.buy_credits(amount_usd=1.00, sender_wallet="0xYourBaseWallet")
+# The server only quotes for a message signed by sender_wallet, so pass a
+# signer: the SDK builds the message and calls it once.
+quote = tf.buy_credits(
+    amount_usd=1.00,
+    sender_wallet=acct.address,
+    sign_message=lambda m: acct.sign_message(encode_defunct(text=m)).signature.hex(),
+)
 print(f"Send {quote['amount_usd']} USDC on Base to {quote['wallet']}")
 print(f"Memo: {quote['memo']} (expires in {quote['ttl_seconds']}s)")
 print(f"Will get: {quote['credits']} credits")
 
-# Step 2: send the USDC tx with your wallet
-# (auto-send via web3 is on the roadmap; for v1.1 you sign and send manually)
+# Step 2: send the USDC tx from sender_wallet
+# (or let tf.purchase_credits() below do steps 1 to 3 for you)
 
 # Step 3: confirm with the tx hash
 result = tf.confirm(tx_hash="0xYOUR_TX_HASH", nonce=quote["memo"])
@@ -173,6 +183,34 @@ tf.delete_watch(watch_id)         # remove when done
 print(tf.balance())
 ```
 
+### Signing the quote request
+
+`buy_credits()` requires proof that you control `sender_wallet`: an EIP-191 (`personal_sign`) signature by that wallet over this exact message, lines joined with `\n`:
+
+```
+I am requesting a TensorFeed credit quote for this wallet.
+
+wallet: <sender_wallet, 0x address>
+timestamp: <ISO 8601, within 10 minutes of now>
+nonce: <16 to 64 hex chars, fresh per quote>
+```
+
+Pass `sign_message=` (any callable that takes the message string and returns a 0x hex signature) and the SDK fills in the timestamp and a random nonce. If your signer lives elsewhere (a hardware wallet, a remote signing service), build the message yourself and pass both halves:
+
+```python
+from tensorfeed import build_quote_message
+
+message = build_quote_message(wallet)          # timestamp=now, nonce=random
+signature = my_remote_signer.personal_sign(message)
+quote = tf.buy_credits(
+    amount_usd=1.00, sender_wallet=wallet, message=message, signature=signature
+)
+```
+
+Each signed message is good for one quote. The server answers `sender_proof_expired` for a stale timestamp, `sender_proof_invalid` when the signature does not match the wallet, and `sender_proof_replayed` for a reused nonce. Calling `buy_credits()` with no signer and no message raises `ValueError` before any request is sent.
+
+Only an externally owned account (a plain private key) can produce this signature. Smart contract wallets cannot, and should pay per call through the x402 `X-PAYMENT` flow instead.
+
 ## Auto-Send (optional, web3 extra)
 
 The base SDK keeps you dependency-free, but if you want to skip the manual tx step, install with the `web3` extra:
@@ -181,7 +219,7 @@ The base SDK keeps you dependency-free, but if you want to skip the manual tx st
 pip install 'tensorfeed[web3]'
 ```
 
-Then `tf.purchase_credits()` quotes, signs, broadcasts, and confirms in one call:
+Then `tf.purchase_credits()` quotes, signs, broadcasts, and confirms in one call. The same key signs the quote request message and the USDC transfer:
 
 ```python
 import os
@@ -284,7 +322,8 @@ except TensorFeedError as e:
 | `tf.routing_preview(task=)` | Top-1 routing recommendation (5/day/IP) |
 | `tf.health()` | API health check |
 | `tf.payment_info()` | Wallet, pricing, supported payment flows |
-| `tf.buy_credits(amount_usd=, sender_wallet=)` | Generate a 30-min payment quote |
+| `tf.buy_credits(amount_usd=, sender_wallet=, sign_message=)` | Generate a 30-min payment quote (or pass `message=` and `signature=` instead of `sign_message=`) |
+| `build_quote_message(wallet, timestamp=, nonce=)` | Build the exact quote message `sender_wallet` signs |
 | `tf.confirm(tx_hash=, nonce=)` | Verify USDC tx, mint credit token |
 
 ### Token-required
@@ -334,7 +373,7 @@ Premium API responses are licensed for inference use only. Use of TensorFeed pre
 
 ## No refunds; credits do not expire
 
-All credit purchases are final and non-refundable per Section 17.5 of the [Terms](https://tensorfeed.ai/terms#premium). Credits never expire and are jointly redeemable on tensorfeed.ai and terminalfeed.io. The recommended pattern is to buy in small increments (for example, $1 USDC for 50 credits) until call volume is calibrated, then top up as needed.
+All credit purchases are final and non-refundable per Section 17.5 of the [Terms](https://tensorfeed.ai/terms#premium). Credits never expire while the token holds them, and a zero-balance token is deleted 30 days after its last use. The recommended pattern is to buy in small increments (for example, $1 USDC for 50 credits) until call volume is calibrated, then top up as needed.
 
 ## Sanctions
 

{tensorfeed-3.0.0 → tensorfeed-3.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tensorfeed"
-version = "3.0.0"
+version = "3.1.0"
 description = "Python SDK for the TensorFeed.ai API: AI news, status, model pricing, premium routing + history series + webhook watches, LangChain/CrewAI tool factories, agent payments via USDC on Base (optional web3 auto-send)"
 readme = "README.md"
 license = "MIT"

{tensorfeed-3.0.0 → tensorfeed-3.1.0}/tensorfeed/__init__.py

@@ -13,6 +13,7 @@ from .client import (
     TensorFeedError,
     PaymentRequired,
     RateLimited,
+    build_quote_message,
 )
 
 __all__ = [
@@ -20,5 +21,6 @@ __all__ = [
     "TensorFeedError",
     "PaymentRequired",
     "RateLimited",
+    "build_quote_message",
 ]
-__version__ = "3.0.0"
+__version__ = "3.1.0"

{tensorfeed-3.0.0 → tensorfeed-3.1.0}/tensorfeed/client.py

@@ -6,19 +6,106 @@ agent activity) plus the paid premium tier (routing, payment flow).
 
 Premium endpoints are paid via USDC on Base. No accounts, no API keys,
 no traditional payment processors. See ``buy_credits()`` and ``confirm()``.
+
+A credit quote requires proof that you control the paying wallet:
+``buy_credits()`` sends a short message signed by ``sender_wallet``
+(EIP-191 personal_sign). Pass ``sign_message=`` and the SDK builds the
+message for you, or build it yourself with ``build_quote_message()``.
+Smart contract wallets cannot produce this signature and should pay
+through the x402 X-PAYMENT flow instead.
 """
 
 from __future__ import annotations
 
 import json
+import secrets
 import urllib.error
 import urllib.parse
 import urllib.request
-from typing import Any  # noqa: F401  (re-exported by purchase_credits return type)
+from datetime import datetime, timezone
+from typing import Any, Callable
 
 
 DEFAULT_BASE_URL = "https://tensorfeed.ai/api"
-DEFAULT_USER_AGENT = "TensorFeed-SDK-Python/3.0"
+DEFAULT_USER_AGENT = "TensorFeed-SDK-Python/3.1"
+
+# First line of the credit quote message. The server requires it to
+# match exactly, so a message signed for another flow is never accepted.
+QUOTE_PROOF_HEADER = "I am requesting a TensorFeed credit quote for this wallet."
+
+
+def _utc_now_iso() -> str:
+    """Current UTC time as ISO 8601 with milliseconds and a Z suffix."""
+    return (
+        datetime.now(timezone.utc)
+        .isoformat(timespec="milliseconds")
+        .replace("+00:00", "Z")
+    )
+
+
+def build_quote_message(
+    wallet: str,
+    timestamp: str | None = None,
+    nonce: str | None = None,
+) -> str:
+    """Build the exact message ``sender_wallet`` signs for a credit quote.
+
+    The layout is fixed and must be signed byte for byte (lines joined
+    with LF)::
+
+        I am requesting a TensorFeed credit quote for this wallet.
+
+        wallet: 0x...
+        timestamp: 2026-11-06T12:00:00.000Z
+        nonce: 3f9c...
+
+    Sign the returned string with EIP-191 personal_sign using the key
+    for ``wallet``, then pass it to ``TensorFeed.buy_credits()`` as
+    ``message`` with the resulting ``signature``. Each message works for
+    one quote only.
+
+    Args:
+        wallet: The 0x address that will send the USDC (the same value
+            you pass as ``sender_wallet``).
+        timestamp: ISO 8601 time. Defaults to now in UTC. The server
+            accepts it within 10 minutes of its clock, and at most 60
+            seconds in the future.
+        nonce: 16 to 64 hex characters, fresh per quote. Defaults to
+            ``secrets.token_hex(16)``.
+    """
+    if timestamp is None:
+        timestamp = _utc_now_iso()
+    if nonce is None:
+        nonce = secrets.token_hex(16)
+    return "\n".join(
+        [
+            QUOTE_PROOF_HEADER,
+            "",
+            f"wallet: {wallet}",
+            f"timestamp: {timestamp}",
+            f"nonce: {nonce}",
+        ]
+    )
+
+
+def _normalize_signature(signature: Any) -> str:
+    """Return a signature as a 0x-prefixed hex string.
+
+    Signers differ: eth_account returns HexBytes, whose ``.hex()`` has
+    the 0x prefix on some versions and not on others. Accept raw bytes
+    or hex with or without the prefix.
+    """
+    if isinstance(signature, (bytes, bytearray)):
+        return "0x" + bytes(signature).hex()
+    if not isinstance(signature, str):
+        raise TypeError(
+            "signature must be a 0x-prefixed hex string (or bytes), "
+            f"got {type(signature).__name__}"
+        )
+    sig = signature.strip()
+    if sig[:2].lower() != "0x":
+        sig = "0x" + sig
+    return sig
 
 
 class TensorFeedError(Exception):
@@ -59,9 +146,20 @@ class TensorFeed:
         news = tf.news(limit=10)
         preview = tf.routing_preview(task="code")
 
-        # Paid: buy credits, then call routing
-        quote = tf.buy_credits(amount_usd=1.00)
-        # ... send USDC tx ...
+        # Paid: buy credits, then call routing. The quote needs a
+        # message signed by sender_wallet (see buy_credits()).
+        from eth_account import Account
+        from eth_account.messages import encode_defunct
+
+        acct = Account.from_key(os.environ["TENSORFEED_PRIVATE_KEY"])
+        quote = tf.buy_credits(
+            amount_usd=1.00,
+            sender_wallet=acct.address,
+            sign_message=lambda m: acct.sign_message(
+                encode_defunct(text=m)
+            ).signature.hex(),
+        )
+        # ... send USDC tx from acct.address ...
         result = tf.confirm(tx_hash="0x...", nonce=quote["memo"])
         # token is auto-stored on the client
         rec = tf.routing(task="code", top_n=5)
@@ -608,28 +706,101 @@ class TensorFeed:
         """
         return self._get("/payment/info")
 
-    def buy_credits(self, *, amount_usd: float, sender_wallet: str) -> dict[str, Any]:
+    def buy_credits(
+        self,
+        *,
+        amount_usd: float,
+        sender_wallet: str,
+        sign_message: Callable[[str], str] | None = None,
+        message: str | None = None,
+        signature: str | None = None,
+    ) -> dict[str, Any]:
         """Generate a 30-min payment quote bound to a sender wallet.
 
         Returns a dict with ``wallet``, ``memo``, ``amount_usd``, ``credits``,
         ``sender_wallet``, ``expires_at``, ``ttl_seconds``, ``next_step``.
 
+        The server issues a quote only for a message signed by
+        ``sender_wallet`` (EIP-191 personal_sign), so supply one of:
+
+        * ``sign_message``: a callable that takes the message string and
+          returns its signature as 0x hex. The SDK builds the message
+          (UTC timestamp, fresh random nonce) and calls it once.
+        * ``message`` plus ``signature``: a message you built with
+          ``build_quote_message()`` and signed yourself. Each signed
+          message is single use.
+
+        With eth_account::
+
+            from eth_account import Account
+            from eth_account.messages import encode_defunct
+
+            acct = Account.from_key(os.environ["TENSORFEED_PRIVATE_KEY"])
+            quote = tf.buy_credits(
+                amount_usd=1.00,
+                sender_wallet=acct.address,
+                sign_message=lambda m: acct.sign_message(
+                    encode_defunct(text=m)
+                ).signature.hex(),
+            )
+
+        Only an externally owned account (a plain private key) can sign
+        this. A smart contract wallet cannot, and should pay per call
+        through the x402 X-PAYMENT flow instead.
+
         Send the USDC on Base FROM ``sender_wallet`` TO ``wallet``, then
         call ``confirm()`` with the tx hash and the returned ``memo`` as
         nonce. The on-chain sender must match ``sender_wallet`` exactly
-        or ``confirm()`` will reject with ``sender_mismatch``. This is
-        the post-2026-05-05 binding that closes the public-mempool tx
-        sniper attack.
+        or ``confirm()`` will reject with ``sender_mismatch``.
 
         Args:
             amount_usd: USD value of credits to buy. Must be 0.5 to 10000.
                 Volume discounts apply at $5 (10%), $30 (25%), $200 (40%).
             sender_wallet: 0x-prefixed 40-char EVM address that will sign
                 the on-chain USDC transfer. Required.
+            sign_message: Callable that signs the quote message with the
+                key for ``sender_wallet`` and returns the signature (0x
+                hex string; raw bytes are also accepted).
+            message: A pre-built quote message from
+                ``build_quote_message()``. Use with ``signature``.
+            signature: The EIP-191 signature of ``message`` by
+                ``sender_wallet`` (0x followed by 130 hex characters).
+
+        Raises:
+            ValueError: if no signer and no message plus signature is
+                supplied, or if both are. Raised before any HTTP call.
+            TensorFeedError: on a server-side rejection, for example
+                ``sender_proof_expired`` (timestamp outside the 10 minute
+                window), ``sender_proof_invalid`` (signature does not
+                match), or ``sender_proof_replayed`` (nonce already used).
         """
+        if sign_message is not None:
+            if message is not None or signature is not None:
+                raise ValueError(
+                    "buy_credits(): pass either sign_message or message plus "
+                    "signature, not both."
+                )
+            message = build_quote_message(sender_wallet.strip())
+            signature = sign_message(message)
+        elif message is None or signature is None:
+            raise ValueError(
+                "buy_credits() needs proof that you control sender_wallet. "
+                "TensorFeed now issues a credit quote only for a message "
+                "signed by sender_wallet (EIP-191 personal_sign). Pass "
+                "sign_message=<callable that signs a str and returns a 0x hex "
+                "signature>, or pass message= (from build_quote_message()) "
+                "and signature=. Smart contract wallets cannot sign this; "
+                "pay through the x402 X-PAYMENT flow instead. See "
+                "https://tensorfeed.ai/developers/agent-payments#sender-proof"
+            )
         return self._post(
             "/payment/buy-credits",
-            {"amount_usd": amount_usd, "sender_wallet": sender_wallet},
+            {
+                "amount_usd": amount_usd,
+                "sender_wallet": sender_wallet,
+                "message": message,
+                "signature": _normalize_signature(signature),
+            },
         )
 
     def confirm(
@@ -709,9 +880,11 @@ class TensorFeed:
         """Buy credits end-to-end: quote, sign USDC tx, broadcast, confirm.
 
         Convenience wrapper around buy_credits() + raw signing + confirm()
-        that handles the whole flow in one call. The token is auto-stored
-        on this client on success, so subsequent ``routing()`` calls work
-        immediately.
+        that handles the whole flow in one call. The same key signs the
+        quote request message and the USDC transfer, so it must be an
+        externally owned account (not a smart contract wallet). The token
+        is auto-stored on this client on success, so subsequent
+        ``routing()`` calls work immediately.
 
         Requires the optional ``web3`` extra:
             pip install 'tensorfeed[web3]'

{tensorfeed-3.0.0 → tensorfeed-3.1.0}/tensorfeed/web3_signer.py

@@ -14,10 +14,12 @@ Security:
     Cloudflare Workers and similar environments should keep the key in
     a secret manager.
 
-    For higher security, sign transactions externally (e.g., via a
-    hardware wallet or remote signer) and call ``TensorFeed.confirm()``
-    with the resulting tx hash directly. The auto-send path here is for
-    server-side agents that hold their own keys.
+    For higher security, sign externally (e.g., via a hardware wallet or
+    remote signer): pass that signer to
+    ``TensorFeed.buy_credits(sign_message=...)`` for the quote, send the
+    USDC transfer yourself, and call ``TensorFeed.confirm()`` with the
+    resulting tx hash. The auto-send path here is for server-side agents
+    that hold their own keys.
 """
 
 from __future__ import annotations
@@ -63,14 +65,19 @@ def auto_purchase_credits(
 ) -> dict[str, Any]:
     """Buy credits end-to-end: quote, sign USDC tx, broadcast, confirm.
 
+    The same key signs the quote request message (EIP-191, required by
+    ``buy_credits()``) and the on-chain USDC transfer, so the key must
+    belong to an externally owned account. Smart contract wallets cannot
+    use this flow; pay through the x402 X-PAYMENT flow instead.
+
     Args:
         tf: The TensorFeed client. Token is auto-stored on success so
             subsequent calls to ``tf.routing()`` etc. work immediately.
         amount_usd: USD value of credits to buy. Must be 0.5 to 10000.
         private_key: 0x-prefixed Ethereum private key for signing the
-            USDC transfer. NEVER hardcode this; read from a secure env
-            var. The key is held in memory only for the duration of
-            this call.
+            quote message and the USDC transfer. NEVER hardcode this;
+            read from a secure env var. The key is held in memory only
+            for the duration of this call.
         rpc_url: Base mainnet RPC endpoint. Defaults to the free public
             Base RPC, which is fine for occasional use. For production
             use Alchemy or QuickNode.
@@ -91,11 +98,13 @@ def auto_purchase_credits(
     try:
         from web3 import Web3
         from eth_account import Account
+        from eth_account.messages import encode_defunct
     except ImportError as e:
         raise Web3NotInstalled(
             "web3 is not installed. Run: pip install 'tensorfeed[web3]'\n"
-            "Then retry, or use the manual flow: tf.buy_credits() + sign "
-            "the USDC tx yourself + tf.confirm(tx_hash=..., nonce=...)."
+            "Then retry, or use the manual flow: tf.buy_credits(..., "
+            "sign_message=...) + sign the USDC tx yourself + "
+            "tf.confirm(tx_hash=..., nonce=...)."
         ) from e
 
     rpc = rpc_url or DEFAULT_BASE_RPC
@@ -107,9 +116,19 @@ def auto_purchase_credits(
     sender = account.address
 
     # Step 1: TensorFeed-side quote, bound to this sender wallet so the
-    # post-2026-05-05 Tx-Sniper guard accepts the confirm. Must pass the
-    # exact lowercased address that will sign the on-chain transfer.
-    quote = tf.buy_credits(amount_usd=amount_usd, sender_wallet=sender.lower())
+    # confirm accepts the on-chain transfer. Must pass the exact
+    # lowercased address that will sign that transfer. The server only
+    # quotes for a message signed by that wallet, so sign it here with
+    # the same key (EIP-191 personal_sign).
+    def _sign_quote_message(message: str) -> str:
+        signed = account.sign_message(encode_defunct(text=message))
+        return "0x" + bytes(signed.signature).hex()
+
+    quote = tf.buy_credits(
+        amount_usd=amount_usd,
+        sender_wallet=sender.lower(),
+        sign_message=_sign_quote_message,
+    )
     receiving_wallet = quote["wallet"]
     memo = quote["memo"]
 

{tensorfeed-3.0.0 → tensorfeed-3.1.0}/tensorfeed.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tensorfeed
-Version: 3.0.0
+Version: 3.1.0
 Summary: Python SDK for the TensorFeed.ai API: AI news, status, model pricing, premium routing + history series + webhook watches, LangChain/CrewAI tool factories, agent payments via USDC on Base (optional web3 auto-send)
 Author-email: "TensorFeed.ai" <feedback@tensorfeed.ai>
 License-Expression: MIT
@@ -137,19 +137,29 @@ print(preview["recommendation"])
 ## Premium Tier (paid, USDC on Base)
 
 ```python
+import os
+from eth_account import Account                      # pip install eth-account
+from eth_account.messages import encode_defunct
 from tensorfeed import TensorFeed, PaymentRequired
 
 tf = TensorFeed()
+acct = Account.from_key(os.environ["TENSORFEED_PRIVATE_KEY"])  # NEVER hardcode
 
 # Step 1: get a 30-minute quote. sender_wallet is the Base wallet you will
 # send the USDC from (required); quote['wallet'] below is where you send it.
-quote = tf.buy_credits(amount_usd=1.00, sender_wallet="0xYourBaseWallet")
+# The server only quotes for a message signed by sender_wallet, so pass a
+# signer: the SDK builds the message and calls it once.
+quote = tf.buy_credits(
+    amount_usd=1.00,
+    sender_wallet=acct.address,
+    sign_message=lambda m: acct.sign_message(encode_defunct(text=m)).signature.hex(),
+)
 print(f"Send {quote['amount_usd']} USDC on Base to {quote['wallet']}")
 print(f"Memo: {quote['memo']} (expires in {quote['ttl_seconds']}s)")
 print(f"Will get: {quote['credits']} credits")
 
-# Step 2: send the USDC tx with your wallet
-# (auto-send via web3 is on the roadmap; for v1.1 you sign and send manually)
+# Step 2: send the USDC tx from sender_wallet
+# (or let tf.purchase_credits() below do steps 1 to 3 for you)
 
 # Step 3: confirm with the tx hash
 result = tf.confirm(tx_hash="0xYOUR_TX_HASH", nonce=quote["memo"])
@@ -206,6 +216,34 @@ tf.delete_watch(watch_id)         # remove when done
 print(tf.balance())
 ```
 
+### Signing the quote request
+
+`buy_credits()` requires proof that you control `sender_wallet`: an EIP-191 (`personal_sign`) signature by that wallet over this exact message, lines joined with `\n`:
+
+```
+I am requesting a TensorFeed credit quote for this wallet.
+
+wallet: <sender_wallet, 0x address>
+timestamp: <ISO 8601, within 10 minutes of now>
+nonce: <16 to 64 hex chars, fresh per quote>
+```
+
+Pass `sign_message=` (any callable that takes the message string and returns a 0x hex signature) and the SDK fills in the timestamp and a random nonce. If your signer lives elsewhere (a hardware wallet, a remote signing service), build the message yourself and pass both halves:
+
+```python
+from tensorfeed import build_quote_message
+
+message = build_quote_message(wallet)          # timestamp=now, nonce=random
+signature = my_remote_signer.personal_sign(message)
+quote = tf.buy_credits(
+    amount_usd=1.00, sender_wallet=wallet, message=message, signature=signature
+)
+```
+
+Each signed message is good for one quote. The server answers `sender_proof_expired` for a stale timestamp, `sender_proof_invalid` when the signature does not match the wallet, and `sender_proof_replayed` for a reused nonce. Calling `buy_credits()` with no signer and no message raises `ValueError` before any request is sent.
+
+Only an externally owned account (a plain private key) can produce this signature. Smart contract wallets cannot, and should pay per call through the x402 `X-PAYMENT` flow instead.
+
 ## Auto-Send (optional, web3 extra)
 
 The base SDK keeps you dependency-free, but if you want to skip the manual tx step, install with the `web3` extra:
@@ -214,7 +252,7 @@ The base SDK keeps you dependency-free, but if you want to skip the manual tx st
 pip install 'tensorfeed[web3]'
 ```
 
-Then `tf.purchase_credits()` quotes, signs, broadcasts, and confirms in one call:
+Then `tf.purchase_credits()` quotes, signs, broadcasts, and confirms in one call. The same key signs the quote request message and the USDC transfer:
 
 ```python
 import os
@@ -317,7 +355,8 @@ except TensorFeedError as e:
 | `tf.routing_preview(task=)` | Top-1 routing recommendation (5/day/IP) |
 | `tf.health()` | API health check |
 | `tf.payment_info()` | Wallet, pricing, supported payment flows |
-| `tf.buy_credits(amount_usd=, sender_wallet=)` | Generate a 30-min payment quote |
+| `tf.buy_credits(amount_usd=, sender_wallet=, sign_message=)` | Generate a 30-min payment quote (or pass `message=` and `signature=` instead of `sign_message=`) |
+| `build_quote_message(wallet, timestamp=, nonce=)` | Build the exact quote message `sender_wallet` signs |
 | `tf.confirm(tx_hash=, nonce=)` | Verify USDC tx, mint credit token |
 
 ### Token-required
@@ -367,7 +406,7 @@ Premium API responses are licensed for inference use only. Use of TensorFeed pre
 
 ## No refunds; credits do not expire
 
-All credit purchases are final and non-refundable per Section 17.5 of the [Terms](https://tensorfeed.ai/terms#premium). Credits never expire and are jointly redeemable on tensorfeed.ai and terminalfeed.io. The recommended pattern is to buy in small increments (for example, $1 USDC for 50 credits) until call volume is calibrated, then top up as needed.
+All credit purchases are final and non-refundable per Section 17.5 of the [Terms](https://tensorfeed.ai/terms#premium). Credits never expire while the token holds them, and a zero-balance token is deleted 30 days after its last use. The recommended pattern is to buy in small increments (for example, $1 USDC for 50 credits) until call volume is calibrated, then top up as needed.
 
 ## Sanctions
 

{tensorfeed-3.0.0 → tensorfeed-3.1.0}/tensorfeed.egg-info/SOURCES.txt

@@ -14,4 +14,5 @@ tensorfeed.egg-info/requires.txt
 tensorfeed.egg-info/top_level.txt
 tests/test_premium_auth_header.py
 tests/test_premium_tools.py
+tests/test_quote_proof.py
 tests/test_route_verdict.py

tensorfeed-3.1.0/tests/test_quote_proof.py

@@ -0,0 +1,283 @@
+"""Tests for the signed credit quote request (sender proof).
+
+/api/payment/buy-credits only issues a quote for a message signed by
+sender_wallet (EIP-191 personal_sign). The server parses the message
+strictly (exact header line, wallet / timestamp / nonce fields), so the
+SDK's builder has to match the template byte for byte, and buy_credits()
+has to post the same message it had signed.
+
+Network-free: urlopen is patched and every outgoing request is captured.
+The signature recovery tests need eth_account and skip without it.
+
+Run from sdk/python::
+
+    python -m pytest tests
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+import types
+import unittest
+from datetime import datetime, timezone
+from typing import Any
+from unittest import mock
+
+import tensorfeed
+from tensorfeed import TensorFeed, build_quote_message
+from tensorfeed import client as client_mod
+
+try:
+    from eth_account import Account
+    from eth_account.messages import encode_defunct
+
+    HAVE_ETH_ACCOUNT = True
+except ImportError:  # pragma: no cover (depends on the environment)
+    HAVE_ETH_ACCOUNT = False
+
+WALLET = "0x1111111111111111111111111111111111111111"
+FAKE_SIG = "0x" + "ab" * 65
+# Throwaway key built in code so no key-shaped literal sits in source.
+TEST_KEY = "0x" + "11" * 32
+
+QUOTE_RESPONSE = {
+    "ok": True,
+    "wallet": "0x549c82e6bfc54bdae9a2073744cbc2af5d1fc6d1",
+    "sender_wallet": WALLET,
+    "memo": "tfq_test",
+    "amount_usd": 1.0,
+    "credits": 50,
+    "ttl_seconds": 1800,
+}
+
+
+class _StubResponse:
+    def __init__(self, payload: dict[str, Any]) -> None:
+        self._body = json.dumps(payload).encode()
+
+    def read(self) -> bytes:
+        return self._body
+
+    def __enter__(self) -> "_StubResponse":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        return None
+
+
+def _capturing_urlopen(calls: list[dict[str, Any]], payload: dict[str, Any] | None = None):
+    def fake_urlopen(req, *a, **kw):
+        calls.append(
+            {
+                "url": req.full_url,
+                "method": req.get_method(),
+                "headers": {k.lower(): v for k, v in req.header_items()},
+                "body": json.loads(req.data.decode()) if req.data else None,
+            }
+        )
+        return _StubResponse(payload or QUOTE_RESPONSE)
+
+    return fake_urlopen
+
+
+class BuildQuoteMessage(unittest.TestCase):
+    def test_exact_output(self):
+        msg = build_quote_message(
+            WALLET, timestamp="2026-11-06T12:00:00.000Z", nonce="0123456789abcdef"
+        )
+        self.assertEqual(
+            msg,
+            "I am requesting a TensorFeed credit quote for this wallet.\n"
+            "\n"
+            "wallet: 0x1111111111111111111111111111111111111111\n"
+            "timestamp: 2026-11-06T12:00:00.000Z\n"
+            "nonce: 0123456789abcdef",
+        )
+        self.assertNotIn("\r", msg)
+        self.assertFalse(msg.endswith("\n"))
+
+    def test_defaults_use_utc_timestamp_and_fresh_hex_nonce(self):
+        before = datetime.now(timezone.utc)
+        lines = build_quote_message(WALLET).split("\n")
+        after = datetime.now(timezone.utc)
+
+        self.assertEqual(lines[0], client_mod.QUOTE_PROOF_HEADER)
+        self.assertEqual(lines[1], "")
+        self.assertEqual(lines[2], f"wallet: {WALLET}")
+
+        self.assertTrue(lines[3].startswith("timestamp: "))
+        ts = lines[3].removeprefix("timestamp: ")
+        # Millisecond precision with a Z suffix, the form Date.parse reads.
+        self.assertRegex(ts, r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$")
+        parsed = datetime.strptime(ts, "%Y-%m-%dT%H:%M:%S.%fZ").replace(tzinfo=timezone.utc)
+        # isoformat truncates to the millisecond, so compare at that precision.
+        self.assertLessEqual(before.replace(microsecond=before.microsecond // 1000 * 1000), parsed)
+        self.assertLessEqual(parsed, after)
+
+        self.assertTrue(lines[4].startswith("nonce: "))
+        nonce = lines[4].removeprefix("nonce: ")
+        self.assertRegex(nonce, r"^[0-9a-f]{16,64}$")
+        self.assertNotEqual(nonce, build_quote_message(WALLET).split("\n")[4].removeprefix("nonce: "))
+
+    def test_exported_from_package_root(self):
+        self.assertIn("build_quote_message", tensorfeed.__all__)
+        self.assertIs(tensorfeed.build_quote_message, client_mod.build_quote_message)
+
+
+class BuyCreditsSendsTheProof(unittest.TestCase):
+    def test_sign_message_posts_all_four_fields(self):
+        tf = TensorFeed()
+        calls: list[dict[str, Any]] = []
+        signed: list[str] = []
+
+        def signer(message: str) -> str:
+            signed.append(message)
+            return FAKE_SIG
+
+        with mock.patch.object(client_mod.urllib.request, "urlopen", _capturing_urlopen(calls)):
+            result = tf.buy_credits(amount_usd=1.0, sender_wallet=WALLET, sign_message=signer)
+
+        self.assertEqual(result, QUOTE_RESPONSE)
+        self.assertEqual(len(calls), 1)
+        self.assertEqual(len(signed), 1, "the signer must be called exactly once")
+        call = calls[0]
+        self.assertEqual(call["method"], "POST")
+        self.assertTrue(call["url"].endswith("/api/payment/buy-credits"))
+        self.assertEqual(
+            set(call["body"]), {"amount_usd", "sender_wallet", "message", "signature"}
+        )
+        self.assertEqual(call["body"]["amount_usd"], 1.0)
+        self.assertEqual(call["body"]["sender_wallet"], WALLET)
+        self.assertEqual(call["body"]["message"], signed[0])
+        self.assertEqual(call["body"]["signature"], FAKE_SIG)
+        self.assertEqual(signed[0].split("\n")[2], f"wallet: {WALLET}")
+        self.assertNotIn("authorization", call["headers"])
+
+    def test_signature_is_normalized_to_0x_hex(self):
+        tf = TensorFeed()
+        bare = "ab" * 65
+        for returned in (bare, bytes.fromhex(bare), "0x" + bare):
+            calls: list[dict[str, Any]] = []
+            with mock.patch.object(client_mod.urllib.request, "urlopen", _capturing_urlopen(calls)):
+                tf.buy_credits(
+                    amount_usd=1.0, sender_wallet=WALLET, sign_message=lambda m, r=returned: r
+                )
+            self.assertEqual(calls[0]["body"]["signature"], "0x" + bare)
+
+    def test_prebuilt_message_and_signature_are_posted_unchanged(self):
+        tf = TensorFeed()
+        msg = build_quote_message(WALLET)
+        calls: list[dict[str, Any]] = []
+        with mock.patch.object(client_mod.urllib.request, "urlopen", _capturing_urlopen(calls)):
+            tf.buy_credits(amount_usd=2.5, sender_wallet=WALLET, message=msg, signature=FAKE_SIG)
+        self.assertEqual(calls[0]["body"]["message"], msg)
+        self.assertEqual(calls[0]["body"]["signature"], FAKE_SIG)
+
+
+class BuyCreditsRefusesWithoutProof(unittest.TestCase):
+    def _assert_raises_without_http(self, **kwargs: Any) -> ValueError:
+        tf = TensorFeed()
+        urlopen = mock.MagicMock(side_effect=AssertionError("no HTTP call expected"))
+        with mock.patch.object(client_mod.urllib.request, "urlopen", urlopen):
+            with self.assertRaises(ValueError) as ctx:
+                tf.buy_credits(amount_usd=1.0, sender_wallet=WALLET, **kwargs)
+        urlopen.assert_not_called()
+        return ctx.exception
+
+    def test_neither_signer_nor_message(self):
+        exc = self._assert_raises_without_http()
+        text = str(exc)
+        self.assertIn("sign_message", text)
+        self.assertIn("signature", text)
+        self.assertIn("x402", text)
+
+    def test_message_without_signature(self):
+        self._assert_raises_without_http(message=build_quote_message(WALLET))
+
+    def test_signature_without_message(self):
+        self._assert_raises_without_http(signature=FAKE_SIG)
+
+    def test_signer_and_message_together(self):
+        self._assert_raises_without_http(
+            sign_message=lambda m: FAKE_SIG,
+            message=build_quote_message(WALLET),
+            signature=FAKE_SIG,
+        )
+
+
+@unittest.skipUnless(HAVE_ETH_ACCOUNT, "eth_account is not installed")
+class SignatureRecoversTheWallet(unittest.TestCase):
+    def test_eth_account_signer_recovers_sender_wallet(self):
+        acct = Account.from_key(TEST_KEY)
+        tf = TensorFeed()
+        calls: list[dict[str, Any]] = []
+
+        def signer(message: str) -> str:
+            return acct.sign_message(encode_defunct(text=message)).signature.hex()
+
+        with mock.patch.object(client_mod.urllib.request, "urlopen", _capturing_urlopen(calls)):
+            tf.buy_credits(amount_usd=1.0, sender_wallet=acct.address, sign_message=signer)
+
+        body = calls[0]["body"]
+        # Same shape check the server applies before recovery.
+        self.assertRegex(body["signature"], r"^0x[0-9a-fA-F]{130}$")
+        recovered = Account.recover_message(
+            encode_defunct(text=body["message"]), signature=body["signature"]
+        )
+        self.assertEqual(recovered, acct.address)
+        wallet_line = body["message"].split("\n")[2]
+        self.assertEqual(wallet_line, f"wallet: {acct.address}")
+
+    def test_auto_purchase_signs_the_quote_with_its_key(self):
+        """purchase_credits() must send a quote proof signed by its own key.
+
+        web3 is replaced with a stub (only the RPC connectivity check runs
+        before the quote), and the transport stops the flow right after
+        the buy-credits request, so nothing touches a chain.
+        """
+
+        class _StopAfterQuote(Exception):
+            pass
+
+        class _FakeWeb3:
+            class HTTPProvider:
+                def __init__(self, *a: object, **kw: object) -> None:
+                    pass
+
+            def __init__(self, provider: object) -> None:
+                pass
+
+            def is_connected(self) -> bool:
+                return True
+
+        fake_web3 = types.ModuleType("web3")
+        fake_web3.Web3 = _FakeWeb3  # type: ignore[attr-defined]
+
+        captured: list[dict[str, Any]] = []
+
+        def fake_urlopen(req, *a, **kw):
+            captured.append(json.loads(req.data.decode()))
+            raise _StopAfterQuote()
+
+        acct = Account.from_key(TEST_KEY)
+        tf = TensorFeed()
+        with mock.patch.dict(sys.modules, {"web3": fake_web3}):
+            with mock.patch.object(client_mod.urllib.request, "urlopen", fake_urlopen):
+                with self.assertRaises(_StopAfterQuote):
+                    tf.purchase_credits(amount_usd=1.0, private_key=TEST_KEY)
+
+        self.assertEqual(len(captured), 1)
+        body = captured[0]
+        self.assertEqual(body["sender_wallet"], acct.address.lower())
+        self.assertRegex(body["signature"], r"^0x[0-9a-fA-F]{130}$")
+        recovered = Account.recover_message(
+            encode_defunct(text=body["message"]), signature=body["signature"]
+        )
+        self.assertEqual(recovered.lower(), body["sender_wallet"])
+        self.assertTrue(re.match(r"^wallet: 0x[0-9a-f]{40}$", body["message"].split("\n")[2]))
+
+
+if __name__ == "__main__":
+    unittest.main()