allowance

balogh.adam@icloud.com · balogh.adam@icloud.com · commit 1aa8d8e7846d · 2026-03-26T22:50:22.000-04:00
diff --git a/README.md b/README.md
@@ -88,10 +88,10 @@ hub = og.ModelHub(email="you@example.com", password="...")
 
 ### OPG Token Approval
 
-Before making LLM requests, your wallet must approve OPG token spending via the [Permit2](https://github.com/Uniswap/permit2) protocol. Call this once (it's idempotent — no transaction is sent if the allowance already covers the requested amount):
+Before making LLM requests, your wallet must approve OPG token spending via the [Permit2](https://github.com/Uniswap/permit2) protocol. This only sends an on-chain transaction when the current allowance drops below the threshold:
 
 ```python
-llm.approve_opg(opg_amount=5)
+llm.ensure_opg_allowance(min_allowance=5)
 ```
 
 See [Payment Settlement](#payment-settlement) for details on settlement modes.
diff --git a/docs/CLAUDE_SDK_USERS.md b/docs/CLAUDE_SDK_USERS.md
@@ -21,8 +21,8 @@ import os
 # Create an LLM client
 llm = og.LLM(private_key=os.environ["OG_PRIVATE_KEY"])
 
-# One-time OPG token approval (idempotent — skips if allowance already sufficient)
-llm.approve_opg(opg_amount=0.1)
+# Ensure sufficient OPG allowance (only sends tx when below threshold)
+llm.ensure_opg_allowance(min_allowance=0.1)
 
 # LLM Chat (TEE-verified with x402 payments, async)
 result = await llm.chat(
diff --git a/docs/opengradient/client/index.md b/docs/opengradient/client/index.md
@@ -24,7 +24,7 @@ import opengradient as og
 
 # LLM inference (Base Sepolia OPG tokens)
 llm = og.LLM(private_key="0x...")
-llm.approve_opg(opg_amount=5)
+llm.ensure_opg_allowance(min_allowance=5)
 result = await llm.chat(model=og.TEE_LLM.CLAUDE_HAIKU_4_5, messages=[...])
 
 # On-chain model inference (OpenGradient testnet gas tokens)
diff --git a/docs/opengradient/client/llm.md b/docs/opengradient/client/llm.md
@@ -21,7 +21,7 @@ Supports both streaming and non-streaming responses.
 All request methods (``chat``, ``completion``) are async.
 
 Before making LLM requests, ensure your wallet has approved sufficient
-OPG tokens for Permit2 spending by calling ``ensure_opg_approval``.
+OPG tokens for Permit2 spending by calling ``ensure_opg_allowance``.
 This only sends an on-chain transaction when the current allowance is
 below the requested amount.
 
diff --git a/docs/opengradient/index.md b/docs/opengradient/index.md
@@ -35,7 +35,7 @@ import opengradient as og
 llm = og.LLM(private_key="0x...")
 
 # One-time OPG token approval (idempotent -- skips if allowance is sufficient)
-llm.approve_opg(opg_amount=5)
+llm.ensure_opg_allowance(min_allowance=5)
 
 # Chat with an LLM (TEE-verified)
 response = asyncio.run(llm.chat(
diff --git a/examples/langchain_react_agent.py b/examples/langchain_react_agent.py
@@ -17,9 +17,9 @@
 
 private_key = os.environ["OG_PRIVATE_KEY"]
 
-# One-time Permit2 approval for OPG spending (idempotent)
+# Ensure sufficient OPG allowance for Permit2 spending
 llm_client = og.LLM(private_key=private_key)
-llm_client.approve_opg(opg_amount=5)
+llm_client.ensure_opg_allowance(min_allowance=5)
 
 # Create the OpenGradient LangChain adapter
 llm = og.agents.langchain_adapter(
diff --git a/examples/llm_chat.py b/examples/llm_chat.py
@@ -10,7 +10,7 @@
 
 async def main():
     llm = og.LLM(private_key=os.environ.get("OG_PRIVATE_KEY"))
-    llm.approve_opg(opg_amount=0.1)
+    llm.ensure_opg_allowance(min_allowance=0.1)
 
     messages = [
         {"role": "user", "content": "What is the capital of France?"},
diff --git a/examples/llm_chat_streaming.py b/examples/llm_chat_streaming.py
@@ -6,7 +6,7 @@
 
 async def main():
     llm = og.LLM(private_key=os.environ.get("OG_PRIVATE_KEY"))
-    llm.approve_opg(opg_amount=0.1)
+    llm.ensure_opg_allowance(min_allowance=0.1)
 
     messages = [
         {"role": "user", "content": "What is Python?"},
diff --git a/examples/llm_tool_calling.py b/examples/llm_tool_calling.py
@@ -50,8 +50,8 @@ async def main():
         {"role": "user", "content": "What's the weather like in Dallas, Texas? Give me the temperature in fahrenheit."},
     ]
 
-    # One-time Permit2 approval for OPG spending (idempotent)
-    llm.approve_opg(opg_amount=0.1)
+    # Ensure sufficient OPG allowance for Permit2 spending
+    llm.ensure_opg_allowance(min_allowance=0.1)
 
     print("Testing Gemini tool calls...")
     print(f"Model: {og.TEE_LLM.GEMINI_2_5_FLASH_LITE}")
diff --git a/src/opengradient/__init__.py b/src/opengradient/__init__.py
@@ -26,7 +26,7 @@
 llm = og.LLM(private_key="0x...")
 
 # One-time OPG token approval (idempotent -- skips if allowance is sufficient)
-llm.approve_opg(opg_amount=5)
+llm.ensure_opg_allowance(min_allowance=5)
 
 # Chat with an LLM (TEE-verified)
 response = asyncio.run(llm.chat(
diff --git a/src/opengradient/client/__init__.py b/src/opengradient/client/__init__.py
@@ -17,7 +17,7 @@
 
 # LLM inference (Base Sepolia OPG tokens)
 llm = og.LLM(private_key="0x...")
-llm.approve_opg(opg_amount=5)
+llm.ensure_opg_allowance(min_allowance=5)
 result = await llm.chat(model=og.TEE_LLM.CLAUDE_HAIKU_4_5, messages=[...])
 
 # On-chain model inference (OpenGradient testnet gas tokens)
diff --git a/src/opengradient/client/llm.py b/src/opengradient/client/llm.py
@@ -58,7 +58,7 @@ class LLM:
     All request methods (``chat``, ``completion``) are async.
 
     Before making LLM requests, ensure your wallet has approved sufficient
-    OPG tokens for Permit2 spending by calling ``ensure_opg_approval``.
+    OPG tokens for Permit2 spending by calling ``ensure_opg_allowance``.
     This only sends an on-chain transaction when the current allowance is
     below the requested amount.
 
@@ -69,8 +69,8 @@ class LLM:
         # Via hardcoded URL (development / self-hosted)
         llm = og.LLM.from_url(private_key="0x...", llm_server_url="https://1.2.3.4")
 
-        # One-time approval (idempotent — skips if allowance is already sufficient)
-        llm.ensure_opg_approval(opg_amount=5)
+        # Ensure sufficient OPG allowance (only sends tx when below threshold)
+        llm.ensure_opg_allowance(min_allowance=5)
 
         result = await llm.chat(model=TEE_LLM.CLAUDE_HAIKU_4_5, messages=[...])
         result = await llm.completion(model=TEE_LLM.CLAUDE_HAIKU_4_5, prompt="Hello")
diff --git a/src/opengradient/client/opg_token.py b/src/opengradient/client/opg_token.py
@@ -188,7 +188,7 @@ def ensure_opg_allowance(
 
     Only sends an approval transaction when the current allowance drops
     below ``min_allowance``. When approval is needed, approves
-    ``approve_amount`` (defaults to ``10 * min_allowance``) to create a
+    ``approve_amount`` (defaults to ``2 * min_allowance``) to create a
     buffer that survives multiple service restarts without re-approving.
 
     Best for backend servers that call this on startup::
@@ -203,7 +203,7 @@ def ensure_opg_allowance(
             transaction is only sent when the current allowance is
             strictly below this value.
         approve_amount: The amount of OPG to approve when a transaction
-            is needed. Defaults to ``10 * min_allowance``. Must be
+            is needed. Defaults to ``2 * min_allowance``. Must be
             >= ``min_allowance``.
 
     Returns:
@@ -216,7 +216,7 @@ def ensure_opg_allowance(
         RuntimeError: If the approval transaction fails.
     """
     if approve_amount is None:
-        approve_amount = min_allowance * 10
+        approve_amount = min_allowance * 2
 
     if approve_amount < min_allowance:
         raise ValueError(f"approve_amount ({approve_amount}) must be >= min_allowance ({min_allowance})")
diff --git a/stresstest/llm.py b/stresstest/llm.py
@@ -13,7 +13,7 @@
 
 async def main(private_key: str):
     llm = og.LLM(private_key=private_key)
-    llm.approve_opg(opg_amount=0.1)
+    llm.ensure_opg_allowance(min_allowance=0.1)
 
     async def run_prompt(prompt: str):
         messages = [{"role": "user", "content": prompt}]
diff --git a/tutorials/01-verifiable-ai-agent.md b/tutorials/01-verifiable-ai-agent.md
@@ -36,19 +36,19 @@ export OG_PRIVATE_KEY="0x..."
 ## Step 1: Initialize and Create the LangChain Adapter
 
 Before making any LLM calls, you need to approve OPG token spending for the x402
-payment protocol. The `approve_opg` method checks your wallet's current
-Permit2 allowance and only sends an on-chain transaction if the allowance is below
-the requested amount -- so it's safe to call every time.
+payment protocol. The `ensure_opg_allowance` method checks your wallet's current
+Permit2 allowance and only sends an on-chain transaction if the allowance drops
+below the threshold -- so it's safe to call every time.
 
 ```python
 import os
 import opengradient as og
 
 private_key = os.environ["OG_PRIVATE_KEY"]
 
-# Approve OPG spending for x402 payments (idempotent -- skips if already approved).
+# Ensure sufficient OPG allowance for x402 payments (only sends tx when below threshold).
 llm_client = og.LLM(private_key=private_key)
-llm_client.approve_opg(opg_amount=5)
+llm_client.ensure_opg_allowance(min_allowance=5)
 
 # Create the LangChain chat model backed by OpenGradient TEE.
 # The adapter creates its own internal LLM client. The approval above applies
@@ -287,9 +287,9 @@ SAMPLE_PRICES = {
 # ── Clients ───────────────────────────────────────────────────────────────
 private_key = os.environ["OG_PRIVATE_KEY"]
 
-# Approve OPG spending for x402 payments (idempotent -- skips if already approved).
+# Ensure sufficient OPG allowance for x402 payments (only sends tx when below threshold).
 llm_client = og.LLM(private_key=private_key)
-llm_client.approve_opg(opg_amount=5)
+llm_client.ensure_opg_allowance(min_allowance=5)
 
 # Alpha client for on-chain model inference.
 alpha = og.Alpha(private_key=private_key)
diff --git a/tutorials/02-streaming-multi-provider.md b/tutorials/02-streaming-multi-provider.md
@@ -35,9 +35,9 @@ export OG_PRIVATE_KEY="0x..."
 ## Step 1: Basic Non-Streaming Chat
 
 Start with the simplest possible call -- send a message and get a response. Before
-making any LLM calls, approve OPG token spending for the x402 payment protocol using
-`approve_opg`. This is idempotent -- it checks the current Permit2 allowance
-and only sends a transaction if the allowance is below the requested amount.
+making any LLM calls, ensure sufficient OPG token allowance for the x402 payment
+protocol using `ensure_opg_allowance`. This only sends a transaction when the
+current allowance drops below the threshold.
 
 ```python
 import asyncio
@@ -52,8 +52,8 @@ if not private_key:
 
 llm = og.LLM(private_key=private_key)
 
-# Approve OPG spending for x402 payments (one-time, idempotent).
-llm.approve_opg(opg_amount=5)
+# Ensure sufficient OPG allowance for x402 payments (only sends tx when below threshold).
+llm.ensure_opg_allowance(min_allowance=5)
 
 async def main():
     result = await llm.chat(
@@ -273,8 +273,8 @@ if not private_key:
 
 llm = og.LLM(private_key=private_key)
 
-# Approve OPG spending for x402 payments (idempotent -- skips if already approved).
-llm.approve_opg(opg_amount=5)
+# Ensure sufficient OPG allowance for x402 payments (only sends tx when below threshold).
+llm.ensure_opg_allowance(min_allowance=5)
 
 PROMPT = "Explain what a Trusted Execution Environment is in two sentences."
 
diff --git a/tutorials/03-verified-tool-calling.md b/tutorials/03-verified-tool-calling.md
@@ -35,10 +35,9 @@ export OG_PRIVATE_KEY="0x..."
 
 ## Step 1: Initialize the Client
 
-Before making any LLM calls, approve OPG token spending for the x402 payment
-protocol. The `approve_opg` method is idempotent -- it checks the current
-Permit2 allowance and only sends a transaction if the allowance is below the
-requested amount.
+Before making any LLM calls, ensure sufficient OPG token allowance for the x402
+payment protocol. The `ensure_opg_allowance` method only sends a transaction when
+the current allowance drops below the threshold.
 
 ```python
 import json
@@ -54,8 +53,8 @@ if not private_key:
 
 llm = og.LLM(private_key=private_key)
 
-# Approve OPG spending for x402 payments (one-time, idempotent).
-llm.approve_opg(opg_amount=5)
+# Ensure sufficient OPG allowance for x402 payments (only sends tx when below threshold).
+llm.ensure_opg_allowance(min_allowance=5)
 ```
 
 ## Step 2: Define Local Tool Implementations
@@ -317,8 +316,8 @@ if not private_key:
 
 llm = og.LLM(private_key=private_key)
 
-# Approve OPG spending for x402 payments (idempotent -- skips if already approved).
-llm.approve_opg(opg_amount=5)
+# Ensure sufficient OPG allowance for x402 payments (only sends tx when below threshold).
+llm.ensure_opg_allowance(min_allowance=5)
 
 # ── Mock data ─────────────────────────────────────────────────────────────
 PORTFOLIO      = {"ETH": {"amount": 5.0, "avg_cost": 1950.00},

Original file line number	Diff line number	Diff line change
`@@ -50,8 +50,8 @@ async def main():`
`50`	`50`	`{"role": "user", "content": "What's the weather like in Dallas, Texas? Give me the temperature in fahrenheit."},`
`51`	`51`	`]`
`52`	`52`
`53`		`- # One-time Permit2 approval for OPG spending (idempotent)`
`54`		`- llm.approve_opg(opg_amount=0.1)`
	`53`	`+ # Ensure sufficient OPG allowance for Permit2 spending`
	`54`	`+ llm.ensure_opg_allowance(min_allowance=0.1)`
`55`	`55`
`56`	`56`	`print("Testing Gemini tool calls...")`
`57`	`57`	`print(f"Model: {og.TEE_LLM.GEMINI_2_5_FLASH_LITE}")`