tron-x402-payment

# x402 Payment Protocol for TRON Agents Invoke x402-enabled AI agent endpoints with automatic TRC20 token payments on TRON. Currently recommended tokens: **USDT**, **USDD**. ## Quick Start The tool `x402_tron_invoke` is implemented by the compiled script `dist/x402_tron_invoke.js`. The script is pre-built and ready to run. You can execute it directly from the command line: ```bash # v2 Invoke node dist/x402_tron_invoke.js --url https://api.example.com --entrypoint chat --input '{"prompt": "hi"}' # Direct/Discovery node dist/x402_tron_invoke.js --url https://api.example.com/.well-known/agent.json ``` --- ## How It Works The `x402_tron_invoke` tool: 1. Constructs the endpoint URL: - If `entrypoint` is provided: `{url}/entrypoints/{entrypoint}/invoke` (v2) - Otherwise: Uses `{url}` as-is (v1 / Discovery) 2. Makes a request (POST for v2, GET default for v1) 3. If 402 Payment Required is returned: - Parses payment requirements - Checks wallet balance and allowance - Performs an **infinite approval** if allowance is insufficient - Signs the payment permit (EIP-712 / TRON Typed Data) - Retries the request with `X-PAYMENT` header 4. Returns the response ## Prerequisites - **Wallet**: A TRON private key must be available. The skill automatically looks for it in: 1. `TRON_PRIVATE_KEY` environment variable. 2. `~/.mcporter/mcporter.json` (AIBank standard). 3. `x402-config.json` in the current/home directory. - **Tokens**: Wallet needs USDT/USDD and some TRX for gas. - **TronGrid API Key**: Required for **Mainnet** to avoid rate limits (`TRON_GRID_API_KEY`). --- ## Tool Reference ### x402_tron_invoke Invokes an HTTP endpoint with automatic payment handling. **Modes:** 1. **v2 Agent Invoke** (Recommended): Provide `url` (Base URL) + `entrypoint`. * Constructs: `{url}/entrypoints/{entrypoint}/invoke` * Wraps input: `{"input": <input>}` * Method: `POST` 2. **v1 / Direct / Discovery**: Provide `url` (Full URL) without `entrypoint`. * Uses the URL as-is. * Method: `GET` (default) or specified via `method`. * **Agent Advice**: Use this mode for discovery. If `url` returns 404, try appending `/.well-known/agent.json` or `/entrypoints`. 3. **Status Check**: Provide `--check` or `--status`. * Verifies if `TRON_PRIVATE_KEY` is correctly configured and outputs the associated wallet address. * Checks if `TRON_GRID_API_KEY` is present (Required for Mainnet). * **Agent Advice**: ALWAYS use this instead of `env` or `echo $TRON_PRIVATE_KEY`. | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `url` | string | Yes* | Base URL (v2) or Full URL (v1/Discovery). *Not required for `--check`. | | `entrypoint` | string | No | Entrypoint name. Required for v2 Invoke. | | `input` | object | No | Input data. | | `method` | string | No | HTTP method. Default: `POST` (v2), `GET` (Direct). | | `network` | string | No | `mainnet`, `nile`, `shasta` (Default: `nile`). | | `check` | boolean | No | Verify wallet configuration and output address. | ### Example: Chat with Agent (v2 Invoke) ```bash node dist/x402_tron_invoke.js --url https://api.example.com --entrypoint chat --input '{"prompt": "Tell me a joke"}' ``` *(Sends `POST https://api.example.com/entrypoints/chat/invoke`)* ### Example: Agent Discovery (Direct) 1. **Manifest**: Fetch agent metadata. ```bash node dist/x402_tron_invoke.js --url https://api.example.com/.well-known/agent.json ``` 2. **List Entrypoints**: List available functions. ```bash node dist/x402_tron_invoke.js --url https://api.example.com/entrypoints ``` Each entrypoint typically returns: - **Path**: `/entrypoints/{name}/invoke` - **Pricing**: Cost in tokens (e.g., 1000 units) - **Network**: Usually `nile` or `mainnet` - **Input Schema**: Expected JSON format for the `input` parameter ### Example: Raw URL (Legacy) ```bash node dist/x402_tron_invoke.js --url https://api.example.com/chat --method POST --input '{"prompt": "Tell me a joke"}' ``` --- ## Cost Reference (USDT/USDD) | Token | Network | Contract Address | Decimals | |-------|---------|------------------|----------| | USDT | Mainnet | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` | 6 | | USDT | Nile | `TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf` | 6 | | USDT | Shasta | `TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs` | 6 | | USDD | Mainnet | `TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz` | 18 | | USDD | Nile | `TGjgvdTWWrybVLaVeFqSyVqJQWjxqRYbaK` | 18 | | Amount (raw) | Value (USDT, 6 dec) | Typical Use | |--------------|---------------------|-------------| | 1000 | $0.001 | Single API call | | 5000 | $0.005 | Multiple results | | 10000 | $0.01 | Premium request | | 1000000 | $1.00 | Large batch | --- ## Understanding 402 Responses When payment is required, agents return: ```json { "error": "X-PAYMENT header is required", "accepts": [{ "scheme": "exact", "network": "nile", "maxAmountRequired": "1000", "payTo": "T...", "asset": "T..." }], "x402Version": 1 } ``` The tool handles this automatically. --- ## Supported Tokens This tool supports TRC20 tokens compatible with the x402 protocol. **Recommended:** - **USDT** (Tether) - **USDD** (Decentralized USD) ## Security Rules for Agents - **No Private Key Output**: The Agent MUST NOT print, echo, or output the `TRON_PRIVATE_KEY` or any other signing secret to the dialogue context. - **Internal Loading Only**: The Agent should rely on the skill or underlying scripts to load the key internally. - **No Export Commands**: The Agent MUST NOT execute shell commands that contain the private key as a literal string. - **Sanitized Logs**: Ensure that logs or error messages do not leak the key. - **Silent Environment Checks**: If you need to verify if an environment variable is set, use a "Silent Check". - **Correct**: `[[ -n $TRON_PRIVATE_KEY ]] && echo "Configured" || echo "Missing"` - **Forbidden**: `echo $TRON_PRIVATE_KEY`, `env`, `printenv`, `set`, `export`. - **Disabled Commands List**: Do NOT use the following commands in any environment containing sensitive keys: - `env` / `printenv` - `echo $VARIABLE_NAME` - `set` / `export` (without arguments) - **Use the Check Tool**: To safely verify wallet status, use `node dist/x402_tron_invoke.js --check`. ### ❌ Negative Example (CRITICAL FAILURE) > "I will check your private key now: `echo $TRON_PRIVATE_KEY`" -> **STOP! This leaks the secret to the logs and UI.** ### ✅ Positive Example > "I will verify the wallet configuration: `node dist/x402_tron_invoke.js --check`" -> **SAFE. Only the public address is shown.** ## Troubleshooting ### "Private key not found" Ensure the `TRON_PRIVATE_KEY` environment variable is set or a valid `x402-config.json` exists in the expected locations. ### "Insufficient Allowance" The tool will attempt to broadcast an **infinite approve** transaction. This requires TRX for gas. Ensure your wallet has TRX. ### "Transaction Failed" Check if you have enough Token balance (USDT/USDD) and TRX for gas. --- ## Binary and Image Handling If the endpoint returns an image (Content-Type: `image/*`) or binary data (`application/octet-stream`): 1. The data is automatically saved to a temporary file (e.g., `/tmp/x402_image_...`). 2. The tool returns a JSON object with: - `file_path`: Path to the temporary file. - `content_type`: The MIME type of the content. - `bytes`: File size in bytes. 3. **Important**: The Agent is responsible for deleting the temporary file after it has been used. --- ## Network Reference | Network | Chain ID | CAIP-2 | USDT Contract | USDD Contract | |---------|----------|--------|---------------|---------------| | TRON Mainnet | 0x2b6653dc | `eip155:728126428`, `tron:mainnet` | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` | `TXDk8mbtRbXeYuMNS83CfKPaYYT8XWv9Hz` | | TRON Nile | 0xcd8690dc | `eip155:3448148188`, `tron:nile` | `TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf` | `TGjgvdTWWrybVLaVeFqSyVqJQWjxqRYbaK` | | TRON Shasta | 0x94a9059e | `eip155:2494104990`, `tron:shasta` | `TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs` | - |