@springmint/x402-payment 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Springmint
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,261 @@
+# @springmint/x402-payment
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![npm](https://img.shields.io/npm/v/@springmint/x402-payment)](https://www.npmjs.com/package/@springmint/x402-payment)
+
+Add **pay-per-use** capability to your AI agent skills and Node.js applications with the [x402 protocol](https://x402.org).
+
+## What is x402?
+
+x402 is a payment protocol built on HTTP status code **402 Payment Required**. When you call an x402-enabled API without paying, the server returns a `402` response with payment requirements. This SDK handles the entire payment flow automatically:
+
+```
+Your App                          Paid API Server
+  │                                     │
+  │──── GET /api/data ─────────────────>│
+  │<─── 402 Payment Required ───────────│  (includes: price, token, chain, payTo)
+  │                                     │
+  │  [SDK auto-signs & pays on-chain]   │
+  │                                     │
+  │──── GET /api/data + payment proof ─>│
+  │<─── 200 OK + data ─────────────────│
+  └─────────────────────────────────────┘
+```
+
+**You don't need to handle any of this yourself.** Just use `createX402FetchClient()` and call your API like normal — the SDK intercepts 402 responses, pays on-chain, and retries automatically.
+
+## Install
+
+```bash
+npm install @springmint/x402-payment
+```
+
+## Wallet Configuration
+
+The SDK needs a private key to sign on-chain payments. It searches in this order:
+
+| Priority | Source | Keys |
+|----------|--------|------|
+| 1 | Environment variables | `TRON_PRIVATE_KEY`, `EVM_PRIVATE_KEY`, `ETH_PRIVATE_KEY`, `PRIVATE_KEY` |
+| 2 | Project config | `./x402-config.json` |
+| 3 | User config | `~/.x402-config.json` |
+| 4 | mcporter config | `~/.mcporter/mcporter.json` |
+
+Quickest way:
+
+```bash
+# For EVM chains (BSC, Ethereum, Base, etc.)
+export EVM_PRIVATE_KEY=your_private_key_hex
+
+# For TRON
+export TRON_PRIVATE_KEY=your_private_key_hex
+
+# Verify
+npx @springmint/x402-payment --check
+# [OK] EVM Wallet: 0x1234...abcd
+# [OK] TRON Wallet: TXyz...
+```
+
+Or use a config file:
+
+```json
+// x402-config.json
+{
+  "evm_private_key": "your_evm_key",
+  "tron_private_key": "your_tron_key",
+  "tron_grid_api_key": "your_trongrid_key"
+}
+```
+
+## Usage
+
+### As a Library
+
+Import the SDK in your skill or Node.js application to call paid APIs:
+
+```ts
+import { createX402FetchClient } from "@springmint/x402-payment";
+
+// Create a client — keys are auto-discovered
+const client = await createX402FetchClient();
+
+// Use it like a normal fetch — 402 payments are handled automatically
+const response = await client.request(
+  "https://www.cpbox.io/api/rpc/x402/batch-balance",
+  {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      chain: "ethereum",
+      token: "",
+      addresses: ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"],
+    }),
+  },
+);
+
+const data = await response.json();
+console.log(data);
+```
+
+For the common pattern of calling an x402 agent's entrypoint, use the high-level helper:
+
+```ts
+import { invokeEndpoint } from "@springmint/x402-payment";
+
+// Entrypoint mode — automatically calls POST {url}/entrypoints/{name}/invoke
+const result = await invokeEndpoint("https://api.example.com", {
+  entrypoint: "chat",
+  input: { prompt: "hello" },
+});
+console.log(result.status); // 200
+console.log(result.body);   // { response: "..." }
+```
+
+You can also pass keys explicitly instead of relying on auto-discovery:
+
+```ts
+const client = await createX402FetchClient({
+  evmPrivateKey: "0x...",
+  tronPrivateKey: "...",
+  silent: true, // suppress [x402] log output
+});
+```
+
+### As a CLI
+
+AI agents and command-line users can invoke paid APIs directly:
+
+```bash
+# Call an agent's entrypoint
+npx @springmint/x402-payment \
+  --url https://api.example.com \
+  --entrypoint chat \
+  --input '{"prompt": "hello"}'
+
+# Call a URL directly
+npx @springmint/x402-payment \
+  --url https://www.cpbox.io/api/rpc/x402/batch-balance \
+  --method POST \
+  --input '{"chain":"ethereum","token":"","addresses":["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"]}'
+```
+
+#### CLI Options
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `--url` | Yes | Target API endpoint URL |
+| `--entrypoint` | No | Entrypoint name (constructs `/entrypoints/{name}/invoke` URL, forces POST) |
+| `--input` | No | JSON request body |
+| `--method` | No | HTTP method (default: GET for direct, POST for entrypoint) |
+| `--check` | No | Verify wallet configuration and exit |
+
+Output goes to **stdout** as JSON. Logs go to **stderr**.
+
+## API Reference
+
+### `createX402FetchClient(options?)`
+
+Create a fetch client that automatically handles 402 payment flows.
+
+Returns an `X402FetchClient` instance. Use `client.request(url, init)` to make requests — the same interface as `fetch()`.
+
+### `createX402Client(options?)`
+
+Create the underlying `X402Client` with all payment mechanisms registered. Use this when you need lower-level control over payment mechanisms and policies.
+
+### `invokeEndpoint(url, options?)`
+
+High-level helper that creates a client, sends the request, and returns the parsed response.
+
+```ts
+const result = await invokeEndpoint(url, {
+  entrypoint?: string,       // entrypoint name (switches to invoke mode)
+  input?: any,               // request body (auto-serialized to JSON)
+  method?: string,           // HTTP method
+  clientOptions?: {          // passed to createX402FetchClient
+    tronPrivateKey?: string,
+    evmPrivateKey?: string,
+    tronGridApiKey?: string,
+    silent?: boolean,
+  },
+});
+// result: { status: number, headers: Record<string, string>, body: any }
+```
+
+### `findPrivateKey(type: "tron" | "evm")`
+
+Search for a private key following the lookup order described in [Wallet Configuration](#wallet-configuration).
+
+### `findApiKey()`
+
+Search for TronGrid API key using the same lookup order.
+
+## Supported Networks & Tokens
+
+| Chain    | Network       | Tokens           | Example USDT Contract |
+|----------|---------------|------------------|-----------------------|
+| **TRON** | `mainnet`     | USDT, USDD       | `TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t` |
+| **TRON** | `nile`        | USDT, USDD       | `TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf` |
+| **BSC**  | `bsc`         | USDT, USDC       | `0x55d398326f99059fF775485246999027B3197955` |
+| **BSC**  | `bsc-testnet` | USDT, USDC, DHLU | `0x337610d27c682E347C9cD60BD4b3b107C9d34dDd` |
+
+Both **direct transfer** and **permit-based** payment mechanisms are supported on all chains.
+
+## For AI Agent Skill Developers
+
+If you're building a skill that calls a paid API, add this package as a dependency:
+
+```bash
+npm install @springmint/x402-payment
+```
+
+Then in your skill's code:
+
+```ts
+import { createX402FetchClient } from "@springmint/x402-payment";
+
+const client = await createX402FetchClient();
+const res = await client.request("https://your-paid-api.com/endpoint", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ /* your request */ }),
+});
+```
+
+And in your skill's `SKILL.md`, declare the dependency:
+
+```yaml
+dependencies:
+  - x402-payment
+```
+
+See [cpbox-skills/batch-balance](https://github.com/springmint/cpbox-skills) for a real-world example.
+
+## Security
+
+- Private keys are **never** output to stdout or logs
+- Error messages are automatically sanitized to redact any leaked key material
+- `console.log` is redirected to `stderr` in CLI mode to prevent library output from polluting your data pipeline
+- Always use testnet (`nile`, `bsc-testnet`) for development
+
+## Project Structure
+
+```
+x402-payment/
+├── README.md
+├── LICENSE
+├── package.json              # @springmint/x402-payment
+├── SKILL.md                  # AI Agent instruction file
+├── src/
+│   ├── index.ts              # Library exports
+│   ├── config.ts             # Key discovery
+│   ├── client.ts             # Client factory & invokeEndpoint
+│   └── cli.ts                # CLI entry point
+└── dist/
+    ├── lib/                  # Library build (import)
+    └── cli/                  # CLI build (npx / bin)
+```
+
+## License
+
+[MIT](LICENSE)

package/SKILL.md

@@ -0,0 +1,159 @@
+---
+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.0
+  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
+
+- **Wallet Configuration**:
+  - **TRON**: Set `TRON_PRIVATE_KEY` for TRC20 payments (USDT/USDD).
+  - **EVM**: Set `EVM_PRIVATE_KEY` or `ETH_PRIVATE_KEY` for ERC20 payments (USDT/USDC).
+  - The skill also searches for keys in `x402-config.json` and `~/.mcporter/mcporter.json`.
+- **TronGrid API Key**: Required for **Mainnet** to avoid rate limits (`TRON_GRID_API_KEY`).
+
+## 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 allowance is insufficient, the tool will automatically attempt an "infinite approval" transaction. 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_

package/dist/cli/254.index.js

@@ -0,0 +1,222 @@
+export const id = 254;
+export const ids = [254];
+export const modules = {
+
+/***/ 7254:
+/***/ ((__unused_webpack___webpack_module__, __webpack_exports__, __webpack_require__) => {
+
+
+// EXPORTS
+__webpack_require__.d(__webpack_exports__, {
+  offchainLookup: () => (/* binding */ offchainLookup),
+  offchainLookupSignature: () => (/* binding */ offchainLookupSignature)
+});
+
+// UNUSED EXPORTS: ccipRequest, offchainLookupAbiItem
+
+// EXTERNAL MODULE: ./node_modules/viem/_esm/actions/public/call.js + 1 modules
+var call = __webpack_require__(8454);
+// EXTERNAL MODULE: ./node_modules/viem/_esm/utils/stringify.js
+var stringify = __webpack_require__(2162);
+// EXTERNAL MODULE: ./node_modules/viem/_esm/errors/base.js + 1 modules
+var base = __webpack_require__(9298);
+// EXTERNAL MODULE: ./node_modules/viem/_esm/errors/utils.js
+var utils = __webpack_require__(8400);
+;// CONCATENATED MODULE: ./node_modules/viem/_esm/errors/ccip.js
+
+
+
+class OffchainLookupError extends base/* BaseError */.C {
+    constructor({ callbackSelector, cause, data, extraData, sender, urls, }) {
+        super(cause.shortMessage ||
+            'An error occurred while fetching for an offchain result.', {
+            cause,
+            metaMessages: [
+                ...(cause.metaMessages || []),
+                cause.metaMessages?.length ? '' : [],
+                'Offchain Gateway Call:',
+                urls && [
+                    '  Gateway URL(s):',
+                    ...urls.map((url) => `    ${(0,utils/* getUrl */.I)(url)}`),
+                ],
+                `  Sender: ${sender}`,
+                `  Data: ${data}`,
+                `  Callback selector: ${callbackSelector}`,
+                `  Extra data: ${extraData}`,
+            ].flat(),
+            name: 'OffchainLookupError',
+        });
+    }
+}
+class OffchainLookupResponseMalformedError extends base/* BaseError */.C {
+    constructor({ result, url }) {
+        super('Offchain gateway response is malformed. Response data must be a hex value.', {
+            metaMessages: [
+                `Gateway URL: ${(0,utils/* getUrl */.I)(url)}`,
+                `Response: ${(0,stringify/* stringify */.A)(result)}`,
+            ],
+            name: 'OffchainLookupResponseMalformedError',
+        });
+    }
+}
+class OffchainLookupSenderMismatchError extends base/* BaseError */.C {
+    constructor({ sender, to }) {
+        super('Reverted sender address does not match target contract address (`to`).', {
+            metaMessages: [
+                `Contract address: ${to}`,
+                `OffchainLookup sender address: ${sender}`,
+            ],
+            name: 'OffchainLookupSenderMismatchError',
+        });
+    }
+}
+//# sourceMappingURL=ccip.js.map
+// EXTERNAL MODULE: ./node_modules/viem/_esm/errors/request.js
+var request = __webpack_require__(1168);
+// EXTERNAL MODULE: ./node_modules/viem/_esm/utils/abi/decodeErrorResult.js
+var decodeErrorResult = __webpack_require__(2615);
+// EXTERNAL MODULE: ./node_modules/viem/_esm/utils/abi/encodeAbiParameters.js
+var encodeAbiParameters = __webpack_require__(3570);
+// EXTERNAL MODULE: ./node_modules/viem/_esm/utils/address/isAddressEqual.js
+var isAddressEqual = __webpack_require__(2538);
+// EXTERNAL MODULE: ./node_modules/viem/_esm/utils/data/concat.js
+var concat = __webpack_require__(5878);
+// EXTERNAL MODULE: ./node_modules/viem/_esm/utils/data/isHex.js
+var isHex = __webpack_require__(4381);
+// EXTERNAL MODULE: ./node_modules/viem/_esm/utils/ens/localBatchGatewayRequest.js + 3 modules
+var localBatchGatewayRequest = __webpack_require__(3547);
+;// CONCATENATED MODULE: ./node_modules/viem/_esm/utils/ccip.js
+
+
+
+
+
+
+
+
+
+
+const offchainLookupSignature = '0x556f1830';
+const offchainLookupAbiItem = {
+    name: 'OffchainLookup',
+    type: 'error',
+    inputs: [
+        {
+            name: 'sender',
+            type: 'address',
+        },
+        {
+            name: 'urls',
+            type: 'string[]',
+        },
+        {
+            name: 'callData',
+            type: 'bytes',
+        },
+        {
+            name: 'callbackFunction',
+            type: 'bytes4',
+        },
+        {
+            name: 'extraData',
+            type: 'bytes',
+        },
+    ],
+};
+async function offchainLookup(client, { blockNumber, blockTag, data, to, }) {
+    const { args } = (0,decodeErrorResult/* decodeErrorResult */.W)({
+        data,
+        abi: [offchainLookupAbiItem],
+    });
+    const [sender, urls, callData, callbackSelector, extraData] = args;
+    const { ccipRead } = client;
+    const ccipRequest_ = ccipRead && typeof ccipRead?.request === 'function'
+        ? ccipRead.request
+        : ccipRequest;
+    try {
+        if (!(0,isAddressEqual/* isAddressEqual */.h)(to, sender))
+            throw new OffchainLookupSenderMismatchError({ sender, to });
+        const result = urls.includes(localBatchGatewayRequest/* localBatchGatewayUrl */.J)
+            ? await (0,localBatchGatewayRequest/* localBatchGatewayRequest */.X)({
+                data: callData,
+                ccipRequest: ccipRequest_,
+            })
+            : await ccipRequest_({ data: callData, sender, urls });
+        const { data: data_ } = await (0,call/* call */.T)(client, {
+            blockNumber,
+            blockTag,
+            data: (0,concat/* concat */.xW)([
+                callbackSelector,
+                (0,encodeAbiParameters/* encodeAbiParameters */.h)([{ type: 'bytes' }, { type: 'bytes' }], [result, extraData]),
+            ]),
+            to,
+        });
+        return data_;
+    }
+    catch (err) {
+        throw new OffchainLookupError({
+            callbackSelector,
+            cause: err,
+            data,
+            extraData,
+            sender,
+            urls,
+        });
+    }
+}
+async function ccipRequest({ data, sender, urls, }) {
+    let error = new Error('An unknown error occurred.');
+    for (let i = 0; i < urls.length; i++) {
+        const url = urls[i];
+        const method = url.includes('{data}') ? 'GET' : 'POST';
+        const body = method === 'POST' ? { data, sender } : undefined;
+        const headers = method === 'POST' ? { 'Content-Type': 'application/json' } : {};
+        try {
+            const response = await fetch(url.replace('{sender}', sender.toLowerCase()).replace('{data}', data), {
+                body: JSON.stringify(body),
+                headers,
+                method,
+            });
+            let result;
+            if (response.headers.get('Content-Type')?.startsWith('application/json')) {
+                result = (await response.json()).data;
+            }
+            else {
+                result = (await response.text());
+            }
+            if (!response.ok) {
+                error = new request/* HttpRequestError */.Ci({
+                    body,
+                    details: result?.error
+                        ? (0,stringify/* stringify */.A)(result.error)
+                        : response.statusText,
+                    headers: response.headers,
+                    status: response.status,
+                    url,
+                });
+                continue;
+            }
+            if (!(0,isHex/* isHex */.q)(result)) {
+                error = new OffchainLookupResponseMalformedError({
+                    result,
+                    url,
+                });
+                continue;
+            }
+            return result;
+        }
+        catch (err) {
+            error = new request/* HttpRequestError */.Ci({
+                body,
+                details: err.message,
+                url,
+            });
+        }
+    }
+    throw error;
+}
+//# sourceMappingURL=ccip.js.map
+
+/***/ })
+
+};