MyPayVerse API Documentation

A unified crypto payment and yield infrastructure. MyPayVerse now focuses on multi-tenant crypto payouts—onboard SaaS customers, register their wallets, and drive BEP20 hot-wallet flows via these APIs.

Base URL: https://api.mypayverse.xyzContact: 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.xyz/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.xyz/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.xyz/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.xyz/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"
}

Tenant & Wallet Management

Endpoints reserved for SaaS operators to register tenants, provision wallets, and inspect wallet activity. Send the tenant identifier via the `x-customer-id` header when interacting with downstream asset routes.

4 endpoints

POST

/api/v1/customers/createAuth Required

Create SaaS Customer

Registers a tenant and stores chain configuration that powers downstream BEP20 operations.

Notes

Only privileged dashboard/service accounts should invoke this endpoint.
Responses always follow the `{ result, responseMessage, statusCode }` shape used across internal services.

Body Parameters

Name	Type	Description	Example
nameRequired	string	Display name for the tenant.	Acme Corp
rpcUrlRequired	string	RPC endpoint the tenant uses for on-chain reads/writes.	https://bsc-dataseed.binance.org/
tokenAddress	string	ERC20/BEP20 contract address for the tenant token.	0x1234567890abcdef1234567890abcdef12345678
vaultContractAddress	string	Vault contract used for custody operations.	—
adminAddress	string	Tenant admin wallet used for approvals.	—
hotwalletAddress	string	Tenant hot wallet address that funds withdrawals.	—
adminPvtKey	string	Encrypted admin private key (store securely).	—
hotwalletPvtKey	string	Encrypted hot wallet private key.	—

curl -X POST https://api.mypayverse.xyz/api/v1/customers/create \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "rpcUrl": "https://bsc-dataseed.binance.org/",
    "tokenAddress": "0x1234567890abcdef1234567890abcdef12345678"
  }'

Endpoint: /api/v1/customers/create

Responses

HTTP 200

Customer created and identifier returned.

{
  "result": {
    "customerId": "66586574d5d79f82c4bc5e9a"
  },
  "responseMessage": "SUCCESS",
  "statusCode": 200
}

HTTP 400

Validation failed for required fields.

{
  "responseMessage": "\"name\" is required",
  "statusCode": 400
}

GET

/api/v1/customers/{id}Auth Required

Get SaaS Customer

Fetches a tenant document by identifier, including configured wallet metadata.

Path Parameters

Name	Type	Description	Example
idRequired	string	Tenant object id.	—

curl https://api.mypayverse.xyz/api/v1/customers/66586574d5d79f82c4bc5e9a \
  -H "Authorization: Bearer <admin-token>"

Endpoint: /api/v1/customers/{id}

Responses

HTTP 200

Customer found.

{
  "result": {
    "_id": "66586574d5d79f82c4bc5e9a",
    "name": "Acme Corp",
    "rpcUrl": "https://bsc-dataseed.binance.org/",
    "tokenAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "hotwalletAddress": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
    "createdAt": "2024-05-25T07:14:11.132Z"
  },
  "responseMessage": "DATA_FOUND",
  "statusCode": 200
}

HTTP 404

Customer id does not exist.

{
  "responseMessage": "DATA_NOT_FOUND",
  "statusCode": 404
}

POST

/api/v1/customers/walletAuth Required

Provision User Wallet

Creates a custodial wallet for a user within a tenant context and stores it in the internal wallets collection.

Body Parameters

Name	Type	Description	Example
userIdRequired	string	User identifier that will own the wallet.	—
customerIdRequired	string	Tenant identifier owning the wallet.	—

curl -X POST https://api.mypayverse.xyz/api/v1/customers/wallet \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{ "userId": "664f8f6b9aae7cd290a9d994", "customerId": "66586574d5d79f82c4bc5e9a" }'

Endpoint: /api/v1/customers/wallet

Responses

HTTP 200

Wallet document persisted.

{
  "result": {
    "_id": "6658662fd5d79f82c4bc5ea3",
    "userId": "664f8f6b9aae7cd290a9d994",
    "customerId": "66586574d5d79f82c4bc5e9a",
    "address": "0x7f1d5e2c6d79d8a1f8c2735e4ef09fd8a4f1db5a"
  },
  "responseMessage": "SUCCESS",
  "statusCode": 200
}

HTTP 404

Customer id not found.

{
  "responseMessage": "Customer not found",
  "statusCode": 404
}

GET

/api/v1/customers/wallet/transactionsAuth Required

Wallet Transactions

Lists deposit and withdrawal transactions for a specific custodial wallet inside a tenant.

Query Parameters

Name	Type	Description	Example
walletAddressRequired	string	Managed wallet address to inspect.	—
customerIdRequired	string	Tenant identifier tied to the wallet.	—
type	string	Optional filter across DEPOSIT or WITHDRAW.	—

curl "https://api.mypayverse.xyz/api/v1/customers/wallet/transactions?walletAddress=0x7f1d5e2c6d79d8a1f8c2735e4ef09fd8a4f1db5a&customerId=66586574d5d79f82c4bc5e9a" \
  -H "Authorization: Bearer <admin-token>"

Endpoint: /api/v1/customers/wallet/transactions

Responses

HTTP 200

Transactions returned (sorted newest first).

{
  "result": [
    {
      "_id": "665866c5d5d79f82c4bc5ead",
      "amount": 120,
      "transacionType": "DEPOSIT",
      "transacionStatus": "COMPLETED",
      "toWalletAddress": "0x7f1d5e2c6d79d8a1f8c2735e4ef09fd8a4f1db5a",
      "createdAt": "2024-05-25T07:20:14.512Z"
    }
  ],
  "responseMessage": "DATA_FOUND",
  "statusCode": 200
}

