💳 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. 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...
   

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

Expected check-wallet Output:

{
  "status": "success",
  "address": "0x...",
  "eth": 0.01,
  "usdc": 100.0,
  "checks": {
    "gas_ready": true, // Has > 0.001 ETH for gas
    "tokens_ready": true, // Has USDC for payments
    "can_pay": true // Ready for x402 flow
  }
}

🛠️ 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: bun run mint-test-tokens --json
• 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