x402 Starter Kit

A template for creating agents with x402 payment support on Base. This project demonstrates how to build AI-powered tools with integrated payment handling using the OpenTool framework. The template defaults to the DuckAI facilitator and can be hosted on OpenPond.

Quick Start

1. Create your environment file:

   cp .env.example .env
   

   Update the file with your required credentials:

   • WALLET_ADDRESS – Your wallet address for receiving payments
   • DEPLOYED_URL – Base URL (e.g. https://your-app.openpond.live) used in x402 payment metadata
   • Additional API keys as needed for the OpenPond gateway
   • Optional overrides:
     • X402_FACILITATOR_URL – Custom facilitator base (defaults to https://facilitator.x402.rs/x402)
     • X402_NETWORK – Network slug (base, base-sepolia, etc.)
     • X402_ASSET_ADDRESS – ERC20 token address if the default for the selected network should be overridden

2. Install dependencies:

   bun install
   

3. Build the project:

   npx opentool build
   

4. Run the project:

   npx opentool dev
   

5. Exercise the paywall end-to-end with the helper script (keep npx opentool dev running):

   PRIVATE_KEY=0xyour_private_key \
   bunx tsx scripts/test-x402-client.ts
   

   The script performs the full x402 flow: it makes the initial request, captures the 402 response, signs the transfer authorization, and retries with the X-PAYMENT header. Optional overrides include PAYMENT_URL (defaults to http://localhost:7000/ai-oracle), RPC_URL for a different Ethereum RPC, and QUESTION to change the payload. Successful runs print the payment details, HTTP status, and the paid response body.