MyPayVerse API Documentation

A unified crypto payment and yield infrastructure. MyPayVerse provides a secure infrastructure for onboarding users, managing crypto transactions, and delivering investment yields. Use this guide to integrate programmably with our REST API.

Base URL: https://api.mypayverse.comContact: build@MyPayVerse.com

Quick Start

1. Create an account via the dashboard or using the /api/auth/register endpoint.
2. Verify the user with OTP and capture the bearer token from /api/auth/verify-otp.
3. Attach Authorization: Bearer <token> to access protected resources such as profile, finance, and contact endpoints.

Useful Links

MyPayVerse Console – manage API keys, view balances, and monitor activity.
API Reference GitHub – track documentation updates or open integration requests.

Authentication

JWT Bearer Token

Authenticate by exchanging credentials for a JWT access token. Include the token in the Authorization header when calling protected resources.

Flow

1Register a user with `POST /api/auth/register` and verify the OTP, or onboard users via the admin dashboard.
2Authenticate with `POST /api/auth/login` to receive a JWT.
3Include the token on subsequent requests using the `Authorization: Bearer <token>` header.

Details

Token Time-to-Live: 7 days

Tokens are scoped to the authenticated user. Refresh tokens are not yet supported.
Requests made without a valid bearer token return HTTP 401.

Rate Limiting

Usage Policy

Soft limits at 60 requests/minute per IP. Bursts are tolerated, but abusive traffic is throttled.

X-RateLimit-Limit

Total number of requests allowed in the current window.

X-RateLimit-Remaining

Requests remaining in the current window.

Retry-After

Seconds to wait before retrying once the limit is exceeded.

Authentication

Endpoints for user registration, verification, and token issuance. All responses include meaningful error messages for failed operations.

4 endpoints

POST

/api/auth/register

Register User

Creates a new user, generates a managed wallet address, and triggers an email OTP challenge.

Body Parameters

Name	Type	Description	Example
emailRequired	string (email)	User email address.	satoshi@mypayverse.com
passwordRequired	string	Password must be at least 6 characters.	Sup3rStrong!
countryRequired	string	ISO country name.	Singapore
mobileRequired	string	International phone number.	+6581234567

curl -X POST https://api.mypayverse.com/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "satoshi@mypayverse.com",
    "password": "Sup3rStrong!",
    "country": "Singapore",
    "mobile": "+6581234567"
  }'

Endpoint: /api/auth/register

Responses

HTTP 201

Registration succeeded and OTP sent.

{
  "message": "User registered successfully. Please verify your email with the OTP sent.",
  "userId": "664f8f6b9aae7cd290a9d994",
  "emailSent": true
}

HTTP 400

Validation failed (missing fields or password length).

{
  "error": "All fields are required"
}

HTTP 409

Email already exists.

{
  "error": "User already exists with this email"
}

POST

/api/auth/resend-otp

Resend OTP

Issues a new OTP code when the previous verification window expires.

Body Parameters

Name	Type	Description	Example
emailRequired	string (email)	Previously registered email.	satoshi@mypayverse.com

curl -X POST https://api.mypayverse.com/api/auth/resend-otp \
  -H "Content-Type: application/json" \
  -d '{ "email": "satoshi@mypayverse.com" }'

Endpoint: /api/auth/resend-otp

Responses

HTTP 200

OTP successfully re-issued.

{
  "message": "OTP sent successfully"
}

HTTP 404

User email not found.

{
  "error": "User not found"
}

HTTP 400

User already verified.

{
  "error": "User is already verified"
}

POST

/api/auth/verify-otp

Verify OTP

Validates the OTP challenge, upgrades the user to verified, and returns a JWT for immediate use.

Body Parameters

Name	Type	Description	Example
emailRequired	string (email)	Email linked to the OTP.	satoshi@mypayverse.com
otpRequired	string	6-digit OTP received via email.	941203

curl -X POST https://api.mypayverse.com/api/auth/verify-otp \
  -H "Content-Type: application/json" \
  -d '{
    "email": "satoshi@mypayverse.com",
    "otp": "941203"
  }'

