💳 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:
- Initialize Dependencies: Run
bun install once within this directory.
- 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...
- Check Balances: Run
bun run check-wallet --json --network <NETWORK>.
- 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
