API Documentation

This documentation provides a ioprehensive guide to PeoPay’s APIs, enabling developers to integrate with the PeoPay ecosystem. The APIs allow seamless access to core features such as user management, P2P payments, staking, governance, and Dynamic Contribution Scoring (DCS).

1. Overview

PeoPay APIs enable developers to: - Authenticate users and manage accounts. - Initiate and track transactions, including crypto-to-mobile money conversions. - Access staking, rewards, and referral systems. - Participate in governance through voting and proposal submission. - Monitor user contributions and penalties via DCS.

Base URL

• Production Environment: https://api.peopay.io/v1
• Sandbox Environment: https://sandbox.api.peopay.io/v1

2. Authentication

Endpoint: Login

Authenticate users and retrieve a session token for subsequent API requests.

• Method: POST
• URL: /auth/login

Request

{
  "username": "user@example.io",
  "password": "securePassword123"
}

Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600
}

Endpoint: Register

Create a new user account.

• Method: POST
• URL: /auth/register

Request

{
  "username": "user@example.io",
  "password": "securePassword123",
  "mobile_number": "+1234567890"
}

Response

{
  "message": "User registered successfully. Please verify your email."
}

3. User Management

Endpoint: Get User Profile

Retrieve user details, including DCS score and staking status.

• Method: GET
• URL: /user/profile
• Headers: Authorization: Bearer <token>

Response

{
  "username": "user@example.io",
  "mobile_number": "+1234567890",
  "dcs_score": 1250,
  "staking_balance": 500,
  "referrals": 10
}

4. Transactions

Endpoint: Send P2P Payment

Send a peer-to-peer payment using PeoCoin.

• Method: POST
• URL: /transactions/p2p

Request

{
  "recipient": "recipient@example.io",
  "amount": 50,
  "message": "Payment for services"
}

Response

{
  "transaction_id": "abc123",
  "status": "success",
  "timestamp": "2024-01-01T12:00:00Z"
}

Endpoint: Crypto-to-Mobile Conversion

Convert crypto to mobile money.

• Method: POST
• URL: /transactions/convert

Request

{
  "amount": 100,
  "currency": "PEO",
  "mobile_number": "+1234567890"
}

Response

{
  "conversion_id": "conv123",
  "status": "processing",
  "mobile_money_balance": 1000,
  "exchange_rate": 1.2
}

5. Staking

Endpoint: Stake PeoCoin

Stake PeoCoin to earn rewards.

• Method: POST
• URL: /staking/stake

Request

{
  "amount": 200
}

Response

{
  "staking_id": "stake123",
  "status": "success",
  "message": "You have successfully staked 200 PEO."
}

Endpoint: Get Staking Rewards

Retrieve current staking rewards.

• Method: GET
• URL: /staking/rewards
• Headers: Authorization: Bearer <token>

Response

{
  "total_rewards": 50,
  "next_payout": "2024-01-15T00:00:00Z"
}

6. Governance

Endpoint: Submit Proposal

Submit a governance proposal.

• Method: POST
• URL: /governance/proposals

Request

{
  "title": "Proposal to Increase Staking Yields",
  "description": "This proposal suggests increasing staking yields by 5% to encourage participation.",
  "category": "Staking",
  "attachments": []
}

Response

{
  "proposal_id": "prop123",
  "status": "submitted",
  "message": "Your proposal has been submitted for review."
}

Endpoint: Vote on Proposal

Cast a vote on an active proposal.

• Method: POST
• URL: /governance/vote

Request

{
  "proposal_id": "prop123",
  "vote": "yes"
}

Response

{
  "status": "success",
  "message": "Your vote has been recorded."
}

7. Dynamic Contribution Scoring (DCS)

Endpoint: Get DCS Score

Retrieve the user’s DCS score.

• Method: GET
• URL: /dcs/score
• Headers: Authorization: Bearer <token>

Response

{
  "dcs_score": 1350,
  "breakdown": {
    "transactions": 600,
    "staking": 500,
    "governance": 200,
    "referrals": 50,
    "penalties": -50
  }
}

8. Error Codes

iomon Errors

9. Rate Limits

• Free Tier: 100 requests per minute.
• Pro Tier: 500 requests per minute.

Headers

• Rate limit status is returned in the headers:

  X-RateLimit-Limit: 100
  X-RateLimit-Remaining: 80
  X-RateLimit-Reset: 1683721200

10. Examples

Send a Payment (cURL)

curl -X POST https://api.peopay.io/v1/transactions/p2p \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
  "recipient": "recipient@example.io",
  "amount": 50,
  "message": "Payment for services"
}'

Next Steps

1. Test API endpoints in the sandbox environment.
2. Follow our Developer Guide for integration tutorials.
3. Join our iomunity forum for support.