Endpoint: /api/auth/verify-otp

Responses

HTTP 200

OTP confirmed and token minted.

{
  "message": "Email verified successfully",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "664f8f6b9aae7cd290a9d994",
    "email": "satoshi@mypayverse.com",
    "isVerified": true,
    "kycStatus": "verified"
  }
}

HTTP 400

OTP expired or incorrect.

{
  "error": "OTP has expired"
}

HTTP 429

Too many failed attempts.

{
  "error": "Too many failed attempts. Please request a new OTP."
}

POST

/api/auth/login

Login

Authenticates an existing verified user and returns a bearer token together with the latest wallet snapshot.

Body Parameters

Name	Type	Description	Example
emailRequired	string (email)	Registered email address.	satoshi@mypayverse.com
passwordRequired	string	User password.	Sup3rStrong!

curl -X POST https://api.mypayverse.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "satoshi@mypayverse.com",
    "password": "Sup3rStrong!"
  }'

Endpoint: /api/auth/login

Responses

HTTP 200

Credentials valid. Token issued.

{
  "message": "Login successful",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "664f8f6b9aae7cd290a9d994",
    "email": "satoshi@mypayverse.com",
    "balance": 1250,
    "invested": 4000,
    "monthlyROI": 360
  }
}

HTTP 401

Invalid email/password pair.

{
  "error": "Invalid credentials"
}

User Profile

Read and update authenticated user metadata such as contact details and wallet stats.

2 endpoints

GET

/api/user/profileAuth Required

Get Profile

Returns the authenticated user profile. Password hashes are omitted by design.

curl https://api.mypayverse.com/api/user/profile \
  -H "Authorization: Bearer <token>"

Endpoint: /api/user/profile

Responses

HTTP 200

Profile snapshot returned.

{
  "user": {
    "id": "664f8f6b9aae7cd290a9d994",
    "email": "satoshi@mypayverse.com",
    "country": "Singapore",
    "mobile": "+6581234567",
    "isVerified": true,
    "kycStatus": "verified",
    "walletAddress": "TQ4fz3hSyCbtb3XJ2boVQkzhF7Wn1mY6z",
    "balance": 1250,
    "invested": 4000,
    "totalEarned": 870,
    "monthlyROI": 360,
    "referralEarnings": 110,
    "partnerIncome": 45,
    "rank": "Gold",
    "referrals": {
      "level1": 12,
      "level2": 6,
      "level3": 3,
      "level4": 1,
      "level5": 0
    },
    "createdAt": "2024-05-24T08:17:11.631Z"
  }
}

HTTP 401

Missing or invalid bearer token.

{
  "error": "Authorization token required"
}

PUT

/api/user/profileAuth Required

Update Profile

Updates mutable contact attributes. Sensitive financial fields cannot be edited via this route.

Body Parameters

Name	Type	Description	Example
country	string	Updated country of residence.	United Arab Emirates
mobile	string	Updated phone number.	+971501234567

curl -X PUT https://api.mypayverse.com/api/user/profile \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "country": "United Arab Emirates" }'

Endpoint: /api/user/profile

Responses

HTTP 200

Profile updated.

{
  "message": "Profile updated successfully"
}

HTTP 400

No valid fields provided.

{
  "error": "No valid updates provided"
}

HTTP 404

User not found for the token payload.

{
  "error": "User not found"
}

Finance Operations

Deposit, withdraw, and invest USDT balances. All operations automatically create ledger entries.

4 endpoints

POST

/api/transactions/depositAuth Required

Create Deposit

Credits a user balance by logging an on-chain or off-chain deposit.

Notes

Minimum deposit is 1 USDT.
For sandbox environments transactions are auto-confirmed.

Body Parameters

Name	Type	Description	Example
amountRequired	number	Positive amount denominated in USDT.	250

curl -X POST https://api.mypayverse.com/api/transactions/deposit \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 250 }'

Endpoint: /api/transactions/deposit

