U Shield API Documentation

U Shield API Documentation v1.0

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

Introduction

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

Authorization: Bearer <access_token>

Authentication

1. Send OTP

Sends a 6-digit verification code to the provided email address for registration, login, or password change operations.

Request Method Endpoint
POST /auth/send-otp

Rate Limiting: 5 requests per minute

Request Body

{
  "email": "admin@example.com"
}

Success Response (200 OK)

{
  "message": "Verification code sent successfully"
}

Error Response (400 Bad Request - Rate Limited)

{
  "error": "Please wait 45 seconds before requesting another code."
}

Error Response (400 Bad Request - Blocked)

{
  "error": "Too many failed attempts. Please try again later."
}

Error Response (400 Bad Request - Email Send Failed)

{
  "error": "Failed to send verification email. Please try again."
}

Error Response (400 Bad Request - Validation Failed)

{
  "error": "Validation failed",
  "details": [
    {
      "field": "email",
      "message": "Please provide a valid email address"
    }
  ]
}
Notes:
  • OTP expires in 10 minutes
  • Maximum 5 verification attempts per OTP
  • Rate limited to 1 request per 60 seconds per email
  • Account blocked for 30 minutes after 3 failed OTP validations
  • All existing unused OTPs are invalidated when a new OTP is requested
  • OTP is sent via email with HTML formatted code

2. Register Admin

Creates a new admin account.

Request Method Endpoint
POST /auth/register

Request Body

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

Success 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"
}

3. Login

Authenticates admin and returns access token.

Request Method Endpoint
POST /auth/login

Request Body

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

Success 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"
}

4. Get Current Admin

Returns currently authenticated admin info.

Request Method Endpoint
GET /auth/me

HTTP Headers

Authorization: Bearer <access_token>

Success Response (200 OK)

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

5. Logout

Logs out the admin and invalidates refresh token.

Request Method Endpoint
POST /auth/logout

HTTP Headers

Authorization: Bearer <access_token>

Success Response (200 OK)

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

6. Refresh Access Token

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

Request Method Endpoint
POST /auth/refresh

Success Response (200 OK)

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

7. Change Password

Change the admin's password.

Request Method Endpoint
PATCH /auth/change-password

HTTP Headers

Authorization: Bearer <access_token>

Request Body

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

Success 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).

Request Method Endpoint
POST /users/create-addresses

HTTP Headers

Authorization: Bearer <access_token>

Request Body

{
  "user_id": "john_doe_123"
}

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

Request Method Endpoint
POST /users/bulk-generate

HTTP Headers

Authorization: Bearer <access_token>

Request Body

{
  "count": 10
}
Validation: count — Integer, min 1, max 100.

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

Request Method Endpoint
GET /users/:user_id/addresses

HTTP Headers

Authorization: Bearer <access_token>

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

Request Method Endpoint
GET /users

HTTP Headers

Authorization: Bearer <access_token>

Query Parameters

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 format)
to_date date - Filter by creation date (ISO format)
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

Success 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).

Request Method Endpoint
GET /users/auto-generated

Query Parameters: Same as List All Users

Example Request

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

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

Request Method Endpoint
GET /users/export

HTTP Headers

Authorization: Bearer <access_token>

Query Parameters

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

Success 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..."

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

Request Method Endpoint
GET /collection/orders

HTTP Headers

Authorization: Bearer <access_token>

Query Parameters

Parameter Type Default Description
review_statusstringpendingFilter by status (pending, approved, rejected)
chainstring-Filter by blockchain (BTC, ETH, BSC, TRON)
currencystring-Filter by asset/currency
from_datedate-Filter by creation date
to_datedate-Filter by creation date
min_amountnumber-Minimum amount filter
max_amountnumber-Maximum amount filter
sort_bystringcreated_atSort field
sort_orderstringdescSort order (asc, desc)
pagenumber1Page number
limitnumber20Results per page (max 100)

Example Request

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

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

Request Method Endpoint
GET /collection/orders/:orderId

HTTP Headers

Authorization: Bearer <access_token>

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

Request Method Endpoint
GET /collection/orders/stats

HTTP Headers

Authorization: Bearer <access_token>

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

Request Method Endpoint
GET /collection/orders/history

HTTP Headers

Authorization: Bearer <access_token>

Query Parameters

Parameter Type Default Description
collection_statusstringallFilter by status (all, collected, failed)
chainstring-Filter by blockchain
currencystring-Filter by asset
from_datedate-Filter by collection date
to_datedate-Filter by collection date
min_amountnumber-Minimum amount
max_amountnumber-Maximum amount
tx_hashstring-Search by transaction hash
sort_bystringcollected_atSort field
sort_orderstringdescSort order
pagenumber1Page number
limitnumber20Results per page

Example Request

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

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

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

HTTP Headers

Authorization: Bearer <access_token>

Request Body (optional)

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

Success 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 Response (404 Not Found)

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

Error Response (409 Conflict)

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

Error Response (400 Bad Request)

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

6. Reject Collection Order

Rejects a collection order with a reason.

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

HTTP Headers

Authorization: Bearer <access_token>

Request Body

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

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

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

HTTP Headers

Authorization: Bearer <access_token>

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

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

HTTP Headers

Authorization: Bearer <access_token>

Request Body

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

Success 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 Response (400 Bad Request)

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

Error Response (401 Unauthorized)

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

Error Response (400 Bad Request)

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

