ADMIN_API_DOCUMENTATION.md

PocketBase + Engine Admin API Documentation v1

Overview

This document contains all Admin APIs in the PocketBase + ThirdWeb Engine system. These APIs require Superuser authentication and are designed for administrative operations.

Base URL

http://localhost:8090

API Version

The system uses API version 1 (/api/v1/) for all endpoints.

Authentication

All Admin APIs require Superuser Bearer Token authentication.

---

🔐 Admin API Endpoints

1. Admin Health Check

Endpoint: GET /api/v1/admin/health
Authentication: ✅ Required (Superuser Token)
Description: Check system status for admin

Response

{
  "status": "healthy",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "auth": {
    "id": "admin-id",
    "email": "admin@example.com",
    "collectionName": "_superusers"
  },
  "database": "connected",
  "version": "1.0.0"
}

Example Usage

cURL:

curl -X GET http://localhost:8090/api/v1/admin/health \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN_HERE"

---

2. Admin ERC20 Transfer

Endpoint: POST /api/v1/admin/erc20/transfer
Authentication: ✅ Required (Superuser Token)
Description: Admin transfer ERC20 tokens

Request Body

{
  "to": "0x...",
  "amount": "1000000000000000000",
  "contractAddress": "0x...",
  "tokenName": "USDT"
}

Response

{
  "success": true,
  "queueId": "string",
  "message": "Admin transfer initiated successfully"
}

Example Usage

cURL:

curl -X POST http://localhost:8090/api/v1/admin/erc20/transfer \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN_HERE" \
  -d '{
    "to": "0x742d35Cc6634C0532925a3b8D4C9db96590c6C87",
    "amount": "1000000000000000000",
    "contractAddress": "0x57e93049080C5ebeCcf97be7F2CFC619B3A76B04",
    "tokenName": "USDT"
  }'

---

3. Admin ERC20 Pay

Endpoint: POST /api/v1/admin/erc20/pay
Authentication: ✅ Required (Superuser Token)
Description: Admin payment with ERC20 tokens using EIP-712 signature

Request Body

{
  "to": "0x...",
  "amount": "1000000000000000000",
  "contractAddress": "0x...",
  "tokenName": "USDT",
  "userWalletAddress": "0x..."
}

Response

{
  "success": true,
  "queueId": "string",
  "message": "Admin payment completed successfully"
}

Example Usage

cURL:

curl -X POST http://localhost:8090/api/v1/admin/erc20/pay \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN_HERE" \
  -d '{
    "to": "0x742d35Cc6634C0532925a3b8D4C9db96590c6C87",
    "amount": "1000000000000000000",
    "contractAddress": "0x57e93049080C5ebeCcf97be7F2CFC619B3A76B04",
    "tokenName": "USDT",
    "userWalletAddress": "0x1234567890123456789012345678901234567890"
  }'

---

4. Admin ERC20 Redeem

Endpoint: POST /api/v1/admin/erc20/redeem
Authentication: ✅ Required (Superuser Token)
Description: Admin redeem ERC20 tokens using EIP-712 signature

Request Body

{
  "to": "0x...",
  "amount": "1000000000000000000",
  "contractAddress": "0x...",
  "tokenName": "USDT",
  "userWalletAddress": "0x..."
}

Response

{
  "success": true,
  "queueId": "string",
  "message": "Admin redeem completed successfully"
}

Example Usage

cURL:

curl -X POST http://localhost:8090/api/v1/admin/erc20/redeem \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN_HERE" \
  -d '{
    "to": "0x742d35Cc6634C0532925a3b8D4C9db96590c6C87",
    "amount": "1000000000000000000",
    "contractAddress": "0x57e93049080C5ebeCcf97be7F2CFC619B3A76B04",
    "tokenName": "USDT",
    "userWalletAddress": "0x1234567890123456789012345678901234567890"
  }'

---

5. Admin Create Wallet

Endpoint: POST /api/v1/admin/createwallet
Authentication: ✅ Required (Superuser Token)
Description: Create new wallet for admin purposes

Request Body

{}

Response

{
  "success": true,
  "walletAddress": "0x...",
  "message": "Wallet created successfully"
}

Example Usage

cURL:

curl -X POST http://localhost:8090/api/v1/admin/createwallet \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN_HERE" \
  -d '{}'

📝 Admin Notes

Error Handling

All Admin APIs return consistent error responses:

{
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": {}
}

Common Error Codes

• SUPERUSER_REQUIRED: Superuser access required
• INVALID_PARAMS: Invalid parameters
• INSUFFICIENT_BALANCE: Insufficient token balance
• TRANSACTION_FAILED: Blockchain transaction failed

Rate Limiting

• Admin APIs have higher rate limits compared to user APIs
• Superuser operations have additional validation layers

Security

• All Admin APIs require Superuser authentication
• Additional validation for sensitive operations
• Private keys and sensitive data are never exposed in responses
• All operations are logged for audit purposes

Token Amounts

• All token amounts should be provided in wei (smallest unit)
• Use appropriate conversion functions for different token decimals
• Example: 1 USDT = 1000000 (6 decimals)

Transaction Status

• Use Queue Status API (/api/v1/queue) to track transaction progress
• Admin transactions may take time to confirm on blockchain
• Implement polling mechanism for real-time updates

Best Practices

1. Always validate input parameters before making API calls
2. Use proper error handling for all API responses
3. Monitor transaction status using Queue Status API
4. Keep admin credentials secure and rotate regularly
5. Log all admin operations for audit trails
6. Test on testnet before mainnet operations