Responses

HTTP 200

Deposit recorded.

{
  "message": "Deposit successful",
  "transaction": {
    "id": "6650b064d5d79f82c4bc5e17",
    "type": "deposit",
    "amount": 250,
    "status": "confirmed",
    "txId": "0x9db6fa...",
    "createdAt": "2024-05-24T10:41:08.399Z"
  },
  "newBalance": 1500
}

HTTP 400

Amount missing or too low.

{
  "error": "Minimum deposit amount is $1 USDT"
}

POST

/api/transactions/withdrawAuth Required

Request Withdrawal

Initiates a user withdrawal to a third-party wallet address.

Notes

Minimum withdrawal is 10 USDT.
Sandbox auto-confirms withdrawals; production environments enqueue for review.

Body Parameters

Name	Type	Description	Example
amountRequired	number	Positive amount denominated in USDT.	75
walletAddressRequired	string	Destination blockchain address.	TX9yYei3p4SxJ1rD8H9cgxWiu5d2Q3pXmL
hcaptchaToken	string	Captcha token (validated in production).	—

curl -X POST https://api.mypayverse.com/api/transactions/withdraw \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 75,
    "walletAddress": "TX9yYei3p4SxJ1rD8H9cgxWiu5d2Q3pXmL"
  }'

Endpoint: /api/transactions/withdraw

Responses

HTTP 200

Withdrawal logged.

{
  "message": "Withdrawal successful",
  "transaction": {
    "id": "6650b084d5d79f82c4bc5e1c",
    "type": "withdrawal",
    "amount": -75,
    "status": "confirmed",
    "txId": "0x71b94f...",
    "walletAddress": "TX9yYei3p4SxJ1rD8H9cgxWiu5d2Q3pXmL",
    "createdAt": "2024-05-24T10:42:12.512Z"
  },
  "newBalance": 1175
}

HTTP 400

Insufficient balance or below minimum.

{
  "error": "Minimum withdrawal amount is $10 USDT"
}

POST

/api/investment/investAuth Required

Start Investment

Moves available balance into an investment product and calculates a 9% monthly ROI accrual.

Notes

Investment amounts must be between 100 and 10,000 USDT.
Balance is debited immediately and ROI is pre-computed on confirmation.

Body Parameters

Name	Type	Description	Example
amountRequired	number	Investment principal in USDT.	500

curl -X POST https://api.mypayverse.com/api/investment/invest \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 500 }'

Endpoint: /api/investment/invest

Responses

HTTP 200

Investment recorded.

{
  "message": "Investment successful",
  "transaction": {
    "id": "6650b0b4d5d79f82c4bc5e23",
    "type": "investment",
    "amount": -500,
    "status": "confirmed",
    "createdAt": "2024-05-24T10:43:16.298Z"
  },
  "newBalance": 675,
  "totalInvested": 4500,
  "monthlyROI": 405
}

HTTP 400

Below minimum, above maximum, or insufficient balance.

{
  "error": "Investment amount must be between $100 and $10,000"
}

POST

/api/investment/withdrawAuth Required

Withdraw Investment

Moves invested funds back into the available balance.

Body Parameters

Name	Type	Description	Example
amountRequired	number	Withdrawal amount in USDT.	200

curl -X POST https://api.mypayverse.com/api/investment/withdraw \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 200 }'

Endpoint: /api/investment/withdraw

Responses

HTTP 200

Investment withdrawal confirmed.

{
  "message": "Withdrawal successful",
  "transaction": {
    "id": "6650b0e4d5d79f82c4bc5e29",
    "type": "withdrawal",
    "amount": -200,
    "status": "confirmed",
    "description": "Investment withdrawal of 200 USDT",
    "createdAt": "2024-05-24T10:44:20.431Z"
  },
  "newBalance": 875
}

HTTP 400

Insufficient balance to withdraw.

{
  "error": "Insufficient balance"
}

Transaction History

Audit-friendly transaction exports. Filter, paginate, and inspect historic ledger entries.

