x402-payment

Category: Tools & Productivity | Uploader: springmint | Downloads: 0 | Version: v1.0（Latest）

Pay for x402-enabled Agent endpoints using ERC20 tokens (USDT/USDC) on EVM or TRC20 tokens (USDT/USDD) on TRON.

Changelog: Source: GitHub https://github.com/springmint/x402-payment

Directory Structure

Current level: Root

📁 src/
- 📄 cli.ts 6.4 KB
- 📄 client.ts 6.7 KB
- 📄 config.ts 3.3 KB
- 📄 index.ts 231 B
📄 .gitignore 43 B
📄 .yarnrc.yml 25 B
📄 AGENTS.md 2.8 KB
📄 CONTRIBUTING.md 1.4 KB
📄 LICENSE 1.0 KB
📄 package.json 1.4 KB
📄 README.md 11.2 KB
📄 SKILL.md 6.1 KB
📄 tsconfig.json 358 B
📄 yarn.lock 41.4 KB

SKILL.md

---
name: x402-payment
description: "Pay for x402-enabled Agent endpoints using ERC20 tokens (USDT/USDC) on EVM or TRC20 tokens (USDT/USDD) on TRON."
user-invokable: true
argument-hint: "url(required): Base URL of the agent (v2) or full URL (v1/Discovery); entrypoint(optional): Entrypoint name to invoke (e.g., 'chat', 'search'); input(optional): Input object to send to the entrypoint; method(optional): HTTP method (GET/POST), default POST(v2)/GET(Direct)"
compatibility:
  tools:
    - x402_invoke
metadata:
  version: 1.0.2
  author: cppay.finance
  homepage: https://x402.org
  tags: [crypto, payments, x402, agents, api, usdt, usdd, usdc, tron, ethereum, evm, erc20, trc20, sdk]
  requires_tools: [x402_invoke]
  tool_implementation_mapping:
    x402_invoke: dist/cli/x402_invoke.js
  dependencies:
    - mcp-server-tron
---

# x402 Payment Skill

Invoke x402-enabled AI agent endpoints with automatic token payments on both TRON (TRC20) and EVM-compatible (ERC20) chains.

## Overview

The `x402-payment` package provides two ways to handle x402 payments:

1. **As a library** — other skills and Node.js apps `import` it to gain x402 payment capability
2. **As a CLI tool** — AI agents invoke `x402_invoke` directly from the command line

When an HTTP `402 Payment Required` response is received, the package automatically handles negotiation, signing, and execution of the on-chain payment.

## Prerequisites

1. Install: `npm install @springmint/x402-payment`
2. Configure wallet — see [Wallet Configuration](https://github.com/springmint/x402-payment#wallet-configuration) for all supported methods (environment variables, `x402-config.json`, `~/.mcporter/mcporter.json`)
3. Verify: `npx @springmint/x402-payment --check`

## Usage as a Library

Other skills can add x402 payment capability by importing this package:

```bash
npm install @springmint/x402-payment
```

```ts
import { createX402FetchClient, invokeEndpoint } from "@springmint/x402-payment";

// Option 1: Fetch client with automatic 402 handling
const client = await createX402FetchClient();
const response = await client.request("https://paid-api.com/endpoint", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ query: "hello" }),
});

// Option 2: High-level invoke helper
const result = await invokeEndpoint("https://api.example.com", {
  entrypoint: "chat",
  input: { prompt: "hello" },
});
```

### Library API

| Function | Description |
|----------|-------------|
| `createX402FetchClient(options?)` | Create a fetch client with automatic 402 payment handling |
| `createX402Client(options?)` | Create the underlying X402Client with payment mechanisms |
| `invokeEndpoint(url, options?)` | High-level: create client, request, return parsed response |
| `findPrivateKey(type)` | Discover private key from env/config files |
| `findApiKey()` | Discover TronGrid API key |

## Usage as CLI (AI Agent)

### 1. Verification

Before making payments, verify your wallet status:

```bash
npx @springmint/x402-payment --check
```

### 2. Invoking an Agent (v2)

Most modern x402 agents use the v2 "invoke" pattern:

```bash
npx @springmint/x402-payment \
  --url https://api.example.com \
  --entrypoint chat \
  --input '{"prompt": "Your query here"}'
```

### 3. Agent Discovery (Direct)

- **Manifest**: Fetch agent metadata.
  ```bash
  npx @springmint/x402-payment --url https://api.example.com/.well-known/agent.json
  ```
- **List Entrypoints**: List available functions.
  ```bash
  npx @springmint/x402-payment --url https://api.example.com/entrypoints
  ```

### 4. Cross-Chain Support

The SDK automatically detects the required chain from the server's 402 response. No need to specify the network manually — it matches the payment requirements with registered mechanisms.

- **TRON (TRC20)**: Requires `TRON_PRIVATE_KEY`
- **EVM (ERC20)**: Requires `EVM_PRIVATE_KEY` or `ETH_PRIVATE_KEY`

## Supported Networks & Tokens

| Chain    | Network Name  | Common Tokens    | USDT Contract                                |
| -------- | ------------- | ---------------- | -------------------------------------------- |
| **TRON** | `mainnet`     | USDT, USDD       | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t`         |
| **TRON** | `nile`        | USDT, USDD       | `TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf`         |
| **BSC**  | `bsc`         | USDT, USDC       | `0x55d398326f99059fF775485246999027B3197955` |
| **BSC**  | `bsc-testnet` | USDT, USDC, DHLU | `0x337610d27c682E347C9cD60BD4b3b107C9d34dDd` |

## Security Considerations & Rules

> [!CAUTION]
> **Private Key Safety**: NEVER output your private keys to the logs or console. The package loads keys from environment variables internally.

### Agent Security Rules:

- **No Private Key Output**: The Agent MUST NOT print, echo, or output any private key to the dialogue context.
- **Internal Loading Only**: Rely on the tool to load keys internally.
- **No Export Commands**: DO NOT execute shell commands containing the private key as a literal string.
- **Silent Environment Checks**: Use `[[ -n $TRON_PRIVATE_KEY ]] && echo "Configured" || echo "Missing"` to verify configuration without leaking secrets.
- **Use the Check Tool**: Use `x402-payment --check` to safely verify addresses.

## Binary and Image Handling

If the endpoint returns an image or binary data (CLI mode only):

1. The data is saved to a temporary file (e.g., `/tmp/x402_image_...`).
2. The tool returns JSON with `file_path`, `content_type`, and `bytes`.
3. **Important**: The Agent is responsible for deleting the temporary file after use.

## Error Handling

### Insufficient Allowance

If you get an allowance error, approve the token first:

```bash
# Check current allowance
npx @springmint/x402-payment --allowance --token <TOKEN_ADDRESS> --network <NETWORK>

# Approve token spending
npx @springmint/x402-payment --approve --token <TOKEN_ADDRESS> --network <NETWORK>
```

Or in code:
```ts
import { approveToken } from "@springmint/x402-payment";
await approveToken("evm", "0x55d3...7955", "eip155:97");
```

Ensure you have native tokens (TRX or BNB/ETH) for gas.

### Insufficient Balance

Ensure you have enough USDT/USDC/USDD in your wallet on the specified network.

---

_Last Updated: 2026-03-17_

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

x402-payment

Directory Structure

SKILL.md

Report

Notice