x402 Client

Make HTTP requests to x402-enabled APIs with automatic payment handling
Join our community

Overview

The x402 Client node enables making HTTP requests to x402-enabled APIs with automatic handling of required payments using Solana wallets. It supports multiple wallet sources including saved wallets, private keys, external wallet manager nodes, or auto-generated wallets. The node checks wallet balances, manages payments when required by the API, and supports different payment protocol formats. This node is useful for workflows that interact with APIs requiring blockchain-based payments, such as decentralized finance (DeFi) services or pay-per-use APIs.

Use Case Examples

  1. Automatically pay for API requests using a saved Solana wallet managed by a Wallet Manager node.
  2. Use a private key directly to authorize and pay for API requests on Solana mainnet or devnet.
  3. Auto-generate a new wallet per node execution for isolated payment handling.
  4. Send GET, POST, PUT, or DELETE requests to x402-enabled endpoints with custom headers and JSON bodies, with optional automatic payment handling.

Properties

Name Meaning
Wallet Source Select how to provide wallet credentials for payments, e.g., saved wallet, private key, external wallet manager, or auto-generated wallet.
Saved Wallet Notice Information about setting up a saved wallet using the Wallet Manager node.
Private Key Notice Instructions for entering a private key for wallet access.
Network (Private Key) Select Solana network (mainnet or devnet) when using a private key.
Private Key The Solana wallet private key in JSON array or base58 string format.
Wallet Manager Notice Instructions for connecting Wallet Manager node output.
Auto-Generate Notice Warning about auto-generating a unique wallet per node.
Network (Auto-Generate) Select Solana network when auto-generating a wallet.
Resource URL The URL of the x402-enabled API endpoint to send requests to.
HTTP Method The HTTP method to use for the request (GET, POST, PUT, DELETE).
Request Body The JSON body to send with POST or PUT requests.
Headers Custom HTTP headers to include in the request.
Auto-Pay Whether to automatically pay when the API requires payment.
Max Payment Amount (USDC) Maximum USDC amount willing to pay per request as a safety limit.
Protocol Format Payment protocol format to use: official X-402 or legacy signed transaction.
Options Additional options such as showing transaction details, clearing saved wallet, or resetting wallet.

Output

JSON

  • json
    • _x402Payment
      * amount - The amount paid in USDC if a payment was made.
      * currency - Currency of the payment, typically USDC.
      * recipient - Recipient address of the payment.
      * sender - Sender wallet address.
      * network - Solana network used for the payment.
      * timestamp - Timestamp of the payment.
      * scheme - Payment scheme used, e.g., 'exact' (optional, shown if transaction details are included).
    • error - Error message if the request or payment failed.
    • walletAddress - Wallet address used when an error occurs.
    • timestamp - Timestamp of the error event.

Dependencies

  • Solana wallet management utilities
  • x402 client utilities for payment handling

Troubleshooting

  • No saved wallet found error: Ensure the Wallet Manager node is connected and run once to save the wallet before using saved wallet mode.
  • Invalid private key format: Provide the private key as a JSON array or base58 string as required.
  • Insufficient balance errors: Fund the wallet with USDC and SOL tokens before running the workflow.
  • Payment required but auto-pay disabled: Enable auto-pay or fund the wallet to proceed.
  • Network mismatch error: Reset the wallet or select the correct network matching the wallet's creation network.
  • RPC errors when fetching balances: Check Solana RPC endpoint availability or wallet address correctness.

Links

Discussion