Introduction
NEPTUNE is an open-source WiFi-based payment protocol that enables crypto payments over local WiFi networks. It allows ESP8266 devices to host payment endpoints, accept transactions, and verify payments through the Neptune facilitator API.
This documentation will guide you through understanding how Neptune works, setting up your devices, integrating the payment system, and troubleshooting common issues.
How It Works
Overview
Neptune enables peer-to-peer payments over WiFi by turning ESP8266 devices into payment receivers. The system consists of three main components:
ESP8266 Device: Hosts an HTTP server and exposes payment endpoints on your local WiFi network
Mobile/Web App: Discovers devices on the same network and initiates payments
Neptune Facilitator API: Verifies transactions on the blockchain and confirms payment completion
Payment Flow
The payment process follows these steps:
Device Discovery: The ESP8266 connects to your local WiFi network and starts hosting an HTTP server on port 80
Connection: The mobile or web app automatically discovers the device by scanning local IP addresses on the same network
Payment Request: The device sends payment requirements (amount, receiver address, network) via HTTP to the sender's app
Transaction Creation: The sender's app creates a signed blockchain transaction using their wallet
Transaction Exchange: The signed transaction payload is sent back to the ESP8266 over the WiFi connection
Verification: The ESP8266 forwards the transaction to the Neptune facilitator API for verification
Completion: Once verified, the device receives confirmation and completes the payment process
Getting Started
Prerequisites
Before you begin, ensure you have:
An ESP8266 development board (NodeMCU, Wemos D1 Mini, or similar)
Arduino IDE with ESP8266 board support installed
A local WiFi network with internet connectivity
A Solana wallet with testnet funds ( for testing on Base Sepolia )
Basic knowledge of Arduino programming and HTTP protocols
Installation
To set up Neptune on your ESP8266:
Install the ESP8266 board package in Arduino IDE
Install required libraries: ESP8266WiFi, ESP8266WebServer, ArduinoJson
Download the PayNet-Arduino library
Configure your WiFi credentials and payment settings
Upload the code to your ESP8266 device
Architecture
System Components
Neptune consists of several key components:
Neptune-Arduino: Arduino library for ESP8266 that handles payment verification
Neptune-core: Core WiFi HTTP server implementation for ESP8266 devices
Mobile App: React Native application for Android and iOS
Web App: React web application for desktop and mobile browsers
Facilitator API: Backend service that verifies transactions on the blockchain
Network Topology
All devices must be connected to the same local WiFi network. The ESP8266 acts as a server, while mobile/web apps act as clients. Communication happens over HTTP on the local network, with blockchain verification handled by the external Neptune facilitator API.
API Reference
Payment Endpoint
POST /payment
The main endpoint for receiving payment transactions from the sender's app.
Request Body:
Facilitator API
POST https://facilitator.neptune.cloud/verify
Used by the ESP8266 to verify transactions on the blockchain.
Request Body:
Response:
Configuration
WiFi Setup
Configure your WiFi credentials in the Arduino sketch:
Payment Settings
Configure your payment receiver address, network, and amount:
Supported Networks
Currently, Neptune supports:
Base Sepolia (Testnet): For development and testing purposes
Mainnet Support: Coming soon - additional networks are planned for production use
All transactions use USDC (USD Coin) as the payment token.
Security Considerations
Local Network Security
Payments occur over your local WiFi network. Ensure your network is secure and protected with a strong password. All communication between devices happens over HTTP on the local network.
Private Keys
Private keys remain on the user's device. The ESP8266 never sees or stores user keys. Transactions are signed client-side before being sent to the device.
Transaction Verification
All transactions are verified on-chain through the Neptune facilitator API. The ESP8266 only accepts payments after blockchain confirmation, preventing replay attacks and double-spending.
Troubleshooting
Device Not Found
If the mobile/web app cannot discover your ESP8266:
Ensure both devices are on the same WiFi network
Check that the ESP8266 is connected to WiFi (check Serial output)
Verify the HTTP server is running (check Serial output for IP address)
Try manually entering the ESP8266's IP address in the app
Payment Verification Fails
If payment verification fails:
Check that the transaction hash is correct
Verify the transaction has been confirmed on the blockchain
Ensure the receiver address matches your configured address
Check that the payment amount meets the minimum requirement
Verify internet connectivity on the ESP8266 (required for API verification)
WiFi Connection Issues
If the ESP8266 cannot connect to WiFi:
Double-check SSID and password in your code
Ensure your WiFi network is 2.4GHz (ESP8266 doesn't support 5GHz)
Check signal strength at the device location
Try resetting the ESP8266 and reconnecting
Examples
Basic Payment Receiver
See the Developers section on the homepage for a complete example of an ESP8266 payment receiver implementation. The code demonstrates:
WiFi connection setup
HTTP server initialization
Payment endpoint handling
Transaction verification via facilitator API
Device activation after successful payment
Getting Help
For additional support and resources:
Join our community on X (Twitter) @Neptunedotzone
Review the source code and examples
Contact us through official channels listed on our website & X
