A comprehensive C/C++ library implementation of the X402 Payment Protocol for IoT/Embedded Devices, specifically optimized for the ESP32-C6. This library enables resource-constrained embedded devices to participate in blockchain-based payment flows using the X402 standard.

• Full X402 Protocol Support: Complete implementation of the X402 payment protocol specification
• Solana Integration: Native support for Solana blockchain transactions on devnet/mainnet
• SPL Token Transfers: Built-in support for SPL token transfers with Associated Token Accounts (ATA)
• Hardware Wallet Functionality: Secure key management and transaction signing on-device
• WiFi Connectivity: Automated WiFi connection management
• Display Support: LVGL-based UI for payment status and user interaction
• Low Resource Footprint: Optimized for embedded systems with limited RAM/Flash
• Modular Architecture: Clean separation of concerns with reusable components
• Cryptographic Security: Ed25519 signing using libsodium
• SPIFFS Configuration: File-based configuration management

This project is demonstrated using PayAI Echo Merchant, a test service that implements the X402 protocol for Solana Devnet.

The Echo Merchant:

• Returns payment offers in response to HTTP 402 requests
• Accepts SPL token payments on Solana Devnet
• Echoes back premium content upon successful payment
• Provides a complete end-to-end X402 payment flow for testing

Default Configuration:

{
  "payai_url": "https://x402.payai.network/api/solana-devnet/paid-content",
  "solana_rpc_url": "https://api.devnet.solana.com",
  "token_mint": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU"
}

You can use the PayAI Echo Merchant for testing or configure your own X402-compatible merchant endpoint.

• Architecture
• Hardware Requirements
• Software Requirements
• Installation
• Configuration
• Usage
• API Reference
• Protocol Flow
• Project Structure
• Examples
• Troubleshooting
• Contributing
• License

The library follows a modular architecture with clear separation of concerns:

┌─────────────────────────────────────────┐
│           Application Layer             │
│         (app_main.cpp)                  │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│        X402 Payment Client              │
│      (Orchestrates payment flow)        │
└─┬────────┬────────┬────────┬────────────┘
  │        │        │        │
  ▼        ▼        ▼        ▼
┌────┐   ┌────┐   ┌────┐   ┌────┐
│WiFi│   │HTTP│   │Sol │   │Disp│
│Mgr │   │Clnt│   │ana │   │lay │
└────┘   └────┘   └────┘   └────┘
  │        │        │
  ▼        ▼        ▼
┌────────────────────────┐
│   Crypto Utilities     │
│  (Ed25519, Base58/64)  │
└────────────────────────┘

1. X402PaymentClient: Main orchestrator for the payment protocol
2. SolanaClient: Handles Solana RPC communication and transaction building
3. HttpClient: Manages HTTP/HTTPS requests with X-PAYMENT header support
4. WiFiManager: Automated WiFi connection and reconnection
5. CryptoUtils: Cryptographic primitives (Ed25519, Base58, Base64)
6. ConfigManager: SPIFFS-based configuration loading
7. DisplayManager: LVGL-based UI for status and user feedback

• MCU: ESP32-C6
• Display: 240x280 LCD with CST816S touch controller
• Storage: Minimum 4MB Flash
• RAM: Minimum 512KB

• ESP-IDF: v5.0 or higher (Installation Guide)
• CMake: v3.16 or higher
• Python: 3.8 or higher

The following dependencies are automatically managed by ESP-IDF Component Manager:

git clone https://github.com/merttozer/x402-cpp
cd x402-cpp

# Source ESP-IDF environment
. $HOME/esp/esp-idf/export.sh

# Or if using ESP-IDF v5.0+
get_idf

Dependencies are automatically installed via ESP-IDF Component Manager during the build process.

# Set target device (ESP32-C6)
idf.py set-target esp32c6

# Open configuration menu (optional)
idf.py menuconfig

idf.py build

idf.py -p /dev/ttyUSB0 flash monitor

