x402_payment_tron

# x402 Payment Protocol for TRON Agents

Invoke x402-enabled AI agent endpoints with automatic USDT micropayments on TRON.

## Quick Start

### Option 1: Run Pre-built (Recommended for Agents)
The skill is pre-bundled into a single file. No installation required.
```bash
node dist/index.js --url <URL> [options]
```

### Option 2: Development
```bash
npm install
npm start -- --url <URL>
```

## Tool Reference

- **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 configuration).
  3. `x402-config.json` in the current directory.
  4. `~/.x402-config.json` in the home directory.
- **USDT on TRON**: Wallet needs USDT and some TRX for gas.

---

## Tool Reference

### x402_tron_invoke

Invokes an HTTP endpoint. If payment is required (402), it automatically:
1. Negotiates payment requirements.
2. Checks USDT allowance. If insufficient, it performs an **infinite approval** (MAX_UINT256) to minimize future transactions.
3. Signs the payment permit (EIP-712).
4. Retries the request with the payment signature.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | Yes | Full URL to invoke |
| `method` | string | No | HTTP method (GET, POST, etc.) Default: GET |
| `body` | object | No | JSON body for the request |
| `network` | string | No | `mainnet`, `nile`, `shasta` (Default: `nile`) |

### Example: Chat with Agent

```tool:x402_tron_invoke
url: https://api.example.com/chat
method: POST
body: {"prompt": "Tell me a joke"}
```

---

## Agent Discovery

You can discover available endpoints and their pricing by checking the agent's manifest.

### Fetch Agent Manifest

```tool:x402_tron_invoke
url: https://api.example.com/.well-known/agent.json
method: GET
```

---

## 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 (e.g., `export TRON_PRIVATE_KEY=...`).
- **Sanitized Logs**: Ensure that logs or error messages do not leak the key.

## 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. 
**Agent Note**: If this error occurs, simply inform the user that the environment is not configured. DO NOT attempt to search for or read private keys from files yourself.

### "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 USDT and TRX.

---

## 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_...` or `/tmp/x402_binary_...`).
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 or processed.

---

## Network Reference

| Network | Chain ID | CAIP-2 | USDT Contract |
|---------|----------|--------|---------------|
| TRON Mainnet | 0x2b6653dc | `eip155:728126428`, `tron:mainnet` | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` |
| TRON Nile | 0xcd8690dc | `eip155:3448148188`, `tron:nile` | `TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf` |
| TRON Shasta | 0x94a9059e | `eip155:2494104990`, `tron:shasta` | - |