add gas free

Author: jizhen181-dot

docs/x402/core-concepts/network-and-token-support.md

@@ -100,29 +100,39 @@ When configuring an `HTTP 402` payment request on the server side, you must expl
 
 ## Payment Scheme
 
-x402 supports two payment schemes: `exact_permit` and `exact`.
+x402 supports three payment schemes: `exact_permit`, `exact`, and `exact_gasfree`.
 
 ### `exact_permit` Scheme
 
 The `exact_permit` scheme transfers tokens via the `PaymentPermit` contract, suitable for:
 
-- **Pay-per-use APIs** (e.g., LLM token generation, image generation services)  
-- **Metered resources** (cloud compute time, storage usage, bandwidth consumption)  
-- **Dynamic pricing services** based on actual usage  
+- **Pay-per-use APIs** (e.g., LLM token generation, image generation services)
+- **Metered resources** (cloud compute time, storage usage, bandwidth consumption)
+- **Dynamic pricing services** based on actual usage
 
 ### `exact` Scheme
 
 The `exact` scheme is for tokens that natively support `transferWithAuthorization`. It does not require the `PaymentPermit` contract.
 
+### `exact_gasfree` Scheme
+
+The `exact_gasfree` scheme is a TRON-specific payment mechanism that allows users to pay with USDT/USDD **without holding TRX for gas fees**. Settlement is handled via the official GasFree Proxy through the BankOfAI facilitator endpoint.
+
+Key characteristics:
+
+- **Zero gas cost for buyers**: Buyers do not need to hold TRX — gas is covered by the GasFree infrastructure
+- **No API keys required**: All GasFree API calls route through the BankOfAI proxy at `https://facilitator.bankofai.io/{mainnet,nile}`, so clients do not need to configure `GASFREE_API_KEY` or `GASFREE_API_SECRET`
+- **TRON only**: Available on `tron:mainnet` and `tron:nile`
+
 ### How Payment Schemes Work
 
-1. **Authorize**  
+1. **Authorize**
    The client signs a message authorizing a **maximum amount**.
 
-2. **Execute**  
+2. **Execute**
    The server performs the requested task and calculates the **actual cost**.
 
-3. **Settle**  
+3. **Settle**
    The Facilitator submits the on-chain transaction based on the actual cost.
 
 ---
@@ -154,7 +164,7 @@ You may deploy your own Facilitator node to gain full control over payment verif
 | **Networks**   | `tron:mainnet`, `tron:shasta`, `tron:nile`, `eip155:56`, `eip155:97` |
 | **Token Standard** | TRC-20 (built-in USDT & USDD support), BEP-20 |
 | **Signing Mechanism** | Typed data signing |
-| **Payment Scheme** | `exact_permit`, `exact` |
+| **Payment Scheme** | `exact_permit`, `exact`, `exact_gasfree` (TRON only) |
 
 ---
 

docs/x402/faq.md

@@ -67,7 +67,10 @@ Common pricing models include:
 
 #### What payment schemes does x402 support?
 
-x402 supports `exact_permit` and `exact` payment schemes. Both allow the client to authorize a **maximum payment amount**, and the server to settle the **actual cost incurred** (up to the authorized limit). This is ideal for **metered billing**, **LLM token usage**, and similar use cases.
+x402 supports three payment schemes:
+
+- **`exact_permit`** and **`exact`**: Both allow the client to authorize a **maximum payment amount**, and the server to settle the **actual cost incurred** (up to the authorized limit). This is ideal for **metered billing**, **LLM token usage**, and similar use cases.
+- **`exact_gasfree`** (TRON only): Allows buyers to pay with USDT/USDD without holding TRX for gas. All GasFree API calls are routed through the BankOfAI proxy — no API keys required on the client side.
 
 ---
 

docs/x402/getting-started/quickstart-for-agent.md

@@ -60,10 +60,10 @@ Set your agent wallet's private key as environment variables so the x402-payment
 
 ```bash
 export TRON_PRIVATE_KEY="your_agent_wallet_private_key_here"
-export TRON_GRID_API_KEY="your_trongrid_api_key_here"  # Recommended to avoid RPC rate limits
+export TRON_GRID_API_KEY="your_trongrid_api_key_here"  # Recommended for production workloads
 ```
 
