SokoWeb - Decentralized Commerce Network
🌐 Overview
SokoWeb is a distributed commerce platform that enables peer-to-peer product and service listings with powerful search and discovery capabilities. Built on decentralized technology, it allows users to create, manage, and discover listings across the network.
🚀 Quick Start Guide
Install and launch SokoWeb with these simple commands:
pip install sokoweb
# Start in interactive mode
sokoweb-up
# Or start in detached mode
sokoweb-up -d
Configuration
During startup, you'll be prompted to configure:
| Parameter | Default | Description |
|---|---|---|
| NODE_PORT | 8000 | HTTP API port |
| NODE_TCP_PORT | 8500 | TCP communication port |
| ADVERTISE_IP | localhost | Your node's public address |
Important: For full network participation, use a public IP or domain name. Localhost mode works for testing but won't connect to the wider network. Note that tunneling services like Ngrok are not compatible as SokoWeb requires direct UDP and TCP access.
💻 System Requirements
- Python 3.9 or higher
- Docker 27.3.1 or higher
- docker compose 2.29.7 or higher
📚 API Reference
Authentication
Create a New User Account
curl -X POST http://localhost:8000/register \
-H "Content-Type: application/json" \
-d '{
"username": "alice",
"password": "alice123",
"email": "alice@example.com",
"full_name": "Alice Wonderland",
"phone_number": "+254712345678",
"scopes": ["products:write", "products:read", "credits:manage"]
}'
Obtain Access Token
curl -X POST http://localhost:8000/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "username=alice&password=alice123&scope=products:write products:read credits:manage"
Available Permission Scopes
| Scope | Description |
|---|---|
| products:write | Create and modify product listings |
| products:read | View product listings |
| credits:manage | Purchase and manage account credits |
| categories:write | Suggest new product categories |
| categories:read | View available categories |
Product Management
Create a New Product Listing
curl -X POST http://localhost:8000/products \
-H "Authorization: Bearer <your_token>" \
-H "Content-Type: application/json" \
-d '{
"core": {
"name": "Smartphone",
"category": "Electronics",
"price": 500.00,
"description": "New smartphone",
"seller_phone": "+254712345678",
"shop_name": "Tech Store",
"seller_location": [-1.2921, 36.8219]
},
"extended": {
"storage_duration_days": 1,
"tags": ["samsung S21","5G"],
"metadata": { "color": "black" }
}
}'
Upload Product Images
curl -X POST http://localhost:8000/products/{product_id}/image \
-H "Authorization: Bearer <your_token>" \
-F "image=@/path/to/image.jpg"
Product Retrieval
Get Product by ID
curl http://localhost:8000/products/{product_id} \
-H "Authorization: Bearer <your_token>"
Search by Category or Shop
curl "http://localhost:8000/products?category=Electronics&shop_name=Tech%20Store" \
-H "Authorization: Bearer <your_token>"
Location-Based Search
Find products within a specific radius (in kilometers):
curl "http://localhost:8000/products?latitude=-1.2921&longitude=36.8219&radius_km=10" \
-H "Authorization: Bearer <your_token>"
Combined Search Parameters
Combine multiple search criteria for precise results:
curl "http://localhost:8000/products?category=Electronics&latitude=-1.2921&longitude=36.8219&radius_km=5" \
-H "Authorization: Bearer <your_token>"
Image Retrieval
Get Primary Product Image
curl "http://localhost:8000/products/{product_id}/image" \
-H "Authorization: Bearer <your_token>"
This endpoint returns the raw image data that can be:
- Saved directly to a file using curl's
-ooption - Viewed in tools like Postman that can render binary responses
Download All Product Images
curl "http://localhost:8000/products/{product_id}/images" \
-H "Authorization: Bearer <your_token>" \
--output images_{product_id}.zip
This endpoint returns a ZIP archive containing all images associated with the product. The response is binary data that should be saved to disk and opened with any ZIP-compatible program.
Credits System
Check Account Balance
curl http://localhost:8000/credits/balance \
-H "Authorization: Bearer <your_token>"
Purchase Additional Credits
curl -X POST http://localhost:8000/credits/purchase \
-H "Authorization: Bearer <your_token>" \
-H "Content-Type: application/json" \
-d '{
"amount": 100,
"phone_number": "+254712345678"
}'
Marketplace
The marketplace allows node operators to sell earned credits to other users.
List All Available Credit Offers
curl http://localhost:8000/market/offers \
-H "Authorization: Bearer <your_token>"
Create a New Credit Sale Offer
curl -X POST http://localhost:8000/market/offer \
-H "Authorization: Bearer <your_token>" \
-H "Content-Type: application/json" \
-d '{
"amount": 50,
"price_per_credit": 1
}'
Note: Only credits beyond the free threshold (100 credits) can be sold.
Purchase Credits from an Offer
curl -X POST http://localhost:8000/market/buy/{offer_id} \
-H "Authorization: Bearer <your_token>" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+254712345678"
}'
This initiates an M-Pesa STK push payment. Once the payment is confirmed, credits are transferred from the seller to the buyer.
Category Management
# Suggest a new product category
curl -X POST http://<your-public-ip>:8000/categories/suggest \
-H "Authorization: Bearer <your_token>" \
-H "Content-Type: application/json" \
-d '{
"category_name": "Smart Home"
}'
# List all available categories
curl http://localhost:8000/categories \
-H "Authorization: Bearer <your_token>"
Note: When deploying to production, replace
localhostwith your server's public IP address or domain name.
🔧 Network Management
Monitor and manage your SokoWeb node:
- View running containers:
docker ps - Shut down your node:
sokoweb-down
👥 Contributing
SokoWeb is an open-source project and welcomes contributions from the community. Feel free to submit issues, feature requests, or pull requests.
📄 License
SokoWeb is released under the MIT License.
1 maintainer
Metadata
1 maintainer
Release files for sokoweb 0.1.50
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| sokoweb-0.1.50.tar.gz | 53.7 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| sokoweb-0.1.50-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 112.9 kB
Release files / sokoweb-0.1.50.tar.gz
| Download URL | sokoweb-0.1.50.tar.gz |
|---|---|
| Size | 53.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
dbdb456ff32cdcff56823323bb545b6e010cad2db17887c766a91d2f82796b1c
|
|
BLAKE2b-256 checksum How to use checksums |
93705efe9a370c77831c4cb3a7d2df8383997eb08e85422e30fd0fae4c44c849
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.10.12
|
Release files / sokoweb-0.1.50-py3-none-any.whl
| Download URL | sokoweb-0.1.50-py3-none-any.whl |
|---|---|
| Size | 59.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9920c6f6b7038d4d80d16415895b975026f214e0c4062df2c5da59a02b695009
|
|
BLAKE2b-256 checksum How to use checksums |
91b96b3c8f8005c4a86b52de8c0108d57d8e00db8d80498b7d32c9e2e251658f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.10.12
|
Security for sokoweb 0.1.50
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
