x402 Mock Server

Mock x402-enabled API server for testing (protocol compliant)
Join our community

Overview

This node implements a mock x402-enabled API server that listens for HTTP requests on a specified webhook path and requires payment in SOL (Solana cryptocurrency) to access the mock API response. It auto-generates a unique Solana wallet on the first request and verifies incoming payments either by signature verification or full on-chain settlement. The node is useful for testing payment-gated APIs or services that require Solana-based payments before granting access. For example, developers can simulate a paywall for API access, ensuring clients pay a specified amount in SOL before receiving the mock response data.

Use Case Examples

  1. A developer wants to test an API that requires payment in Solana tokens before returning data. They configure this node to listen on a webhook path, specify the payment amount, and provide mock response data. When a client sends a request with the correct payment, the node verifies the payment and returns the mock data.
  2. A service provider wants to simulate a pay-per-use API on the Solana devnet. They use this node to generate a wallet, set the payment amount, and enable on-chain verification to ensure payments are settled on the blockchain before responding.

Properties

Name Meaning
šŸ’” How to Find Your Wallet Address Notice explaining how to find and fund the auto-generated wallet address.
HTTP Method The HTTP method (GET, POST, PUT, DELETE) that the webhook listens for.
Path The webhook path to listen for incoming HTTP requests.
Network The Solana network (Mainnet or Devnet) to accept payments on.
Payment Amount (smallest units) The required payment amount in the smallest units of the token (e.g., 10000 units = 0.01 USDC with 6 decimals).
Description Description of the resource or service being accessed.
Mock Response The JSON data to return after successful payment verification.
Verify On-Chain Boolean flag to enable full on-chain settlement verification instead of just signature verification. Requires funding the mock server wallet.
Max Timeout (seconds) Maximum time allowed for the client to respond with payment.

Output

JSON

  • event - Event type indicating the current state (e.g., payment_required, payment_verified_offchain, payment_settled).
  • mockServerWallet
    • address - The Solana wallet address used by the mock server.
    • network - The Solana network (mainnet or devnet) of the wallet.
    • createdAt - Timestamp when the wallet was created.
    • solBalance - Current SOL balance of the wallet (if available).
    • explorerUrl - URL to view the wallet on the Solana explorer.
  • paymentRequested
    • amount - The payment amount requested in smallest units.
    • amountDisplay - The payment amount displayed in USDC format.
    • description - Description of the payment request.
  • verification
    • method - Method of payment verification (off-chain or on-chain).
    • status - Status of the payment verification.
    • note - Additional notes about the verification.
  • settlement
    • transactionHash - Transaction hash of the on-chain settlement.
    • explorerUrl - URL to view the settlement transaction on Solana explorer.
    • status - Status of the settlement transaction.
  • mockResponse - The mock response data returned after successful payment verification or settlement.
  • message - Human-readable message about the current event or status.

Dependencies

  • Solana blockchain network access
  • An API key or wallet management for Solana transactions

Troubleshooting

  • If no payment header is found in the request, the node responds with HTTP 402 Payment Required and instructions to pay the specified amount to the generated wallet address.
  • If payment verification fails, the node responds with HTTP 400 and details about the invalid payment reason. Users should ensure the payment matches the expected amount and recipient.
  • If on-chain settlement is enabled but fails, the node responds with HTTP 400 and an error message. Ensure the mock server wallet is funded with SOL to cover transaction fees.
  • Users may need to check the Solana explorer URLs provided in logs and output to verify wallet balances and transaction statuses.
  • If the node does not generate a wallet address, ensure the node has received at least one request to trigger wallet generation.

Links

Discussion