Error Response (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.

Request Method Endpoint
POST /collection/orders/batch

HTTP Headers

Authorization: Bearer <access_token>

Query Parameters

Parameter Type Required Description
chainstringYesBlockchain (BTC, ETH, BSC, TRON)
assetstringYesAsset symbol (BTC, USDT, etc.)

Request Body

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

Example Request

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

Success 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 Response (404 Not Found)

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

Error Response (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.

Request Method Endpoint
POST /distribution/orders/create

HTTP 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

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

Request Method Endpoint
GET /distribution/orders

HTTP Headers

Authorization: Bearer <access_token>

Query Parameters

Parameter Type Default Description
review_statusstringpendingFilter by status (pending, approved, rejected)
chainstring-Filter by blockchain
currencystring-Filter by asset
user_idstring-Filter by user ID
from_datedate-Filter by creation date
to_datedate-Filter by creation date
min_amountnumber-Minimum amount
max_amountnumber-Maximum amount
sort_bystringcreated_atSort field
sort_orderstringdescSort order
pagenumber1Page number
limitnumber20Results per page (max 100)

Example Request

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

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

Request Method Endpoint
GET /distribution/orders/:orderId

HTTP Headers

Authorization: Bearer <access_token>

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

Request Method Endpoint
GET /distribution/orders/history

HTTP Headers

Authorization: Bearer <access_token>

Query Parameters

Parameter Type Default Description
statusstringallFilter by status (distributed, failed, all)
chainstring-Filter by blockchain
currencystring-Filter by asset
user_idstring-Filter by user ID
from_datedate-Filter by distribution date
to_datedate-Filter by distribution date
tx_hashstring-Search by transaction hash
sort_bystringdistributed_atSort field
sort_orderstringdescSort order
pagenumber1Page number
limitnumber20Results per page

Example Request

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

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

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

HTTP Headers

Authorization: Bearer <access_token>

Request Body (optional)

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

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

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

HTTP Headers

Authorization: Bearer <access_token>

Request Body

{
  "reason": "Insufficient funds in corporate wallet"
}
Validation: reason: Required, string

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

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

HTTP Headers

Authorization: Bearer <access_token>

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

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

HTTP Headers

Authorization: Bearer <access_token>

Request Body

{
  "otp": "123456",
  "password": "YourPassword123!"
}
Validation: otp: Required, 6-digit string • password: Required, string

Success 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 Response (400 Bad Request)

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

Error Response (401 Unauthorized)

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

9. Distribute Bulk Orders

Distributes multiple orders specified by their IDs.

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

HTTP 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

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

Request Method Endpoint
POST /distribution/orders/batch

HTTP Headers

Authorization: Bearer <access_token>

Query Parameters

Parameter Type Required Description
chainstringYesBlockchain (BTC, ETH, BSC, TRON)
assetstringYesAsset symbol

Request Body

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

Example Request

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

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

Request Method Endpoint
GET /dashboard/stats

HTTP Headers

Authorization: Bearer <access_token>

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

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

HTTP Headers

Authorization: Bearer <access_token>

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

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

HTTP Headers

Authorization: Bearer <access_token>

Success 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).

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

HTTP Headers

Authorization: Bearer <access_token>

Query Parameters

Parameter Type Default Description
chainstringBTCBlockchain (BTC, ETH, BSC, TRON)
assetstringBTCAsset symbol

Example Request

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

Success 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).

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

HTTP Headers

Authorization: Bearer <access_token>

Query Parameters

Parameter Type Default Description
chainstringBTCBlockchain
assetstringBTCAsset symbol

Example Request

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

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

Request Method Endpoint
GET /settings

HTTP Headers

Authorization: Bearer <access_token>

Success 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).

Request Method Endpoint
PATCH /settings

HTTP 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

Success 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"
}
{
  "success": false,
  "error": "distribution_mode must be one of: manual, automatic, hybrid",
  "code": "INVALID_DISTRIBUTION_MODE"
}
{
  "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
400VALIDATION_ERRORInvalid request data
401UNAUTHORIZEDMissing or invalid authentication
401OTP_INVALIDInvalid or expired OTP
401INVALID_PASSWORDIncorrect password
404NOT_FOUNDResource not found
404ORDER_NOT_FOUNDOrder not found
404USER_NOT_FOUNDUser not found
409USER_EXISTSUser already exists
409ALREADY_PROCESSEDOrder already processed
409ALREADY_COLLECTEDOrder already collected
500INTERNAL_ERRORServer error

Rate Limiting

Rate limits are applied to protect the API:

Endpoint Limit
/auth/send-otp5 requests per minute
/auth/register3 requests per 5 minutes
/auth/login5 requests per 5 minutes
/auth/refresh10 requests per minute
Other endpointsNo 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.

© U Shield API — Documentation v1.0 • Last Updated: 2025-10-30

Contact us anytime — our security experts are always ready to help.

U Shield is a secure, enterprise-level platform for managing and protecting digital assets through advanced encryption, decentralized key control, and uncompromising reliability.

API interface of coin deposit and withdrawal

About Us

Copyright © 2025 U SHIELD TECHNOLOGY PTE. LTD.

On March 20, 2025, U Shield officially introduced a brand upgrade, enhancing our security architecture and product ecosystem to deliver even more powerful, scalable, and intelligent digital asset protection solutions. Stay tuned for upcoming innovations.

Scroll to Top