1 endpoints

GET

/api/transactionsAuth Required

List Transactions

Returns paginated transactions for the authenticated user.

Query Parameters

Name	Type	Description	Example
page	number	Page index (1-based). Default: 1	—
limit	number	Results per page (max 50). Default: 10	—
type	string	Filter by type: deposit, withdrawal, investment, roi, referral, partner.	—
status	string	Filter by status: pending, confirmed, failed, cancelled.	—

curl "https://api.mypayverse.com/api/transactions?page=1&limit=10&type=deposit" \
  -H "Authorization: Bearer <token>"

Endpoint: /api/transactions

Responses

HTTP 200

Transaction list returned.

{
  "transactions": [
    {
      "_id": "6650b084d5d79f82c4bc5e1c",
      "userId": "664f8f6b9aae7cd290a9d994",
      "type": "withdrawal",
      "amount": -75,
      "status": "confirmed",
      "createdAt": "2024-05-24T10:42:12.512Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "pages": 5
  }
}

Support & Partnerships

Capture partner inquiries and business leads programmatically.

2 endpoints

POST

/api/contact

Submit Contact Form

Creates a contact ticket and sends an internal notification email to the sales desk.

Body Parameters

Name	Type	Description	Example
nameRequired	string	Full name of the requester.	Ada Lovelace
emailRequired	string (email)	Contact email address.	ada@analytical.engine
phoneRequired	string	Telephone number.	+44 20 7123 4567
companyRequired	string	Company or project name.	Analytical Engine Labs
messageRequired	string	Context for the inquiry.	We want to leverage MyPayVerse payouts for our gaming platform.

curl -X POST https://api.mypayverse.com/api/contact \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ada Lovelace",
    "email": "ada@analytical.engine",
    "phone": "+44 20 7123 4567",
    "company": "Analytical Engine Labs",
    "message": "We want to leverage MyPayVerse payouts for our gaming platform."
  }'

Endpoint: /api/contact

Responses

HTTP 201

Ticket logged successfully.

{
  "message": "Contact form submitted successfully",
  "id": "6650b12fd5d79f82c4bc5e32",
  "emailSent": true
}

HTTP 400

Validation failure.

{
  "error": "All fields are required"
}

GET

/api/contactAuth Required

List Contact Submissions

Returns paginated contact tickets. Typically consumed by internal tools.

Query Parameters

Name	Type	Description	Example
page	number	Page index (1-based). Default: 1	—
limit	number	Results per page. Default: 10	—
status	string	Filter by workflow status.	new

curl "https://api.mypayverse.com/api/contact?status=new" \
  -H "Authorization: Bearer <admin-token>"

Endpoint: /api/contact

Responses

HTTP 200

Contact records returned.

{
  "contactForms": [
    {
      "_id": "6650b12fd5d79f82c4bc5e32",
      "name": "Ada Lovelace",
      "email": "ada@analytical.engine",
      "status": "new",
      "createdAt": "2024-05-24T10:46:23.091Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 4,
    "pages": 1
  }
}

Errors

Standard Response Codes

All endpoints return structured JSON errors containing an error message. Consult the table for likely causes.

Code	Meaning	Description
400	Bad Request	Payload validation failed, or the request cannot be fulfilled.
401	Unauthorized	No bearer token provided, or token could not be verified.
404	Not Found	Requested resource does not exist for the authenticated subject.
409	Conflict	Resource already exists, or the action conflicts with the current state.
429	Too Many Requests	Rate limit exceeded. Inspect Retry-After header for the backoff window.
500	Internal Error	Unexpected server error. Retry with exponential backoff and contact support if persistent.

Changelog

Release Notes

v1.2.0

2024-10-01

Added investment withdrawal endpoint.
Introduced rate-limit response headers for public tenants.
Documented support contact listing endpoint for admin dashboards.

v1.1.0

2024-07-12

Raised standard password minimum length to six characters.
Added referral income to login payload.

v1.0.0

2024-04-03

Initial public release of MyPayVerse Core APIs.