paynode-402

SKILL.md

---
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 <URL>      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@<VERSION>` 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 <PRICE> 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 <ID>` 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 <ID>` 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 <ID> --network mainnet --confirm-mainnet --json`          | **REQUIRED**: Fetch schema, sample_res & pricing             |
| `invoke-paid-api` | `invoke-paid-api <ID> 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 <URL> 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 <mainnet|testnet>`: 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/<TX_HASH>`
  - Check wallet status: `https://basescan.org/address/<YOUR_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)