Skip to content

QUICK_REFERENCE.md

Latest commit

 

History

History
347 lines (258 loc) · 5.3 KB

QUICK_REFERENCE.md

File metadata and controls

347 lines (258 loc) · 5.3 KB

📖 QUICK REFERENCE

Repository note, April 21, 2026: this is the original peether-protocol workspace. Current public release work has moved to:

Use the split repositories for current endpoint reference work. The content below is retained as legacy/reference documentation unless updated by a later commit.

Developer cheat sheet. Copy-paste ready!

API Endpoints

Quotes

# Get quote
POST /api/v1/quote
{ "fareAmount": 500, "currency": "PKR", "promoCode": "SAVE10" }

# Check quote
GET /api/v1/quote/:id

Payments

# Execute payment
POST /api/v1/pay
{ "quoteId": "quote_123", "riderAddress": "0x...", "driverAddress": "0x..." }

# Check payment
GET /api/v1/pay/:txId

Withdrawals

# Initiate withdrawal
POST /api/v1/payout
{ "driverId": "driver_123", "ptdtAmount": 10.5, "gateway": "jazzcash", "recipientAccount": "123456789" }

# Check withdrawal
GET /api/v1/payout/:id

Operator

# Get dashboard
GET /api/v1/operator/me

# Get stats
GET /api/v1/operator/stats

Analytics

# Network metrics
GET /api/v1/analytics/network

# Operator metrics
GET /api/v1/analytics/operator/:operatorId

# Driver metrics
GET /api/v1/analytics/driver/:driverId

Health

# Check API status
GET /api/v1/health

Headers Required

# All requests (except /health and /webhook)
Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json

# Alternative
X-API-Key: <API_KEY>
Content-Type: application/json

Response Codes

Code Meaning
200 Success
201 Created
400 Bad request
401 Unauthorized
429 Rate limited
500 Server error

Error Response

{
  "error": "Error message here",
  "timestamp": "2026-01-26T11:20:00Z",
  "path": "/api/v1/quote",
  "method": "POST"
}

Exchange Rates (Static)

1 PTDT = 200 PKR
1 PTDT = 30 KES
1 PTDT = 600 NGN
1 PTDT = 0.032 USD

Payment Gateways

Gateway      | Currency | Country
-------------|----------|--------
jazzcash     | PKR      | Pakistan
mpesa        | KES      | Kenya
flutterwave  | NGN      | Nigeria
wise         | USD      | Global

Fee Distribution

Total: 100%
  └─ Driver: 95%
  └─ Burn: 1%
  └─ Staking: 1%
  └─ Platform: 3%

Database Tables

operators
driver
quotes
transactions
withdrawals
driver_earnings
analytics

Environment Variables

# Server
NODE_ENV=production
PORT=3000
LOG_LEVEL=info

# Security
JWT_SECRET=your_secret
API_KEY=your_api_key
CORS_ORIGIN=http://localhost:3000

# Database
DATABASE_URL=postgresql://user:pass@host:5432/db

# Blockchain
BSC_RPC_URL=https://bsc-dataseed.binance.org
PTDT_CONTRACT_ADDRESS=0x...

# Gateways
JAZZCASH_API_KEY=key
MPESA_API_KEY=key
FLUTTERWAVE_API_KEY=key
WISE_API_KEY=key

# Rates
PTDT_RATE_PKR=200
PTDT_RATE_KES=30
PTDT_RATE_NGN=600
PTDT_RATE_USD=0.032

File Structure

src/
  ├── endpoints/     (7 routes)
  ├── services/      (4 business logic)
  ├── middleware/    (4 request processing)
  ├── utils/         (3 helpers)
  ├── database/      (schema)
  └── index.ts       (main entry)

NPM Scripts

npm run dev        # Start dev server
npm run build      # Compile TypeScript
npm start          # Run compiled app
npm test           # Run tests
npm run lint       # Check code style
npm run lint:fix   # Fix style issues

Docker Commands

# Build image
docker build -t ptdt-api .

# Run container
docker run -p 3000:3000 ptdt-api

# Full stack
docker-compose up

# View logs
docker-compose logs -f api

# Stop
docker-compose down

Common Tasks

Get JWT Token

node -e "console.log(require('jsonwebtoken').sign({id:'user'}, 'secret'))"

Test API

# Health check
curl http://localhost:3000/api/v1/health

# With auth
curl -H "Authorization: Bearer TOKEN" http://localhost:3000/api/v1/operator/me

View Logs

# Dev
npm run dev

# Production
pm2 logs ptdt-api

# Docker
docker-compose logs -f api

Database

# Connect
psql $DATABASE_URL

# List tables
\dt

# Run migration
psql $DATABASE_URL < src/database/schema.sql

Performance Tips

  • Index frequently queried columns
  • Cache analytics results
  • Use connection pooling
  • Enable gzip compression
  • Set appropriate rate limits
  • Monitor database queries

Security

  • Use HTTPS in production
  • Rotate JWT secrets monthly
  • Sanitize user input (Joi handles)
  • Use environment variables
  • Enable CORS correctly
  • Validate webhook signatures
  • Rate limit all endpoints

Monitoring

# CPU/Memory
pm2 monit

# Logs
pm2 logs

# Status
pm2 status

Useful URLs

Support

  • Issue? Open GitHub issue
  • Question? Check README.md
  • Lost? Read START_HERE.md
  • Deploy? Follow DEPLOYMENT.md
  • Integrate? Follow INTEGRATION_GUIDE.md

Last updated: 2026-01-26 | Version: 1.0.0