Replace /dev/ttyUSB0 with your actual serial port.

Create a config.json file in the main/spiffs/ directory:

{
  "wifi_ssid": "YourWiFiSSID",
  "wifi_password": "YourWiFiPassword",
  "payer_public_key": [/* 32 bytes as decimal array */],
  "payer_private_key": [/* 32 bytes as decimal array */],
  "payai_url": "https://x402.payai.network/api/solana-devnet/paid-content",
  "solana_rpc_url": "https://api.devnet.solana.com",
  "user_agent": "x402-esp32c6/1.0",
  "token_mint": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
  "token_decimals": 6
}

To generate a new Solana keypair for testing:

# Using Solana CLI
solana-keygen new --outfile keypair.json

# Convert to byte array format for config.json
# (You'll need to write a small script to convert the JSON keypair)

WARNING: Never commit your private keys to version control!

• Use environment variables or secure key storage for production
• Consider implementing secure element integration for production devices
• The current implementation stores keys in SPIFFS (encrypted flash recommended)

#include "x402_client.h"
#include "config_manager.h"

extern "C" void app_main(void) {
    // Initialize SPIFFS
    if (!ConfigManager::init()) {
        return;
    }

    // Load configuration
    X402Config config = {};
    if (!ConfigManager::load("/spiffs/config.json", config)) {
        return;
    }

    // Create client
    X402PaymentClient client(config);
    
    // Initialize environment (WiFi, crypto, display)
    if (!client.init()) {
        return;
    }

    // Run event loop (blocking)
    client.runEventLoop();
}

// Initialize client
X402PaymentClient client(config);
client.init();

// Execute a single payment
bool success = client.executePaymentFlow();

if (success) {
    ESP_LOGI(TAG, "Payment completed successfully!");
} else {
    ESP_LOGE(TAG, "Payment failed!");
}

// Return to idle screen
client.returnToIdleAfterDelay(3000);

The library includes a task-based payment system for handling button presses:

// This is handled automatically in runEventLoop()
// But you can trigger it manually:
client.onPaymentButtonPressed();

X402PaymentClient(const X402Config& config)

Creates a new payment client with the provided configuration.

Initializes the payment client environment:

• Initializes display
• Initializes libsodium cryptography
• Initializes NVS flash storage
• Connects to WiFi

Returns: true on success, false on failure

Executes a complete X402 payment flow:

1. Fetches payment offer (HTTP 402 response)
2. Parses payment requirements
3. Fetches Solana blockhash
4. Builds SPL token transfer transaction
5. Signs transaction with Ed25519
6. Submits payment with X-PAYMENT header
7. Returns premium content on success

Returns: true if payment successful, false otherwise

Starts the main event loop (blocking). Displays idle screen and handles button press events for initiating payments.

Handles payment button press events. Creates a new FreeRTOS task to execute the payment flow asynchronously.

Returns to idle screen after the specified delay.

Parameters:

• delay_ms: Delay in milliseconds before returning to idle

SolanaClient(const std::string& rpcUrl)

Fetches the most recent blockhash from Solana RPC endpoint.

Returns: true on success

Builds a complete Solana transaction with:

• Compute budget instructions
• SPL token transfer instruction
• Multiple signatures support

Derives the Associated Token Account (ATA) address for a given owner and mint.

HttpClient(const HttpClientConfig& config)

Performs GET request expecting HTTP 402 Payment Required response.

Returns: true if 402 response with valid payment offer received

Submits payment by sending X-PAYMENT header with Base64-encoded payment data.

Returns: true if HTTP 200 received with premium content

Static utility class for cryptographic operations.

Converts Base58-encoded string to 32-byte array.

Encodes binary data to Base64 string.

Signs message using Ed25519 algorithm.

Parameters:

• signature[64]: Output signature buffer
• message: Message to sign
• message_len: Message length
• secret_key[32]: Ed25519 private key
• public_key[32]: Ed25519 public key

