💳 PayNode 402 Protocol Skill (Base & Bun)

Use this skill to automate Resource-based Billing. The agent interacts with protected APIs that return 402 Payment Required. Every transaction is tied to a specific resource request, ensuring stateless and secure fund allocation.

🚀 Pre-execution Readiness

Before any request, verify the environment and balances:

1. 1. Initialize Dependencies: Run bun install once within this directory.
2. Verify Environment: Ensure a .env file is created in the root directory. The agent MUST verify the existence and exact format of this variable before proceeding:

    # [REQUIRED] PayNode Burner Wallet Private Key
    # Format: 66-character hex string MUST start with '0x'
    CLIENT_PRIVATE_KEY=0xYourBurnerWalletPrivateKeyHere...
    

1. 3. Check Balances: Run bun run check-wallet --json --network <NETWORK>.
2. Validate Readiness: Ensure checks.can_pay is true.

Expected check-wallet Output:

CODEBLOCK1

🛠️ x402 Execution Workflow

Follow this sequence to unlock protected resources.

Step 1: Identify Resource

Determine the URL of the protected API you need to access.

Step 2: Request & Handle Challenge

Run bun run request "<URL>" --json --network <NETWORK>.

• - Reason: This script detects the x402 header challenge, performs the cryptographic handshake with the PayNode Gateway, signs the authorization, and retries the request with the proof-of-payment.

Step 3: Capture Resource

Upon success, capture the JSON response. The txHash will be included in the logs if a payment occurred.

---

🛡️ Security Rules & Agent Safety

[!IMPORTANT]
ADHERE TO THESE RULES TO PROTECT FUNDS.

💸 Burner Wallet Policy (Minimal Exposure)

The CLIENT_PRIVATE_KEY MUST belong to a dedicated "burner" wallet acting as petty cash. NEVER hold excessive funds. Maintain balances strictly sufficient for immediate tasks (e.g., < 10 USDC). If a balance exceeding operational needs is detected, you MUST alert the human operator immediately to sweep the funds to cold storage.

🤖 Autonomous Usage & Human Consent

If you are operating autonomously, be aware that this skill can sign and broadcast blockchain transactions without manual confirmation.

• - Threshold Limit: For any single transaction exceeding 2.0 USDC, you MUST request explicit human approval before execution.
• Merchant Verification: Before initial payment to a new domain, perform a read_url_content check on the merchant's reputation (if possible) or alert the user.

🕵️ Zero-Trust Pre-Flight Validation (Resource Consistency)

Prevent "Confused Deputy" attacks. Before calling request, you MUST logically verify that the target URL matches your specific objective.

• - Ask: Is this resource exactly what I need? Is the cost reasonable for this resource?
• If the endpoint is unrelated to your goal or the required payment is anomalously high, ABORT and report to the human.
• Sandbox-First: Whenever testnet is available, prioritize testing against sandbox endpoints (Sepolia/Base-Sepolia) before using real funds.

---

⚠️ Gotchas & Troubleshooting

• - Handshake Failures: If request fails with a 402 exit code, the gateway may be down or the merchant's contract is invalid.
• Private Key Format: The CLIENT_PRIVATE_KEY MUST start with 0x.
• Gas vs. Tokens: You can have $1M USDC but if gas_ready is false (low ETH), the transaction WILL fail.
• Exit Codes:

- 2: Invalid arguments. - 3: Auth Failure (Check .env key format). - 4: Network/RPC Failure. - 402: Challenge detected but automated resolution failed.

---

🧪 Sandbox & Testing

Always test against sandbox endpoints first.

• - Mint Test Tokens: INLINECODE23
• Test Merchant (Doodle Wall): https://paynode.dev/api/pom?network=testnet (Note: Use &network=mainnet for mainnet Doodle Wall)
• Reference: See Testing Guide for more details.

---

🔗 References

• - Official Docs: PayNode Documentation
• SDKs: Node.js SDK
• Hub: PayNode Hub
• Testing: Detailed Testing & Examples