HTTP 404

Wallet not registered for the tenant.

{
  "responseMessage": "Wallet not found for this customer",
  "statusCode": 404
}

Asset Transactions (Tenant Hot Wallet)

Programmatic access to tenant hot wallets. Submit withdrawals, list historical activity, and approve queued payouts.

3 endpoints

POST

/api/v1/assetsTransaction/WithdrawAssetAuth Required

Submit Withdraw Request

Moves funds from the tenant hot wallet to a user-managed wallet. Requests under 100 units auto-complete, otherwise they wait for approval.

Notes

Requests <= 100 are executed immediately and return `COMPLETED`.
Requests > 100 stay in `WAITING_APPROVAL` until processed by the approval endpoint.

Body Parameters

Name	Type	Description	Example
walletAddressRequired	string	Destination wallet to receive the payout.	—
userIdRequired	string	User initiating the withdrawal.	—
customerIdRequired	string	Tenant identifier tied to the hot wallet.	—
amountRequired	number	Token amount to transfer (uses tenant token decimals).	50

curl -X POST https://api.mypayverse.xyz/api/v1/assetsTransaction/WithdrawAsset \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "walletAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "userId": "664f8f6b9aae7cd290a9d994",
    "customerId": "66586574d5d79f82c4bc5e9a",
    "amount": 50
  }'

Endpoint: /api/v1/assetsTransaction/WithdrawAsset

Responses

HTTP 200

Withdraw recorded (completed or awaiting approval).

{
  "result": {
    "_id": "66586846d5d79f82c4bc5ed0",
    "userId": "664f8f6b9aae7cd290a9d994",
    "customerId": "66586574d5d79f82c4bc5e9a",
    "amount": 50,
    "formWalletAddress": "0xhotWallet",
    "toWalletAddress": "0x1234567890abcdef1234567890abcdef12345678",
    "transacionType": "WITHDRAW",
    "transacionStatus": "COMPLETED",
    "txHash": "0x9db6fa..."
  },
  "responseMessage": "Withdraw completed",
  "statusCode": 200
}

HTTP 404

Customer or user id not found.

{
  "responseMessage": "Customer not found",
  "statusCode": 404
}

GET

/api/v1/assetsTransaction/transactionsAuth Required

List Asset Transactions

Paginates asset transactions for a tenant with optional filters by user, status, and date.

Query Parameters

Name	Type	Description	Example
customerId	string	Filter by tenant id.	—
userId	string	Filter transactions created by a specific user.	—
status	string	Filter by transaction status (COMPLETED, WAITING_APPROVAL, etc.).	—
fromDate	string (ISO date)	Inclusive lower bound for createdAt.	—
toDate	string (ISO date)	Inclusive upper bound for createdAt.	—
page	number	Page index (1-based). Default: 1	—
limit	number	Results per page. Default: 10	—

curl "https://api.mypayverse.xyz/api/v1/assetsTransaction/transactions?customerId=66586574d5d79f82c4bc5e9a&status=WAITING_APPROVAL&limit=5" \
  -H "Authorization: Bearer <admin-token>"

Endpoint: /api/v1/assetsTransaction/transactions

Responses

HTTP 200

Paginated list returned.

{
  "result": {
    "transactions": [
      {
        "_id": "66586846d5d79f82c4bc5ed0",
        "userId": "664f8f6b9aae7cd290a9d994",
        "transacionType": "WITHDRAW",
        "transacionStatus": "WAITING_APPROVAL",
        "amount": 250,
        "createdAt": "2024-05-25T07:32:20.512Z"
      }
    ],
    "page": 1,
    "limit": 10,
    "total": 35,
    "totalPages": 4
  },
  "responseMessage": "Transactions fetched",
  "statusCode": 200
}

POST

/api/v1/assetsTransaction/withdraw/approveAuth Required

Approve/Reject Withdraw

Transitions a WAITING_APPROVAL withdraw transaction to COMPLETED (on-chain transfer) or REJECTED.

Body Parameters

Name	Type	Description	Example
transactionIdRequired	string	Identifier returned from the withdraw request.	—
approveRequired	boolean	true to release funds, false to reject.	—

curl -X POST https://api.mypayverse.xyz/api/v1/assetsTransaction/withdraw/approve \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{ "transactionId": "66586846d5d79f82c4bc5ed0", "approve": true }'

Endpoint: /api/v1/assetsTransaction/withdraw/approve

Responses

HTTP 200

Transaction updated.

{
  "result": {
    "_id": "66586846d5d79f82c4bc5ed0",
    "transacionStatus": "COMPLETED",
    "txHash": "0x71b94f..."
  },
  "responseMessage": "Withdraw approved and completed",
  "statusCode": 200
}

HTTP 400

Transaction is not in WAITING_APPROVAL.

{
  "responseMessage": "Transaction not pending approval",
  "statusCode": 400
}

HTTP 404

Transaction id not found.

{
  "responseMessage": "Transaction not found",
  "statusCode": 404
}

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.4.0

2024-11-12

Refreshed the docs site to focus on the new tenant and asset transaction APIs.
Removed deprecated consumer finance, profile, and contact endpoints to avoid confusion.
Called out the `x-customer-id` requirement in the tenant documentation.

v1.3.0

2024-11-05

Documented SaaS tenant creation and wallet provisioning APIs.
Added hot-wallet withdrawal, listing, and approval workflow documentation.
Clarified shared `{ result, responseMessage, statusCode }` response envelope for internal endpoints.

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.