Technical Specifications

Bluetooth (BLE) Protocol

Data Transfer Protocol

1. Device Advertisement

ESP32 advertises with device name containing payment info:

Device Name Format: "x402-[DEVICE_NAME]"
Advertisement Data: Service UUID + Device Name
Scan Response: Additional device info if needed

2. Connection Handshake

3. Payment Requirements JSON

{
  "network": "base-sepolia",
  "payTo": "0xa78eD39F695615315458Bb066ac9a5F28Dfd65FE",
  "maxAmountRequired": "1000000",
  "logoURL": "https://example.com/logo.jpg",
  "description": "Coffee machine payment",
  "options": ["Espresso", "Americano", "Latte"],
  "dynamicPricing": true,
  "recurring": {
    "enabled": true,
    "intervalSeconds": 30
  }
}

4. Payment Response

5. Payment Payload JSON

{
  "network": "base-sepolia",
  "from": "0x742d35Cc6C3C0532925a3b8D345A2E5E0E2F",
  "to": "0xa78eD39F695615315458Bb066ac9a5F28Dfd65FE",
  "amount": "1500000",
  "signature": "0x1c2b4d...",
  "nonce": 42,
  "selectedOptions": ["Latte"],
  "timestamp": 1729814400
}

ESP32 Memory Management

Multi-threading Architecture

x4Pay-core uses FreeRTOS tasks for concurrent operation:

Code Example: Task Creation

void X402Ble::begin() {
  // Set active instance for worker callbacks
  s_active = this;
  NimBLEDevice::init(device_name_.c_str());
  NimBLEDevice::setDeviceName(device_name_.c_str());
  NimBLEDevice::setPower(ESP_PWR_LVL_P7);
  NimBLEDevice::setSecurityAuth(false, false, false);
  NimBLEDevice::setMTU(150);

  // Start payment verification worker with large stack on core 1
  PaymentVerifyWorker::begin(/*stackBytes=*/8192, /*prio=*/3, /*core=*/1);

  pServer = NimBLEDevice::createServer();
  pServer->setCallbacks(new ServerCallbacks());

  pService = pServer->createService(SERVICE_UUID);
}

Mobile App Connection Process

React Native Implementation

Key Code: Device Connection

// Scan for devices
const scanForDevices = () => {
  bleManager.startDeviceScan(
    [NORDIC_UART_SERVICE_UUID],
    { allowDuplicates: false },
    (error, device) => {
      if (device?.name?.startsWith('x402-')) {
        bleManager.stopDeviceScan();
        connectToDevice(device);
      }
    }
  );
};

// Connect and setup
const connectToDevice = async (device) => {
  const connected = await device.connect();
  await connected.discoverAllServicesAndCharacteristics();
  
  // Subscribe to TX characteristic for incoming data
  connected.monitorCharacteristicForService(
    NORDIC_UART_SERVICE_UUID,
    TX_CHARACTERISTIC_UUID,
    (error, characteristic) => {
      const data = JSON.parse(base64Decode(characteristic.value));
      handlePaymentRequirements(data);
    }
  );
};

Web App Implementation

Key Code: Web Bluetooth

const connectToDevice = async () => {
  const device = await navigator.bluetooth.requestDevice({
    filters: [{ services: ['6e400002-b5a3-f393-e0a9-e50e24dcca9e'] }]
  });
  
  const server = await device.gatt.connect();
  const service = await server.getPrimaryService('6e400002-b5a3-f393-e0a9-e50e24dcca9e');
  
  // Get characteristics
  const txCharacteristic = await service.getCharacteristic('6e400003-b5a3-f393-e0a9-e50e24dcca9e');
  const rxCharacteristic = await service.getCharacteristic('6e400004-b5a3-f393-e0a9-e50e24dcca9e');
  
  // Listen for data from device
  await txCharacteristic.startNotifications();
  txCharacteristic.addEventListener('characteristicvaluechanged', (event) => {
    const data = new TextDecoder().decode(event.target.value);
    handlePaymentRequirements(JSON.parse(data));
  });
};

Security & Privacy

Data Privacy

Supported Blockchain Networks

Performance Metrics

Throughput Limits