awesome-x402

Awesome X402 exposes an MCP server that enables autonomous, HTTP 402-based payments in the x402 ecosystem. The server acts as a gateway for agents and clients to request, verify, and settle payments using the HTTP 402 status flow, supporting instant settlement and programmable payment requirements. Typical workflows include integrating with AI agents or automation layers that can trigger payments for on-demand services, paywalled content, or API-driven micropayments. Tools offered by the MCP setup include payment request generation, verification hooks for incoming payments, and middleware-style integration points to plug into existing stacks. The goal is to enable seamless, internet-native payments where agents can autonomously authorize and settle transactions with minimal friction, leveraging USDC on supported networks (e.g., Base).

Prerequisites:

• Node.js (14.x or newer) and npm installed on your system
• Access to the repository containing the AWESOME-X402 MCP server code

1. Clone the repository: git clone https://github.com/xpaysh/awesome-x402.git cd awesome-x402

2. Install dependencies: npm install

3. Configure environment variables (see additional_notes for details):

   • Create a .env file or export vars in your environment: X402_PAYMENTS_PUBLIC_KEY="your-public-key" X402_PAYMENTS_PRIVATE_KEY="your-private-key" X402_API_BASE_URL="https://api.x402.example.org"

4. Start the MCP server: npm run start

5. Verify the server is running: curl -i http://localhost:PORT/health

Notes:

• If the project uses a different startup script, adjust the start command in package.json or run node server.js as appropriate.
• For deployment, you may containerize this service using Docker as an alternative to local runs.

Tips and common issues:

• Ensure your X402 keys are valid and have the necessary permissions for payment requests and settlements.
• If you encounter CORS or network errors, verify the API_BASE_URL and any required whitelisting in your environment.
• Review the protocol docs linked in the README for understanding payment payload structures and verification steps.
• If using MCP integration with AI agents, ensure the agent's environment has access to the necessary keys and endpoints to perform autonomous payments.
• Consider setting up logging around payment requests, verifications, and settlements to aid debugging in production.
• When migrating between networks (e.g., Base vs. testnets), update the API_BASE_URL and any network-specific configurations accordingly.