U Shield API Documentation

U Shield API Documentation v1.0

Base URL: http://localhost:3000/api

Introduction

Authentication: All endpoints (except auth endpoints) require a Bearer token in the Authorization header:

Authorization: Bearer <access_token>

Authentication

1. Register Admin

Creates a new admin account.

Method	Endpoint
POST	`/auth/register`

Request Body

{
  "email": "admin@example.com",
  "password": "SecurePassword123!",
  "otp": "123456"
}

Response (201 Created)

{
  "success": true,
  "message": "Registration successful",
  "admin": {
    "id": "uuid-here",
    "email": "admin@example.com"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Error Response (400 Bad Request)

{
  "error": "Email already registered"
}

2. Login

Authenticates admin and returns access token.

Method	Endpoint
POST	`/auth/login`

Request Body

{
  "email": "admin@example.com",
  "password": "SecurePassword123!",
  "otp": "123456"
}

Response (200 OK)

{
  "success": true,
  "message": "Login successful",
  "admin": {
    "id": "uuid-here",
    "email": "admin@example.com"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Error Response (401 Unauthorized)

{
  "error": "Invalid credentials"
}

3. Get Current Admin

Returns currently authenticated admin info.

Method	Endpoint
GET	`/auth/me`

Headers

Authorization: Bearer <access_token>

Response (200 OK)

{
  "admin": {
    "id": "uuid-here",
    "email": "admin@example.com",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

4. Logout

Logs out the admin and invalidates refresh token.

Method	Endpoint
POST	`/auth/logout`

Headers

Authorization: Bearer <access_token>

Response (200 OK)

{
  "success": true,
  "message": "Logout successful"
}

5. Refresh Access Token

Generates a new access token using refresh token stored in cookie.

Method	Endpoint
POST	`/auth/refresh`

Response (200 OK)

{
  "success": true,
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

6. Change Password

Change the admin's password.

Method	Endpoint
PATCH	`/auth/change-password`

Headers

Authorization: Bearer <access_token>

Request Body

{
  "old_password": "OldPassword123!",
  "new_password": "NewPassword456!",
  "otp": "123456"
}

Response (200 OK)

{
  "success": true,
  "message": "Password changed successfully"
}

User Management

1. Create User Addresses

Creates blockchain addresses for a specific user across all chains (BTC, ETH, BSC, TRON).

Method	Endpoint
POST	`/users/create-addresses`

Headers

Authorization: Bearer <access_token>

Request Body

{
  "user_id": "john_doe_123"
}

Response (201 Created)

{
  "success": true,
  "data": {
    "user_id": "john_doe_123",
    "addresses": [
      {
        "uid": "uuid-1",
        "chain": "BTC",
        "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
      },
      {
        "uid": "uuid-2",
        "chain": "ETH",
        "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
      },
      {
        "uid": "uuid-3",
        "chain": "BSC",
        "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
      },
      {
        "uid": "uuid-4",
        "chain": "TRON",
        "address": "TJCnKsPa4F6YvJFMzQkXZLz1sBmGwKkMfQ"
      }
    ]
  },
  "message": "User addresses created successfully"
}

Error Response (409 Conflict)

{
  "success": false,
  "error": "User already has addresses",
  "code": "USER_EXISTS"
}

2. Bulk Generate Users

Generates multiple users with auto-generated UUID user IDs.

Method	Endpoint
POST	`/users/bulk-generate`

Headers

Authorization: Bearer <access_token>

Request Body

{
  "count": 10
}

Validation: count — Integer, min 1, max 100.

Response (201 Created)

{
  "success": true,
  "data": {
    "generated_count": 10,
    "user_ids": [
      "550e8400-e29b-41d4-a716-446655440000",
      "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "..."
    ],
    "users": [
      {
        "user_id": "550e8400-e29b-41d4-a716-446655440000",
        "addresses": [
          {
            "uid": "uuid-1",
            "chain": "BTC",
            "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
          }
        ]
      }
    ]
  },
  "message": "10 users generated successfully"
}

Error Response (400 Bad Request)

{
  "success": false,
  "error": "Count must be between 1 and 100",
  "code": "BULK_GENERATE_FAILED"
}

3. Get User Addresses

Retrieves all addresses and balances for a specific user.

Method	Endpoint
GET	`/users/:user_id/addresses`

Headers

Authorization: Bearer <access_token>

Response (200 OK)

{
  "success": true,
  "data": {
    "user_id": "john_doe_123",
    "addresses": [
      {
        "uid": "uuid-1",
        "chain": "BTC",
        "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
        "balance": 0.005,
        "total_deposited": 0.01,
        "total_collected": 0.005,
        "last_activity": "2024-01-15T10:30:00Z",
        "is_active": true,
        "created_at": "2024-01-10T08:00:00Z",
        "assets": {}
      }
    ]
  }
}

4. List All Users

Lists all users with pagination and filtering.

Parameter	Type	Default	Description
limit	number	50	Results per page (max 5000)
page	number	1	Page number
search	string	""	Search by user_id or address
from_date	date	-	Filter by creation date (ISO)
to_date	date	-	Filter by creation date (ISO)
sort_by	string	created_at	Sort field (created_at, user_id, total_balance, etc.)
sort_order	string	desc	Sort order (asc \| desc)

Example Request

GET /users?limit=20&page=1&sort_by=created_at&sort_order=desc

Response (200 OK)

{
  "success": true,
  "data": {
    "users": [
      {
        "user_id": "john_doe_123",
        "address_count": 4,
        "total_balance": 150.50,
        "total_deposited": 200.00,
        "total_collected": 49.50,
        "last_activity": "2024-01-15T10:30:00Z",
        "created_at": "2024-01-10T08:00:00Z",
        "addresses": [
          {
            "uid": "uuid-1",
            "user_id": "john_doe_123",
            "chain": "BTC",
            "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
            "balance": 0.005
          }
        ]
      }
    ],
    "stats": {
      "total_users": 1250,
      "new_users_yesterday": 15
    },
    "pagination": {
      "current_page": 1,
      "total_pages": 63,
      "limit": 20,
      "total_records": 1250,
      "has_next": true,
      "has_prev": false
    }
  }
}

5. List Auto-Generated Users

Lists only auto-generated users (created via bulk-generate).

Method	Endpoint
GET	`/users/auto-generated`

Query Parameters: Same as List All Users

Example Request

GET /users/auto-generated?limit=50&page=1

Response (200 OK)

{
  "success": true,
  "data": {
    "users": [
      {
        "user_id": "550e8400-e29b-41d4-a716-446655440000",
        "address_count": 4,
        "total_balance": 0.00,
        "total_deposited": 0.00,
        "total_collected": 0.00,
        "last_activity": null,
        "created_at": "2024-01-15T12:00:00Z",
        "addresses": []
      }
    ],
    "stats": {
      "total_users": 150,
      "new_users_yesterday": 10
    },
    "pagination": {
      "current_page": 1,
      "total_pages": 3,
      "limit": 50,
      "total_records": 150,
      "has_next": true,
      "has_prev": false
    }
  }
}

6. Export Users

Exports user data in CSV or JSON format.

Parameter	Type	Default	Description
format	string	csv	Export format (csv \| json)
search	string	""	Search filter
from_date	date	-	Filter by date
to_date	date	-	Filter by date
sort_by	string	created_at	Sort field
sort_order	string	desc	Sort order

Example Request

GET /users/export?format=csv

Response (CSV)

Content-Type: text/csv
Content-Disposition: attachment; filename="users_export_2024-01-15.csv"

User ID,Address Count,Total Balance,Total Deposited,Total Collected,Last Activity,Created At,Addresses
john_doe_123,4,150.50,200.00,49.50,2024-01-15T10:30:00Z,2024-01-10T08:00:00Z,"BTC:bc1q...(0.005); ETH:0x742..."

Response (JSON)

{
  "success": true,
  "exported_at": "2024-01-15T14:30:00Z",
  "total_records": 1250,
  "filters": {},
  "data": []
}

Collection Orders

Collection orders represent funds that need to be collected from user addresses to corporate wallets.

1. List Collection Orders

Lists collection orders with filtering and pagination.

Method	Endpoint
GET	`/collection/orders`

Headers

Authorization: Bearer <access_token>

Query Parameters

Parameter	Type	Default	Description
review_status	string	pending	Filter by status (pending, approved, rejected)
chain	string	-	Filter by blockchain (BTC, ETH, BSC, TRON)
currency	string	-	Filter by asset/currency
from_date	date	-	Filter by creation date
to_date	date	-	Filter by creation date
min_amount	number	-	Minimum amount filter
max_amount	number	-	Maximum amount filter
sort_by	string	created_at	Sort field
sort_order	string	desc	Sort order (asc, desc)
page	number	1	Page number
limit	number	20	Results per page (max 100)

Example Request

GET /collection/orders?review_status=pending&chain=BTC&limit=20&page=1

Response (200 OK)

{
  "success": true,
  "data": {
    "orders": [
      {
        "id": 123,
        "user_id": "john_doe_123",
        "chain": "BTC",
        "currency": "BTC",
        "amount": 0.005,
        "amount_usd": 250.00,
        "from_address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
        "to_address": "bc1qcorporate123...",
        "transaction_status": "confirmed",
        "review_status": "pending",
        "collection_status": null,
        "deposit_tx_hash": "0xabc123...",
        "collection_tx_hash": null,
        "created_at": "2024-01-15T10:30:00Z",
        "confirmed_at": "2024-01-15T10:35:00Z",
        "reviewed_at": null,
        "collected_at": null
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 5,
      "limit": 20,
      "total_records": 95,
      "has_next": true,
      "has_prev": false
    }
  }
}

2. Get Collection Order Details

Retrieves detailed information about a specific collection order.

Method	Endpoint
GET	`/collection/orders/:orderId`

Headers

Authorization: Bearer <access_token>

Response (200 OK)

{
  "success": true,
  "data": {
    "id": 123,
    "user_id": "john_doe_123",
    "chain": "BTC",
    "currency": "BTC",
    "amount": 0.005,
    "amount_usd": 250.00,
    "from_address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "to_address": "bc1qcorporate123...",
    "transaction_status": "confirmed",
    "review_status": "pending",
    "collection_status": null,
    "deposit_tx_hash": "0xabc123...",
    "collection_tx_hash": null,
    "gas_top_up_tx_hash": null,
    "estimated_gas_fee": null,
    "actual_gas_fee": null,
    "notes": null,
    "rejection_reason": null,
    "created_at": "2024-01-15T10:30:00Z",
    "confirmed_at": "2024-01-15T10:35:00Z",
    "reviewed_at": null,
    "reviewed_by": null,
    "collected_at": null
  }
}

Error Response (404 Not Found)

{
  "success": false,
  "error": "Collection order not found",
  "code": "ORDER_NOT_FOUND"
}

3. Get Collection Order Stats

Retrieves statistics about collection orders.

Method	Endpoint
GET	`/collection/orders/stats`

Headers

Authorization: Bearer <access_token>

Response (200 OK)

{
  "success": true,
  "data": {
    "total_pending": 95,
    "total_approved": 1250,
    "total_rejected": 15,
    "total_collected": 1100,
    "total_failed": 10,
    "pending_amount_usd": 15000.00,
    "collected_amount_usd": 125000.00
  }
}

4. Get Collection History

Retrieves history of collected or failed collection orders.

Method	Endpoint
GET	`/collection/orders/history`

Headers

Authorization: Bearer <access_token>

Query Parameters

Parameter	Type	Default	Description
collection_status	string	all	Filter by status (all, collected, failed)
chain	string	-	Filter by blockchain
currency	string	-	Filter by asset
from_date	date	-	Filter by collection date
to_date	date	-	Filter by collection date
min_amount	number	-	Minimum amount
max_amount	number	-	Maximum amount
tx_hash	string	-	Search by transaction hash
sort_by	string	collected_at	Sort field
sort_order	string	desc	Sort order
page	number	1	Page number
limit	number	20	Results per page

Example Request

GET /collection/orders/history?collection_status=collected&chain=BTC

Response (200 OK)

{
  "success": true,
  "data": {
    "orders": [
      {
        "id": 100,
        "user_id": "john_doe_123",
        "chain": "BTC",
        "currency": "BTC",
        "amount": 0.01,
        "collection_tx_hash": "0xdef456...",
        "collection_status": "collected",
        "collected_at": "2024-01-14T15:00:00Z"
      }
    ],
    "pagination": {}
  }
}

5. Approve Collection Order

Approves a collection order for processing.

Method	Endpoint
PATCH	`/collection/orders/:orderId/approve`

Headers

Authorization: Bearer <access_token>

Request Body (optional)

{
  "notes": "Verified transaction, approved for collection"
}

Response (200 OK)

{
  "success": true,
  "data": {
    "id": 123,
    "review_status": "approved",
    "reviewed_at": "2024-01-15T11:00:00Z",
    "reviewed_by": "uuid-admin",
    "notes": "Verified transaction, approved for collection"
  },
  "message": "Collection order approved successfully"
}

Error Responses

404 Not Found

{
  "success": false,
  "error": "Collection order not found",
  "code": "ORDER_NOT_FOUND"
}

409 Conflict

{
  "success": false,
  "error": "Order already processed",
  "code": "ALREADY_PROCESSED"
}

400 Bad Request

{
  "success": false,
  "error": "Transaction not confirmed yet",
  "code": "NOT_CONFIRMED"
}

6. Reject Collection Order

Rejects a collection order with a reason.

Method	Endpoint
PATCH	`/collection/orders/:orderId/reject`

Headers

Authorization: Bearer <access_token>

Request Body

{
  "reason": "Suspicious transaction pattern detected"
}

Response (200 OK)

{
  "success": true,
  "data": {
    "id": 123,
    "review_status": "rejected",
    "reviewed_at": "2024-01-15T11:00:00Z",
    "reviewed_by": "uuid-admin",
    "rejection_reason": "Suspicious transaction pattern detected"
  },
  "message": "Collection order rejected"
}

7. Estimate Collection Gas

Estimates the gas fee required for collecting an order.

Method	Endpoint
POST	`/collection/orders/:orderId/estimate-gas`

Headers

Authorization: Bearer <access_token>

Response (200 OK)

{
  "success": true,
  "data": {
    "order_id": 123,
    "chain": "ETH",
    "estimated_gas_fee": 0.002,
    "estimated_gas_fee_usd": 6.50,
    "gas_price_gwei": 25,
    "estimated_gas_units": 21000
  }
}

8. Collect Order

Executes the collection transaction for an approved order.

Method	Endpoint
POST	`/collection/orders/:orderId/collect`

Headers

Authorization: Bearer <access_token>

Request Body

{
  "otp": "123456",
  "password": "YourPassword123!"
}

Response (200 OK)

{
  "success": true,
  "data": {
    "order_id": 123,
    "collection_status": "collected",
    "collection_tx_hash": "0xdef456...",
    "gas_top_up_tx_hash": "0xabc123...",
    "actual_gas_fee": 0.0021,
    "collected_at": "2024-01-15T11:30:00Z"
  },
  "message": "Order collected successfully"
}

Error Responses

400 Bad Request

{
  "success": false,
  "error": "OTP is required for collection",
  "code": "OTP_REQUIRED"
}

401 Unauthorized

{
  "success": false,
  "error": "Invalid password",
  "code": "INVALID_PASSWORD"
}

400 Bad Request

{
  "success": false,
  "error": "Order must be approved before collection",
  "code": "NOT_APPROVED"
}

409 Conflict

{
  "success": false,
  "error": "Order already collected",
  "code": "ALREADY_COLLECTED"
}

9. Batch Collect Orders

Collects all eligible orders for a specific chain and asset in parallel.

Method	Endpoint
POST	`/collection/orders/batch`

Headers

Authorization: Bearer <access_token>

Query Parameters

Parameter	Type	Required	Description
chain	string	Yes	Blockchain (BTC, ETH, BSC, TRON)
asset	string	Yes	Asset symbol (BTC, USDT, etc.)

Request Body

{
  "otp": "123456",
  "password": "YourPassword123!"
}

Example Request

POST /collection/orders/batch?chain=ETH&asset=USDT

Response (200 OK)

{
  "success": true,
  "data": [
    {
      "order_id": 123,
      "status": "success",
      "collection_tx_hash": "0xdef456...",
      "gas_top_up_tx_hash": "0xabc123..."
    },
    {
      "order_id": 124,
      "status": "success",
      "collection_tx_hash": "0xghi789..."
    },
    {
      "order_id": 125,
      "status": "failed",
      "error": "Insufficient gas"
    }
  ],
  "summary": {
    "total": 25,
    "collected": 23,
    "failed": 2,
    "duration_ms": 45000
  },
  "message": "Batch collection completed: 23 collected, 2 failed"
}

Error Responses

404 Not Found

{
  "success": false,
  "error": "No eligible orders found for ETH/USDT",
  "code": "NO_ELIGIBLE_ORDERS"
}

401 Unauthorized

{
  "success": false,
  "error": "Invalid OTP",
  "code": "OTP_INVALID"
}

Distribution Orders

Distribution orders represent funds to be sent from corporate wallets to user addresses.

1. Create Distribution Order

Creates a new distribution order.

Method	Endpoint
POST	`/distribution/orders/create`

Headers

Authorization: Bearer <access_token>

Request Body

{
  "user_id": "john_doe_123",
  "chain": "BTC",
  "currency": "BTC",
  "to_address": "bc1quser123...",
  "amount": 0.01,
  "notes": "Withdrawal request #12345",
  "reference_id": "WD-12345"
}

Validation

user_id: Required, string
chain: Required, one of (BTC, ETH, BSC, TRON)
currency: Required, string
to_address: Required, valid blockchain address
amount: Required, positive number
notes: Optional, string
reference_id: Optional, string

Response (200 OK)

{
  "success": true,
  "data": {
    "id": 456,
    "user_id": "john_doe_123",
    "chain": "BTC",
    "currency": "BTC",
    "to_address": "bc1quser123...",
    "amount": 0.01,
    "amount_usd": 500.00,
    "review_status": "pending",
    "distribution_status": null,
    "notes": "Withdrawal request #12345",
    "reference_id": "WD-12345",
    "created_at": "2024-01-15T12:00:00Z",
    "created_by": "uuid-admin"
  }
}

Error Response (400 Bad Request)

{
  "success": false,
  "error": "Missing required fields: user_id, chain, currency, to_address, amount",
  "code": "VALIDATION_ERROR"
}

2. List Distribution Orders

Lists distribution orders with filtering.

Method	Endpoint
GET	`/distribution/orders`

Headers

Authorization: Bearer <access_token>

Query Parameters

Parameter	Type	Default	Description
review_status	string	pending	Filter by status (pending, approved, rejected)
chain	string	-	Filter by blockchain
currency	string	-	Filter by asset
user_id	string	-	Filter by user ID
from_date	date	-	Filter by creation date
to_date	date	-	Filter by creation date
min_amount	number	-	Minimum amount
max_amount	number	-	Maximum amount
sort_by	string	created_at	Sort field
sort_order	string	desc	Sort order
page	number	1	Page number
limit	number	20	Results per page (max 100)

Example Request

GET /distribution/orders?review_status=pending&chain=BTC&limit=20

Response (200 OK)

{
  "success": true,
  "data": {
    "orders": [
      {
        "id": 456,
        "user_id": "john_doe_123",
        "chain": "BTC",
        "currency": "BTC",
        "to_address": "bc1quser123...",
        "amount": 0.01,
        "amount_usd": 500.00,
        "review_status": "pending",
        "distribution_status": null,
        "reference_id": "WD-12345",
        "created_at": "2024-01-15T12:00:00Z"
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 3,
      "limit": 20,
      "total_records": 45
    }
  }
}

3. Get Distribution Order Details

Retrieves detailed information about a specific distribution order.

Method	Endpoint
GET	`/distribution/orders/:orderId`

Headers

Authorization: Bearer <access_token>

Response (200 OK)

{
  "success": true,
  "data": {
    "id": 456,
    "user_id": "john_doe_123",
    "chain": "BTC",
    "currency": "BTC",
    "to_address": "bc1quser123...",
    "amount": 0.01,
    "amount_usd": 500.00,
    "review_status": "pending",
    "distribution_status": null,
    "distribution_tx_hash": null,
    "estimated_gas_fee": null,
    "actual_gas_fee": null,
    "notes": "Withdrawal request #12345",
    "reference_id": "WD-12345",
    "rejection_reason": null,
    "created_at": "2024-01-15T12:00:00Z",
    "created_by": "uuid-admin",
    "reviewed_at": null,
    "reviewed_by": null,
    "distributed_at": null
  }
}

4. Get Distribution History

Retrieves history of distributed or failed distribution orders.

Method	Endpoint
GET	`/distribution/orders/history`

Headers

Authorization: Bearer <access_token>

Query Parameters

Parameter	Type	Default	Description
status	string	all	Filter by status (distributed, failed, all)
chain	string	-	Filter by blockchain
currency	string	-	Filter by asset
user_id	string	-	Filter by user ID
from_date	date	-	Filter by distribution date
to_date	date	-	Filter by distribution date
tx_hash	string	-	Search by transaction hash
sort_by	string	distributed_at	Sort field
sort_order	string	desc	Sort order
page	number	1	Page number
limit	number	20	Results per page

Example Request

GET /distribution/orders/history?status=distributed&chain=ETH

Response (200 OK)

{
  "success": true,
  "data": {
    "orders": [
      {
        "id": 450,
        "user_id": "john_doe_123",
        "chain": "ETH",
        "currency": "USDT",
        "amount": 100.00,
        "distribution_status": "distributed",
        "distribution_tx_hash": "0xabc123...",
        "distributed_at": "2024-01-14T15:00:00Z"
      }
    ],
    "pagination": {}
  }
}

5. Approve Distribution Order

Approves a distribution order for processing.

Method	Endpoint
PATCH	`/distribution/orders/:orderId/approve`

Headers

Authorization: Bearer <access_token>

Request Body (optional)

{
  "notes": "Verified withdrawal request, approved"
}

Response (200 OK)

{
  "success": true,
  "data": {
    "id": 456,
    "review_status": "approved",
    "reviewed_at": "2024-01-15T13:00:00Z",
    "reviewed_by": "uuid-admin",
    "notes": "Verified withdrawal request, approved"
  },
  "message": "Distribution order approved successfully"
}

Error Response (400 Bad Request)

{
  "success": false,
  "error": "Invalid order ID",
  "code": "INVALID_ORDER_ID"
}

6. Reject Distribution Order

Rejects a distribution order with a reason.

Method	Endpoint
PATCH	`/distribution/orders/:orderId/reject`

Headers

Authorization: Bearer <access_token>

Request Body

{
  "reason": "Insufficient funds in corporate wallet"
}

Validation

reason: Required, string

Response (200 OK)

{
  "success": true,
  "data": {
    "id": 456,
    "review_status": "rejected",
    "reviewed_at": "2024-01-15T13:00:00Z",
    "reviewed_by": "uuid-admin",
    "rejection_reason": "Insufficient funds in corporate wallet"
  },
  "message": "Distribution order rejected successfully"
}

Error Response (400 Bad Request)

{
  "success": false,
  "error": "Rejection reason is required",
  "code": "REASON_REQUIRED"
}

7. Estimate Distribution Gas

Estimates the gas fee for distributing an order.

Method	Endpoint
POST	`/distribution/orders/:orderId/estimate-gas`

Headers

Authorization: Bearer <access_token>

Response (200 OK)

{
  "success": true,
  "data": {
    "order_id": 456,
    "chain": "ETH",
    "estimated_gas_fee": 0.003,
    "estimated_gas_fee_usd": 9.75,
    "gas_price_gwei": 30,
    "estimated_gas_units": 21000
  }
}

8. Distribute Order

Executes the distribution transaction for an approved order.

Method	Endpoint
POST	`/distribution/orders/:orderId/distribute`

Headers

Authorization: Bearer <access_token>

Request Body

{
  "otp": "123456",
  "password": "YourPassword123!"
}

Validation: otp required (6-digit string), password required (string).

Response (200 OK)

{
  "success": true,
  "data": {
    "order_id": 456,
    "distribution_status": "distributed",
    "distribution_tx_hash": "0xabc123...",
    "actual_gas_fee": 0.0032,
    "distributed_at": "2024-01-15T14:00:00Z"
  },
  "message": "Distribution completed successfully"
}

Error Responses

400 Bad Request

{
  "success": false,
  "error": "OTP is required for distribution",
  "code": "OTP_REQUIRED"
}

401 Unauthorized

{
  "success": false,
  "error": "Invalid password",
  "code": "INVALID_PASSWORD"
}

9. Distribute Bulk Orders

Distributes multiple orders specified by their IDs.

Method	Endpoint
POST	`/distribution/orders/distribute-bulk`

Headers

Authorization: Bearer <access_token>

Request Body

{
  "order_ids": [456, 457, 458],
  "otp": "123456",
  "password": "YourPassword123!"
}

Validation

order_ids: Required, non-empty array of integers
otp: Required, string
password: Required, string

Response (200 OK)

{
  "success": true,
  "results": [
    { "order_id": 456, "status": "success", "distribution_tx_hash": "0xabc123..." },
    { "order_id": 457, "status": "success", "distribution_tx_hash": "0xdef456..." },
    { "order_id": 458, "status": "failed", "error": "Insufficient balance" }
  ],
  "summary": { "total": 3, "successful": 2, "failed": 1 }
}

Error Response (400 Bad Request)

{
  "success": false,
  "error": "order_ids must be a non-empty array",
  "code": "INVALID_ORDER_IDS"
}

10. Batch Distribute Orders

Auto-selects and distributes all eligible orders for a chain/asset.

Method	Endpoint
POST	`/distribution/orders/batch`

Headers

Authorization: Bearer <access_token>

Query Parameters

Parameter	Type	Required	Description
chain	string	Yes	Blockchain (BTC, ETH, BSC, TRON)
asset	string	Yes	Asset symbol

Request Body

{
  "otp": "123456",
  "password": "YourPassword123!"
}

Example Request

POST /distribution/orders/batch?chain=ETH&asset=USDT

Response (200 OK)

{
  "success": true,
  "results": [
    { "order_id": 456, "status": "success", "distribution_tx_hash": "0xabc123..." }
  ],
  "summary": { "total": 10, "successful": 9, "failed": 1, "duration_ms": 30000 }
}

Error Response (400 Bad Request)

{
  "success": false,
  "error": "chain and asset are required query parameters",
  "code": "MISSING_PARAMETERS"
}

Dashboard & Stats

1. Get Dashboard Stats

Retrieves comprehensive dashboard statistics.

Method	Endpoint
GET	`/dashboard/stats`

Headers

Authorization: Bearer <access_token>

Response (200 OK)

{
  "success": true,
  "data": {
    "users": { "total": 1250, "new_today": 5, "new_yesterday": 15 },
    "yesterday": { "collected_usd": 0, "distributed_usd": 0 },
    "addresses": { "total_limit": 10000, "used": 40, "available": 9960 },
    "assets": [
      { "symbol": "BTC", "total_coins": "0.00287851", "value_usd": 315.3, "processing_usd": 45.3, "collectable_usd": 219.07, "chains": ["BTC"] },
      { "symbol": "USDT", "total_coins": "307.62000000", "value_usd": 307.62, "processing_usd": 215, "collectable_usd": 0, "chains": ["ETH","BSC","TRON"] },
      { "symbol": "ETH", "total_coins": "0.01401848", "value_usd": 54.44, "processing_usd": 0, "collectable_usd": 0, "chains": ["ETH"] },
      { "symbol": "USDC", "total_coins": "0.00000000", "value_usd": 0, "processing_usd": 0, "collectable_usd": 0, "chains": [] },
      { "symbol": "TRX", "total_coins": "0.00000000", "value_usd": 0, "processing_usd": 0, "collectable_usd": 0, "chains": [] }
    ],
    "asset_distribution": [
      { "asset": "BTC", "value_usd": 0 },
      { "asset": "USDT", "value_usd": 0 },
      { "asset": "ETH", "value_usd": 0 },
      { "asset": "USDC", "value_usd": 0 },
      { "asset": "TRX", "value_usd": 0 }
    ]
  }
}

2. Get Collection Funds Stats

Retrieves statistics about collected funds.

Method	Endpoint
GET	`/dashboard/collect-funds-stats`

Headers

Authorization: Bearer <access_token>

Response (200 OK)

{
  "success": true,
  "data": {
    "total_collected_usd": 125000.00,
    "total_collections": 1100,
    "asset_breakdown": [
      { "symbol": "USDT", "count": 17, "amount": 26, "usd_value": 26 },
      { "symbol": "BTC", "count": 1, "amount": 0.0001, "usd_value": 10.95 },
      { "symbol": "ETH", "count": 1, "amount": 0.0001, "usd_value": 0.39 }
    ]
  }
}

3. Get Distribution Funds Stats

Retrieves statistics about distributed funds.

Method	Endpoint
GET	`/dashboard/distribution-funds-stats`

Headers

Authorization: Bearer <access_token>

Response (200 OK)

{
  "success": true,
  "data": {
    "total_distributed_usd": 45000.00,
    "total_distributions": 450,
    "asset_breakdown": [
      { "symbol": "USDT", "count": 17, "amount": 26, "usd_value": 26 },
      { "symbol": "BTC", "count": 1, "amount": 0.0001, "usd_value": 10.95 },
      { "symbol": "ETH", "count": 1, "amount": 0.0001, "usd_value": 0.39 }
    ]
  }
}

4. Get Collection Address Stats

Retrieves stats for collection corporate address (specific chain/asset).

Method	Endpoint
GET	`/dashboard/collection-address-stats`

Headers

Authorization: Bearer <access_token>

Query Parameters

Parameter	Type	Default	Description
chain	string	BTC	Blockchain (BTC, ETH, BSC, TRON)
asset	string	BTC	Asset symbol

Example Request

GET /dashboard/collection-address-stats?chain=ETH&asset=USDT

Response (200 OK)

{
  "success": true,
  "data": {
    "chain": "ETH",
    "asset": "USDT",
    "corporate_address": "0xcorporate123...",
    "fund_balance": 50000.00,
    "gas_balance": 0.5,
    "estimated_gas_fee": 0.003,
    "pending_collections": 15
  }
}

5. Get Distribution Corporate Stats

Retrieves stats for distribution corporate address (specific chain/asset).

Method	Endpoint
GET	`/dashboard/distribution-corporate-stats`

Headers

Authorization: Bearer <access_token>

Query Parameters

Parameter	Type	Default	Description
chain	string	BTC	Blockchain
asset	string	BTC	Asset symbol

Example Request

GET /dashboard/distribution-corporate-stats?chain=BTC&asset=BTC

Response (200 OK)

{
  "success": true,
  "data": {
    "chain": "BTC",
    "asset": "BTC",
    "corporate_address": "bc1qcorporate...",
    "fund_balance": 10.5,
    "available_balance": 9.8,
    "gas_balance": 0.1,
    "pending_distributions": 8
  }
}

Settings

1. Get Admin Settings

Retrieves current admin settings.

Method	Endpoint
GET	`/settings`

Headers

Authorization: Bearer <access_token>

Response (200 OK)

{
  "success": true,
  "data": {
    "admin_id": "uuid-here",
    "distribution_mode": "manual",
    "hybrid_distribution_threshold": 1000.00,
    "auto_collection_enabled": false,
    "auto_collect_thresholds": {
      "BTC": 100,
      "ETH": 100,
      "USDT": 100
    },
    "auto_distribution_enabled": false,
    "used_addresses": 5000,
    "created_at": "2024-01-10T08:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
}

Error Response (404 Not Found)

{
  "success": false,
  "error": "Settings not found",
  "code": "SETTINGS_NOT_FOUND"
}

2. Update Admin Settings

Updates admin settings (requires OTP verification).

Method	Endpoint
PATCH	`/settings`

Headers

Authorization: Bearer <access_token>

Request Body

{
  "otp": "123456",
  "distribution_mode": "hybrid",
  "hybrid_distribution_threshold": 500.00,
  "auto_collection_enabled": true,
  "auto_collect_thresholds": {
    "BTC": 0.02,
    "ETH": 0.2,
    "USDT": 200
  },
  "auto_distribution_enabled": false
}

Field Descriptions

otp: Required, 6-digit OTP code
distribution_mode: Optional, one of (manual, automatic, hybrid)
hybrid_distribution_threshold: Optional, positive number (USD)
auto_collection_enabled: Optional, boolean
auto_collect_thresholds: Optional, object with asset thresholds
auto_distribution_enabled: Optional, boolean

Response (200 OK)

{
  "success": true,
  "data": {
    "admin_id": "uuid-here",
    "distribution_mode": "hybrid",
    "hybrid_distribution_threshold": 500.00,
    "auto_collection_enabled": true,
    "auto_collect_thresholds": {
      "BTC": 0.02,
      "ETH": 0.2,
      "USDT": 200
    },
    "auto_distribution_enabled": false,
    "updated_at": "2024-01-15T15:00:00Z"
  },
  "message": "Settings updated successfully"
}

Error Responses

400 Bad Request

{
  "success": false,
  "error": "OTP is required",
  "code": "OTP_REQUIRED"
}

400 Bad Request

{
  "success": false,
  "error": "distribution_mode must be one of: manual, automatic, hybrid",
  "code": "INVALID_DISTRIBUTION_MODE"
}

400 Bad Request

{
  "success": false,
  "error": "hybrid_distribution_threshold must be a positive number",
  "code": "INVALID_THRESHOLD"
}

Error Response Codes

All API errors follow this format:

{
  "success": false,
  "error": "Human-readable error message",
  "code": "ERROR_CODE"
}

Common Error Codes

HTTP Status	Code	Description
400	VALIDATION_ERROR	Invalid request data
401	UNAUTHORIZED	Missing or invalid authentication
401	OTP_INVALID	Invalid or expired OTP
401	INVALID_PASSWORD	Incorrect password
404	NOT_FOUND	Resource not found
404	ORDER_NOT_FOUND	Order not found
404	USER_NOT_FOUND	User not found
409	USER_EXISTS	User already exists
409	ALREADY_PROCESSED	Order already processed
409	ALREADY_COLLECTED	Order already collected
500	INTERNAL_ERROR	Server error

Rate Limiting

Rate limits are applied to protect the API:

Endpoint	Limit
`/auth/send-otp`	5 requests per minute
`/auth/register`	3 requests per 5 minutes
`/auth/login`	5 requests per 5 minutes
`/auth/refresh`	10 requests per minute
Other endpoints	No specific limit (general throttling applies)

Rate Limit Headers

X-RateLimit-Limit: 5
X-RateLimit-Remaining: 3
X-RateLimit-Reset: 1705324800

Pagination

All list endpoints support pagination with these query parameters:

page: Page number (default: 1)
limit: Results per page (default varies by endpoint)

Pagination Response

{
  "pagination": {
    "current_page": 1,
    "total_pages": 10,
    "limit": 20,
    "total_records": 195,
    "has_next": true,
    "has_prev": false
  }
}

Date Filters

Date filters use ISO 8601 format: YYYY-MM-DD

Examples

?from_date=2024-01-01&to_date=2024-01-31
?from_date=2024-01-15

Supported Blockchains & Assets

Blockchains

BTC – Bitcoin
ETH – Ethereum
BSC – Binance Smart Chain
TRON – Tron

Common Assets

BTC (Bitcoin)
ETH (Ethereum)
USDT (Tether — available on ETH, BSC, TRON)
USDC (USD Coin — available on ETH, BSC, TRON)

Support

For API support and questions, contact your system administrator.

Documentation Version: 1.0
Last Updated: 2025-10-23