-> 💡 **How to get a TronGrid API Key:** Register for free at [TronGrid](https://www.trongrid.io/), create an API Key, and paste it above. You can leave this blank during testnet testing, but it is required for mainnet.
+> 💡 **How to get a TronGrid API Key:** Register for free at [TronGrid](https://www.trongrid.io/), create an API Key, and paste it above. When `TRON_GRID_API_KEY` is not set, mainnet RPC calls are automatically routed to a BankOfAI-operated fallback endpoint. Setting this key is recommended for production workloads to ensure optimal performance.
 
 </TabItem>
 <TabItem value="BSC" label="BSC">
@@ -194,7 +194,7 @@ Before deploying your agent to production, make sure to review the following:
 | Agent doesn't initiate payment, errors immediately | Skill not installed correctly | Re-run the installation command in Step 2 |
 | `Private key not found` or signing fails | Environment variable not set or misconfigured | Re-run Step 1, and make sure you run the agent **in the same terminal session** |
 | Insufficient balance error | No test tokens in the agent wallet | Go back to Prerequisites and claim test tokens from the faucet |
-| Request times out | Network issue or RPC rate limiting | Configure `TRON_GRID_API_KEY` to avoid rate limits |
+| Request times out | Network issue or RPC rate limiting | Configure `TRON_GRID_API_KEY` for better performance (a fallback endpoint is used automatically when not set) |
 | Agent accesses successfully but balance doesn't change | May have accessed a free endpoint | Confirm the URL path is `/protected-nile`, not another path |
 
 ---

docs/x402/getting-started/quickstart-for-human.md

@@ -212,7 +212,10 @@ import httpx
 
 from bankofai.x402.clients import X402Client, X402HttpClient, SufficientBalancePolicy
 from bankofai.x402.mechanisms.tron.exact_permit import ExactPermitTronClientMechanism
+from bankofai.x402.mechanisms.tron.exact_gasfree.client import ExactGasFreeClientMechanism
 from bankofai.x402.signers.client import TronClientSigner
+from bankofai.x402.utils.gasfree import GasFreeAPIClient
+from bankofai.x402.config import NetworkConfig
 
 
 # ========== Configuration ==========
@@ -221,14 +224,21 @@ from bankofai.x402.signers.client import TronClientSigner
 SERVER_URL = "https://x402-demo.bankofai.io/protected-nile"
 # ====================================
 
+# GasFree API clients (routed through BankOfAI proxy — no API keys needed)
+gasfree_clients = {
+    "tron:nile": GasFreeAPIClient(NetworkConfig.get_gasfree_api_base_url("tron:nile")),
+    "tron:mainnet": GasFreeAPIClient(NetworkConfig.get_gasfree_api_base_url("tron:mainnet")),
+}
+
 
 async def main():
     # Initialize signer with your private key (network is resolved dynamically)
     signer = TronClientSigner.from_private_key(os.getenv("TRON_PRIVATE_KEY"))
 
-    # Create x402 client and register the payment mechanism and balance policy
+    # Create x402 client and register payment mechanisms and balance policy
     x402_client = X402Client()
     x402_client.register("tron:*", ExactPermitTronClientMechanism(signer))
+    x402_client.register("tron:*", ExactGasFreeClientMechanism(signer, clients=gasfree_clients))
     x402_client.register_policy(SufficientBalancePolicy)
 
     async with httpx.AsyncClient(timeout=60.0) as http_client:
@@ -264,8 +274,9 @@ Response: {"data": "This is premium content!"}
 import 'dotenv/config'
 import {
   X402Client, X402FetchClient,
-  ExactPermitTronClientMechanism, TronClientSigner,
-  SufficientBalancePolicy,
+  ExactPermitTronClientMechanism, ExactGasFreeClientMechanism,
+  TronClientSigner, SufficientBalancePolicy,
+  GasFreeAPIClient, getGasFreeApiBaseUrl,
 } from '@bankofai/x402'
 
 const TRON_PRIVATE_KEY = process.env.TRON_PRIVATE_KEY!
@@ -280,9 +291,13 @@ async function main(): Promise<void> {
   // Initialize signer with your private key
   const signer = new TronClientSigner(TRON_PRIVATE_KEY)
 
-  // Create x402 client and register the payment mechanism and balance policy
+  // Create x402 client and register payment mechanisms and balance policy
   const x402 = new X402Client()
   x402.register('tron:*', new ExactPermitTronClientMechanism(signer))
+  x402.register('tron:*', new ExactGasFreeClientMechanism(signer, {
+    'tron:nile': new GasFreeAPIClient(getGasFreeApiBaseUrl('tron:nile')),
+    'tron:mainnet': new GasFreeAPIClient(getGasFreeApiBaseUrl('tron:mainnet')),
+  }))
   x402.registerPolicy(SufficientBalancePolicy)
 
   const client = new X402FetchClient(x402)

docs/x402/getting-started/quickstart-for-sellers.md

@@ -396,7 +396,7 @@ Open the `.env` file in the `x402-demo` directory with a text editor and fill in
 # How to get it: TronLink → Settings → Account Management → Export Private Key
 TRON_PRIVATE_KEY=paste_your_facilitator_private_key_here
 
-# TronGrid API Key (required for mainnet, can be left blank for testnet)
+# TronGrid API Key (recommended for production; when not set, a BankOfAI fallback endpoint is used automatically)
 # Apply at: https://www.trongrid.io/
 TRON_GRID_API_KEY=
 ```
@@ -545,7 +545,7 @@ Modify the `network` parameter in the `@x402_protected` decorator in `server.py`
 <Tabs>
 <TabItem value="TRON" label="TRON">
 
-1. **Apply for a TronGrid API Key**: go to [TronGrid](https://www.trongrid.io/) to register and create an API Key, then fill it into the `TRON_GRID_API_KEY` field in `.env` (required for mainnet)
+1. **Apply for a TronGrid API Key**: go to [TronGrid](https://www.trongrid.io/) to register and create an API Key, then fill it into the `TRON_GRID_API_KEY` field in `.env` (recommended for production; a BankOfAI fallback endpoint is used automatically when not set)
 2. **Replace the private key**: update the private key in `.env` to the mainnet Facilitator wallet's private key
 3. **Fund the fee wallet**: transfer sufficient real TRX to the Facilitator mainnet wallet (to pay Energy and Bandwidth fees)
 4. **Update the network config**: change the network configuration in the Facilitator code to `NetworkConfig.TRON_MAINNET`

docs/x402/index.md

@@ -9,7 +9,7 @@ description: >-
 
 x402 is an open blockchain payment standard built on the HTTP `402 Payment Required` status code. It enables web services to charge for APIs or content through a “pay-before-response” mechanism — without relying on traditional account systems or session management.  
 
-x402 currently supports the TRON and BSC networks, with plans to expand to a broader multi-chain ecosystem in the future.
+x402 currently supports the **TRON** and **BSC** networks, with plans to expand to a broader multi-chain ecosystem in the future.
 
 **Interested in contributing to the documentation?**  
 Feel free to submit a PR to the [GitHub repository](https://github.com/BofAI/docs). Our only principle is to maintain neutrality — aside from essential resource links, please avoid promotional or branded content.

docs/x402/sdk-features.md

@@ -46,6 +46,7 @@ This page tracks the implementation progress and feature support status of the x
 | exact_permit/bsc | ✅ | ✅ |
 | exact/tron | ✅ | ✅ |
 | exact/bsc | ✅ | ✅ |
+| exact_gasfree/tron | ✅ | ✅ |
 
 ---
 
@@ -69,6 +70,8 @@ This page tracks the implementation progress and feature support status of the x
 | Allowance check | ✅ | ✅ |
 | Signing (TRON) | ✅ | ✅ |
 | Signing (EVM) | ✅ | ✅ |
+| SufficientBalancePolicy | ✅ | ✅ |
+| GasFree (zero-gas TRON payments) | ✅ | ✅ |
 
 ---
 
@@ -101,6 +104,7 @@ This page tracks the implementation progress and feature support status of the x
 | Token | Python | TypeScript |
 |--------|--------|------------|
 | USDT (TRC-20) | ✅ | ✅ |
+| USDD (TRC-20) | ✅ | ✅ |
 | Custom TRC-20 | ✅ | ✅ |
 | USDT (BEP-20) | ✅ | ✅ |
 | Custom BEP-20 | ✅ | ✅ |

i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/core-concepts/network-and-token-support.md

@@ -40,6 +40,7 @@ x402 专为区块链生态设计，实现了原生的链上支付验证与结算
 | **TRON Shasta**  | **Testnet**   | **备用测试网**：长期稳定的测试环境。   |
 | **BSC Mainnet**        | **Mainnet**   | **生产网络**：用于处理真实价值资产。   |
 | **BSC Testnet**         | **Testnet**   | **推荐测试网**：BSC 首选的开发与调试环境。 |
+
 ### 支持的代币
 
 x402 协议全面支持 **TRC-20/BEP-20** 标准代币，并默认将 **USDT** 和 **USDD** 作为主要结算货币。
@@ -81,7 +82,7 @@ x402 采用类型化数据签名来处理所有支付相关的签名授权。
 
 ### 支付方案
 
-x402 支持两种支付方案：`exact_permit` 和 `exact`。
+x402 支持三种支付方案：`exact_permit`、`exact` 和 `exact_gasfree`。
 
 #### `exact_permit` 方案
 
@@ -95,6 +96,16 @@ x402 支持两种支付方案：`exact_permit` 和 `exact`。
 
 `exact` 方案适用于原生支持 `transferWithAuthorization` 的代币，无需 `PaymentPermit` 合约。
 
+#### `exact_gasfree` 方案
+
+`exact_gasfree` 是 TRON 专属的支付机制，允许用户使用 USDT/USDD 付款而**无需持有 TRX 来支付 gas 费用**。结算通过 BankOfAI Facilitator 端点的官方 GasFree 代理完成。
+
+核心特性：
+
+- **买家零 gas 成本**：买家无需持有 TRX，gas 费用由 GasFree 基础设施承担
+- **无需 API 密钥**：所有 GasFree API 调用通过 BankOfAI 代理路由至 `https://facilitator.bankofai.io/{mainnet,nile}`，客户端无需配置 `GASFREE_API_KEY` 或 `GASFREE_API_SECRET`
+- **仅限 TRON**：支持 `tron:mainnet` 和 `tron:nile`
+
 #### 工作原理
 
 1.  **预授权 (Authorize)**：客户端签署消息，授权支付**最大金额** (Max Amount)。
@@ -123,10 +134,10 @@ Facilitator 作为协议的中间件，承担以下核心职责：
 
 | 核心组件     | TRON/BSC 实现详情                              |
 | :----------- | :----------------------------------------- |
-| **网络环境** | `tron:mainnet`, `tron:shasta`, `tron:nile`, `eip155:56`, `eip155:97`|
+| **网络环境** | `tron:mainnet`, `tron:shasta`, `tron:nile`, `eip155:56`, `eip155:97` |
 | **代币标准** | TRC-20 代币（默认内置 USDT 和 USDD 支持）,BEP-20 代币 |
 | **签名机制** | 类型化数据签名                     |
-| **支付方案** | `exact_permit`, `exact`                    |
+| **支付方案** | `exact_permit`, `exact`, `exact_gasfree`（仅限 TRON） |
 
 ### 添加自定义代币
 

i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/faq.md

@@ -59,7 +59,10 @@ x402 目前提供以下 SDK：
 
 #### x402 支持哪些支付方案？
 
-x402 支持 `exact_permit` 和 `exact` 两种支付方案。两种方案均允许客户端授权一个**最高支付金额**，服务端结算**实际产生的费用**（不超过授权上限）。此方案非常适用于**按量计费 (Metered Billing)**、**LLM Token 消耗**等场景。
+x402 支持三种支付方案：
+
+- **`exact_permit`** 和 **`exact`**：两种方案均允许客户端授权一个**最高支付金额**，服务端结算**实际产生的费用**（不超过授权上限）。此方案非常适用于**按量计费 (Metered Billing)**、**LLM Token 消耗**等场景。
+- **`exact_gasfree`**（仅限 TRON）：允许买家使用 USDT/USDD 付款而无需持有 TRX 来支付 gas。所有 GasFree API 调用通过 BankOfAI 代理路由，客户端无需配置 API 密钥。
 
 ### 资产、网络及费用
 

i18n/zh-Hans/docusaurus-plugin-content-docs/current/x402/getting-started/quickstart-for-agent.md

@@ -60,10 +60,10 @@ x402 专为 Agentic Web 设计。通过安装 `x402-payment` 技能，AI 代理
 
 ```bash
 export TRON_PRIVATE_KEY="在此填入代理钱包私钥"
-export TRON_GRID_API_KEY="在此填入TronGrid API Key"  # 推荐配置，防止 RPC 限速
+export TRON_GRID_API_KEY="在此填入TronGrid API Key"  # 生产环境推荐配置
 ```
 
-> 💡 **如何获取 TronGrid API Key：** 前往 [TronGrid 官网](https://www.trongrid.io/) 免费注册，创建 API Key 后粘贴到上方。测试网阶段可暂时留空，但主网阶段必须配置。
+> 💡 **如何获取 TronGrid API Key：** 前往 [TronGrid 官网](https://www.trongrid.io/) 免费注册，创建 API Key 后粘贴到上方。未配置 `TRON_GRID_API_KEY` 时，主网 RPC 调用会自动路由至 BankOfAI 运营的备用 RPC 端点。生产环境建议配置此 Key 以获得最佳性能。
 
 </TabItem>
 <TabItem value="BSC" label="BSC">
@@ -194,7 +194,7 @@ https://x402-demo.bankofai.io/protected-nile
 | 代理未发起付款，直接报错 | 技能未正确安装 | 重新执行第二步的安装命令 |
 | `私钥未找到` 或签名失败 | 环境变量未配置或配置错误 | 重新执行第一步，在**同一终端**中运行代理 |
 | 余额不足错误 | 测试钱包中没有测试代币 | 回到前置准备，从水龙头领取测试代币 |
-| 请求超时 | 网络问题或 RPC 限速 | 配置 `TRON_GRID_API_KEY` 以避免限速 |
+| 请求超时 | 网络问题或 RPC 限速 | 配置 `TRON_GRID_API_KEY` 以获得更好的性能（未配置时会自动使用备用 RPC 端点） |
 | 代理访问成功但余额没有变化 | 可能访问的是免费接口 | 确认 URL 是 `/protected-nile` 而非其他路径 |
 
 ---