--- name: paynode-402 description: Dynamic Premium API Marketplace for AI Agents. Grants access to an ever-expanding registry of real-time external tools (e.g., web search, crypto oracles, web scraping, and more) via USDC micro-payments. Use this WHENEVER you need real-time data, external API interactions, or when your built-in knowledge is insufficient. version: 2.7.5 metadata: openclaw: homepage: https://github.com/PayNodeLabs/paynode-402-cli requires: env: - CLIENT_PRIVATE_KEY config: - "~/.config/paynode/config.json" bins: - bun primaryEnv: CLIENT_PRIVATE_KEY cliHelp: | Usage: bunx @paynodelabs/paynode-402-cli [command] Commands: check Check wallet readiness (ETH/USDC) mint Mint test USDC request Access protected API list-paid-apis Marketplace discovery invoke-paid-api Execution flow tasks Manage background tasks --- # 💳 PayNode 402 CLI Skill (v2.7.2) > Official ClawHub-compliant skill for PayNode protocol execution. ## ⚠️ Security Warning Before installing or activating this skill, please review the following critical security considerations: - **Burner Wallet ONLY**: Never provide a high-value primary key in `CLIENT_PRIVATE_KEY`. Always use a dedicated burner address with minimal funds. - **Config File Fallback**: This skill reads `~/.config/paynode/config.json` if the env var is missing. Ensure you verify the contents of this file in your environment. - **Supply Chain & Auditability**: The [PayNode CLI](https://github.com/PayNodeLabs/paynode-402-cli) and its core dependency [@paynodelabs/sdk-js](https://github.com/PayNodeLabs/paynode-sdk-js) are **100% Open Source** and verifiable. While we use `bunx` for its seamless update delivery, strict environments should **Git clone & audit** the source code and use a local build: - _Local Install Path_: `git clone ... && bun link` then use `paynode-402` directly instead of `bunx`. - **Runtime Transparency**: The CLI v2.7.2+ is designed to be deterministic. You can pin specific versions via `bunx @paynodelabs/paynode-402-cli@` to prevent auto-updates in critical workflows. - **Sandbox First**: Always test in a sandbox or with Testnet (`--network testnet`) before proceeding to real-value transactions. This skill provides autonomous payment capabilities for HTTP 402 (Payment Required) challenges on Base L2. ## 🛠️ Setup & Config (Mandatory) To ensure this skill can sign transactions even in non-interactive shells (like OpenClaw Gateway), it supports a dual-layer configuration priority: 1. **Priority B (Environment Variable)**: The CLI will first check for `CLIENT_PRIVATE_KEY` in your system environment. 2. **Priority A (XDG Config Fallback)**: If the env var is missing, it will automatically search for a JSON config at: `~/.config/paynode/config.json`. - **Format**: `{"CLIENT_PRIVATE_KEY": "0x..."}` **Recommendation**: Use **Priority B** for dynamic/containerized environments, and **Priority A** for persistent local development or cases where `.bashrc` is not sourced. ## 🛡️ Security Governance (Critical) To comply with **ClawHub Safety Standards**, the Agent MUST strictly follow these protocols: 1. **Burner Wallet ONLY**: Never use high-value primary keys. Advise users to use a dedicated burner address with minimal USDC/ETH for this skill. 2. **Mainnet YES-Confirmation**: Before calling `request` or `invoke-paid-api` on **Mainnet**, the Agent MUST explicitly prompt the user: "Allow payment of on Mainnet?". Proceed ONLY on "YES". Read-only inspection commands may still require `--confirm-mainnet` because of CLI safety policy, but they must not be represented as user-approved spending actions. 3. **Data Path Isolation**: The `data_binary` field returns a local filesystem path. Only read this path if generated during the current session's request. 4. **No Parameter Hallucination**: ALWAYS call `get-api-detail ` to fetch the correct `input_schema` and `sample_response` before execution. 5. **Clean Logs**: The CLI (v2.7.2+) automatically silences internal logs in `--json` mode. You should expect pure, parseable JSON on `stdout`. 6. **Financial Optimization (CRITICAL)**: Paid APIs cost real USDC. YOU MUST NOT call the same paid API multiple times for the same context. ALWAYS pipe output to a temporary file (e.g., `... > /tmp/res.json`) and parse locally to save costs. ## 💡 Quick Start (Success Path) > **Mainnet by Default**: PayNode's production marketplace is on mainnet. The commands below therefore use `--network mainnet`. > > **Critical Rule**: The CLI requires `--confirm-mainnet` for mainnet operations. Explicit user approval is mandatory before any command that may spend real USDC, especially `request` and `invoke-paid-api`. Read-only commands such as `check`, `list-paid-apis`, and `get-api-detail` may use the flag for inspection, but should still be treated as sensitive mainnet operations. ```bash # 1. Verify your mainnet readiness bunx @paynodelabs/paynode-402-cli check --network mainnet --confirm-mainnet --json # 2. Find a tool (Discovery Phase) bunx @paynodelabs/paynode-402-cli list-paid-apis --network mainnet --confirm-mainnet --json --limit 3 # 3. Get precise parameters & execute bunx @paynodelabs/paynode-402-cli get-api-detail crypto-price-quick --network mainnet --confirm-mainnet --json # 🛑🛑🛑 STOP! CRITICAL RULE 🛑🛑🛑 # YOU MUST USE THE `clarify` TOOL TO ASK THE HUMAN FOR PERMISSION BEFORE RUNNING THE NEXT COMMAND. # ONLY RUN THIS AFTER THE HUMAN SAYS "YES": bunx @paynodelabs/paynode-402-cli invoke-paid-api crypto-price-quick coin_id=bitcoin --network mainnet --confirm-mainnet --json ``` Use the execution command above only after the user has explicitly approved spending real USDC on mainnet. ## 🤖 Agent Action Triggers & Discovery Protocol PayNode is a DYNAMIC marketplace. The available APIs and capabilities change and expand over time. You must adopt a "Discovery-First" approach. **WHEN TO USE THIS SKILL:** 1. **Knowledge Gap:** If the user asks for real-time data, current events, live market prices, or content behind URLs that you cannot access natively. 2. **Specialized Tasks:** If the user requests specialized processing (e.g., data extraction, blockchain analytics, specific third-party integrations). **STANDARD WORKFLOW (The "Check Before Giving Up" Rule):** - Step 1 (Discovery): NEVER tell the user "I don't have access to real-time internet" or "I cannot do that" without FIRST checking the marketplace. Run `list-paid-apis --network mainnet --confirm-mainnet --json` to explore available tools. On mainnet, the agent must still obtain explicit user permission before using `--confirm-mainnet`. - Step 2 (Analysis): Use `get-api-detail ` to fetch the full manifest. **Pay attention to `sample_response`** to understand the data structure you will receive. The CLI handles `headers_template` automatically, so you don't need to manually set headers defined by the merchant. - Step 3 (Execution): Ask for user permission (showing the price), then use `invoke-paid-api` to fulfill the request. ## 🚀 Cold Start (Discovery Phase) The first action MUST be indexing the marketplace (**Outbound discovery**). Use this to explore current premium tools: ```bash bunx @paynodelabs/paynode-402-cli list-paid-apis --network mainnet --confirm-mainnet --json --limit 10 ``` ## 📋 Command Reference | Command | Usage Example | Purpose | | :---------------- | :------------------------------------------------------------------------ | :----------------------------------------------------------- | | `list-paid-apis` | `list-paid-apis --network mainnet --confirm-mainnet --json` | **DISCOVERY**: Explore available tools | | `get-api-detail` | `get-api-detail --network mainnet --confirm-mainnet --json` | **REQUIRED**: Fetch schema, sample_res & pricing | | `invoke-paid-api` | `invoke-paid-api key=val --network mainnet --confirm-mainnet --json` | **EXECUTION**: Auto-handles payment. Use `key=value` format. | | `check` | `check --network mainnet --confirm-mainnet --json` | Balance readiness (silenced logs) | | `request` | `request key=val --json` | Access protected 402 URL (Low-level) | | `tasks` | `tasks list` | Async progress monitor | | `mint` | `mint --amount 100 --json` | Get test tokens (Base Sepolia) | ### 🛠️ Global Flags - `--network `: Target (Default: testnet). - `--confirm-mainnet`: Required for real USDC. - `--json`: Required for agent parsing. --- ## 🔧 Troubleshooting & Debugging - **`402 Handshake Failure`**: Ensure `CLIENT_PRIVATE_KEY` is valid and the wallet has a tiny amount of native ETH for base fee, even on Testnet. - **`Insufficient USDC`**: Run `check` to verify your balance. On Testnet, use `mint` to get 1000 USDC instantly. - **`Provider Error`**: High RPC latency can skip verification. The CLI v2.7.2 includes 3x retry logic and enhanced X402 v2 (CoinGecko/Coinbase) protocol support, but ensure your network connection is stable. - **`Transaction Pending`**: Wait 5-10 seconds for L2 finality. Use [BaseScan](https://basescan.org) to verify: - Track transactions: `https://basescan.org/tx/` - Check wallet status: `https://basescan.org/address/` --- ## 🛡️ Security & Environment - **Environment Priority**: ALWAYS prioritize **`mainnet`** for production tasks to ensure access to real-time, high-fidelity data. - **Testing & Debug**: Use `testnet` (Base Sepolia) only for initial integration testing, connectivity debugging, or development. - **Wallet Safety**: Use a **Burner Wallet** with minimum required funds. Never use a primary vault key. - **Required Flags**: Mainnet execution requires the `--confirm-mainnet` flag to prevent accidental spending. This flag should only be added after the user has explicitly approved the spend. - **Data Integrity**: Always use the `--json` flag for consistent agentic parsing. --- ## 🔗 Resources - **CLI (GitHub)**: [PayNodeLabs/paynode-402-cli](https://github.com/PayNodeLabs/paynode-402-cli) - **CLI (NPM)**: [@paynodelabs/paynode-402-cli](https://www.npmjs.com/package/@paynodelabs/paynode-402-cli) - **SDK (GitHub)**: [PayNodeLabs/paynode-sdk-js](https://github.com/PayNodeLabs/paynode-sdk-js) - **SDK (NPM)**: [@paynodelabs/sdk-js](https://www.npmjs.com/package/@paynodelabs/sdk-js) - **Faucet**: [Base Official Faucets](https://docs.base.org/base-chain/network-information/network-faucets#network-faucets) - **Protocol**: [PayNode Specification](https://docs.paynode.dev)

paynode-402

Description

Latest Changes

Install paynode-402 with One Click