WiFiManager(const std::string& ssid, const std::string& password)

Initiates WiFi connection. Blocks until connected or timeout.

Returns: true if connected successfully

Checks current WiFi connection status.

Returns: true if currently connected

The X402 payment protocol implementation follows this sequence:

┌─────────┐                 ┌─────────┐                 ┌─────────┐
│  Client │                 │ Merchant│                 │ Solana  │
└────┬────┘                 └────┬────┘                 └────┬────┘
     │                           │                           │
     │  1. GET /resource         │                           │
     ├──────────────────────────>│                           │
     │                           │                           │
     │  2. 402 Payment Required  │                           │
     │     (Payment Offer)       │                           │
     │<──────────────────────────┤                           │
     │                           │                           │
     │  3. getLatestBlockhash    │                           │
     ├───────────────────────────┼──────────────────────────>│
     │                           │                           │
     │  4. Blockhash Response    │                           │
     │<──────────────────────────┼───────────────────────────┤
     │                           │                           │
     │  5. Build Transaction     │                           │
     │  6. Sign with Ed25519     │                           │
     │                           │                           │
     │  7. GET /resource         │                           │
     │     X-PAYMENT: <tx>       │                           │
     ├──────────────────────────>│                           │
     │                           │                           │
     │                           │  8. Verify & Send TX      │
     │                           ├──────────────────────────>│
     │                           │                           │
     │                           │  9. TX Confirmation       │
     │                           │<──────────────────────────┤
     │                           │                           │
     │  10. 200 OK               │                           │
     │      (Premium Content)    │                           │
     │<──────────────────────────┤                           │
     │                           │                           │

1. Initial Request: Client requests protected resource
2. Payment Offer: Merchant returns 402 with payment requirements in JSON
3. Blockhash Fetch: Client fetches recent blockhash from Solana
4. Transaction Build: Client constructs SPL token transfer transaction
5. Signing: Client signs transaction with Ed25519 private key
6. Payment Submission: Client sends signed transaction in X-PAYMENT header
7. Verification: Merchant verifies and broadcasts transaction to Solana
8. Confirmation: Solana confirms transaction on-chain
9. Content Delivery: Merchant returns premium content (HTTP 200)

esp32-x402-client/
├── components/
│   └── x402_protocol/
│       ├── include/
│       │   ├── config_manager.h
│       │   ├── crypto_utils.h
│       │   ├── display_manager.h
│       │   ├── http_client.h
│       │   ├── solana_client.h
│       │   ├── wifi_manager.h
│       │   └── x402_client.h
│       ├── src/
│       │   ├── config_manager.cpp
│       │   ├── crypto_utils.cpp
│       │   ├── display_manager.cpp
│       │   ├── http_client.cpp
│       │   ├── solana_client.cpp
│       │   ├── wifi_manager.cpp
│       │   └── x402_client.cpp
│       └── CMakeLists.txt
├── main/
│   ├── spiffs/
│   │   └── config.json           # Configuration file
│   ├── app_main.cpp
│   ├── idf_component.yml
│   └── CMakeLists.txt
├── CMakeLists.txt
├── partitions.csv
├── sdkconfig
└── README.md

// The default configuration uses PayAI Echo Merchant
config.payai_url = "https://x402.payai.network/api/solana-devnet/paid-content";

X402PaymentClient client(config);
client.init();
client.executePaymentFlow();

// Use your own X402-compatible merchant
config.payai_url = "https://your-merchant.com/api/paid-endpoint";

X402PaymentClient client(config);
client.init();
client.executePaymentFlow();

{
  "solana_rpc_url": "https://api.mainnet-beta.solana.com",
  "token_mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "token_decimals": 6
}

for (int i = 0; i < 5; i++) {
    ESP_LOGI(TAG, "Payment attempt %d", i + 1);
    
    if (client.executePaymentFlow()) {
        ESP_LOGI(TAG, "Payment %d successful", i + 1);
    }
    
    vTaskDelay(pdMS_TO_TICKS(2000)); // Wait 2 seconds between payments
}

Symptoms: ❌ WiFi connection timeout

Solutions:

• Verify SSID and password in config.json
• Check WiFi signal strength
• Ensure 2.4GHz WiFi (ESP32-C6 doesn't support 5GHz)
• Try increasing timeout in x402_client.cpp

const int max_retries = 20;  // Increase from 10

Symptoms: ❌ libsodium initialization failed

Solutions:

• Ensure libsodium component is properly installed
• Check ESP-IDF version (v5.0+ required)
• Verify dependency in idf_component.yml

Symptoms: ❌ Payment submission failed

Solutions:

• Verify merchant URL is accessible
• Check RPC endpoint connectivity
• Ensure sufficient token balance in payer account
• Verify private key matches public key
• Check merchant logs for rejection reason

Symptoms: ❌ Failed to build transaction

Solutions:

• Verify token mint address is correct
• Ensure Associated Token Accounts exist for both sender/receiver
• Check token decimals match the mint's decimals
• Verify blockhash is recent (< 150 blocks old)

Symptoms: Crashes, stack overflows, allocation failures

Solutions:

• Increase task stack size in x402_client.cpp:

xTaskCreate(paymentTaskWrapper, "payment_task", 16384, ...);  // Increase from 8192

• Enable PSRAM if available
• Reduce HTTP buffer sizes if needed

Enable verbose logging for specific components:

esp_log_level_set("x402", ESP_LOG_DEBUG);
esp_log_level_set("SolanaClient", ESP_LOG_DEBUG);
esp_log_level_set("HttpClient", ESP_LOG_DEBUG);

idf.py monitor

Use filters to focus on specific components:

idf.py monitor | grep "x402\|SolanaClient"

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests (if available)
5. Commit with clear messages: git commit -m 'Add amazing feature'
6. Push to your fork: git push origin feature/amazing-feature
7. Open a Pull Request

• Follow ESP-IDF coding standards
• Use meaningful variable and function names
• Add comments for complex logic
• Keep functions focused and modular
• Use C++11/14 features appropriately

• Code compiles without warnings
• All features tested on actual hardware
• Documentation updated (README, code comments)
• No private keys or secrets committed
• CHANGELOG updated (if applicable)

• Add support for multiple token types
• Implement transaction retry logic
• Add detailed error codes
• Improve display UI/UX
• Add OTA update support

• Support for Ethereum/EVM chains
• Hardware secure element integration
• BLE payment initiation
• QR code scanning support
• Multi-signature support

• Lightning Network integration
• Cross-chain atomic swaps
• Payment streaming
• Recurring payment subscriptions
• Mobile app companion

This project is dual-licensed:

Free to use under GNU Affero General Public License v3.0 for open source projects. If you use this software in a network service or distribute it, you must share your source code modifications under AGPL-3.0.

Use AGPL-3.0 if:

• Your project is open source
• You will share all source code
• Personal/educational/research use
• Internal company use (no external distribution)

For commercial products, SaaS, IoT devices, or proprietary use without sharing source code, you must purchase a commercial license.

Use Commercial License if:

• Building commercial IoT products
• Want to keep modifications private
• Embedding in hardware devices for sale
• Running as a paid SaaS service
• Any proprietary/closed-source use

Purchase Commercial License: Contact mertt.ozer@hotmail.com

See LICENSE file for complete terms.

• X402 Protocol Specification - Protocol design
• PayAI Network - Echo Merchant test service for X402 protocol
• Espressif Systems - ESP-IDF framework
• LVGL - Graphics library
• libsodium - Cryptography library
• Solana - Blockchain infrastructure

• X402 Protocol Docs
• ESP-IDF Documentation
• Solana Developer Docs

• GitHub Issues: Report bugs or request features
• Discussions: Ask questions

• Email: mertt.ozer@hotmail.com
• Twitter: @mertt_ozer