Điểm cuối API - Tài liệu API

URL cơ sở

Môi trường sản xuất: https://api.usdtlowfee.com

Quy ước chung

Đơn vị

• sun: 1 TRX = 1.000.000 sun (tất cả các trường số tiền sử dụng sun)
• energyValue: đơn vị năng lượng (số int64)
• durationHours: giờ (số int)

Kiểu dữ liệu

• Trường ID: số int64 (snowflake ID)
• Trường số tiền: số int64 (hậu tố *Sun, ví dụ: balanceSun, priceSun)
• Trường thời gian: chuỗi (định dạng ISO8601 UTC, ví dụ: "2025-01-15T10:30:00Z")
• Trường boolean: true/false

Định dạng phản hồi

• Thành công: { "data": {...}, "meta": {...} } (meta tùy chọn)
• Lỗi: { "error": { "code": "...", "message": "..." } }

Quản lý tài khoản

Truy vấn số dư ví và thông tin người dùng

GET /v1/wallet/balance

Lấy số dư

Lấy số dư ví hiện tại

Ví dụ phản hồi:

{
  "data": {
    "balanceSun": 1000000,
    "frozenSun": 0,
    "totalSun": 1000000
  }
}

GET /v1/users/me

Thông tin người dùng

Lấy thông tin cơ bản của người dùng hiện tại

Ví dụ phản hồi:

{
  "data": {
    "id": 123456,
    "email": "user@example.com",
    "emailVerified": true,
    "createdAt": "2025-01-01T00:00:00Z"
  }
}

Quản lý đơn hàng

Tạo và truy vấn đơn hàng năng lượng

POST /v1/energy/orders

Tạo đơn hàng

Tạo đơn hàng thuê năng lượng cho một địa chỉ được chỉ định (hiện tại chỉ hỗ trợ loại manual)

Tham số yêu cầu:

Tham số	Loại	Bắt buộc	Mô tả
type	string	Có	Loại đơn hàng, hiện tại chỉ hỗ trợ "manual"
data.tronAddress	string	Có	Địa chỉ TRON nhận năng lượng (34 ký tự, bắt đầu bằng T)
data.energyValue	int64	Có	Số lượng năng lượng (số, tối thiểu 32000, khuyến nghị 65000 cho chuyển USDT)
data.durationHours	int	Có	Thời hạn thuê (giờ, giá trị hợp lệ: 1, 24, 72, 168, 336, 720)

Ví dụ yêu cầu:

{
  "type": "manual",
  "data": {
    "tronAddress": "TYour1Address2Here3...",
    "energyValue": 65000,
    "durationHours": 1
  }
}

Ví dụ phản hồi:

{
  "data": {
    "id": 1234567890,
    "userId": 9876543210,
    "tronAddress": "TYour1Address2Here3...",
    "energyValue": 65000,
    "durationHours": 1,
    "priceSun": 3000000,
    "priceTrx": 3.0,
    "orderType": "manual",
    "status": "processing",
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-15T10:30:00Z",
    "statusUpdatedAt": "2025-01-15T10:30:00Z",
    "canTransitionTo": ["completed", "failed"]
  }
}

GET /v1/energy/orders/:id

Lấy đơn hàng

Truy vấn chi tiết đơn hàng theo ID đơn hàng

Ví dụ phản hồi:

{
  "data": {
    "id": 1234567890,
    "userId": 9876543210,
    "tronAddress": "TYour1Address2Here3...",
    "energyValue": 65000,
    "durationHours": 1,
    "priceSun": 3000000,
    "priceTrx": 3.0,
    "orderType": "manual",
    "status": "completed",
    "txid": "abc123...",
    "createdAt": "2025-01-15T10:30:00Z",
    "completedAt": "2025-01-15T10:30:05Z",
    "updatedAt": "2025-01-15T10:30:05Z",
    "statusUpdatedAt": "2025-01-15T10:30:05Z",
    "canTransitionTo": []
  }
}

GET /v1/energy/orders

Liệt kê đơn hàng

Truy vấn danh sách đơn hàng (hỗ trợ phân trang và lọc)

Tham số yêu cầu:

Tham số	Loại	Bắt buộc	Mô tả
offset	number	Không	Độ lệch, mặc định 0
limit	number	Không	Số mục mỗi trang, mặc định 20, tối đa 100
status	string	Không	Lọc theo trạng thái đơn hàng: processing, completed, failed

Ví dụ phản hồi:

{
  "data": {
    "orders": [
      {
        "id": 1234567890,
        "userId": 9876543210,
        "tronAddress": "TYour1...",
        "energyValue": 65000,
        "durationHours": 1,
        "priceSun": 3000000,
        "priceTrx": 3.0,
        "orderType": "manual",
        "status": "completed",
        "createdAt": "2025-01-15T10:30:00Z",
        "updatedAt": "2025-01-15T10:30:05Z",
        "statusUpdatedAt": "2025-01-15T10:30:05Z",
        "canTransitionTo": []
      }
    ],
    "total": 100,
    "offset": 0,
    "limit": 20
  }
}

Quản lý địa chỉ

Quản lý các địa chỉ nhận thường dùng

POST /v1/addresses

Thêm địa chỉ

Lưu một địa chỉ mới

Ví dụ yêu cầu:

{
  "tronAddress": "TYour1Address2Here3...",
  "label": "Ví chính",
  "isDefault": false
}

Ví dụ phản hồi:

{
  "data": {
    "id": 1,
    "tronAddress": "TYour1Address2Here3...",
    "label": "Ví chính",
    "isDefault": false,
    "usageCount": 0,
    "createdAt": "2025-01-01T00:00:00Z"
  }
}

GET /v1/addresses

Liệt kê địa chỉ

Lấy danh sách địa chỉ đã lưu

Ví dụ phản hồi:

{
  "data": {
    "addresses": [
      {
        "id": 1,
        "tronAddress": "TYour1Address2Here3...",
        "label": "Ví chính",
        "isDefault": true,
        "usageCount": 5,
        "lastUsedAt": "2025-01-15T10:30:00Z",
        "createdAt": "2025-01-01T00:00:00Z"
      }
    ],
    "total": 1
  }
}

GET /v1/addresses/:id

Lấy chi tiết địa chỉ

Truy vấn thông tin một địa chỉ

Ví dụ phản hồi:

{
  "data": {
    "id": 1,
    "tronAddress": "TYour1Address2Here3...",
    "label": "Ví chính",
    "isDefault": true,
    "usageCount": 5,
    "lastUsedAt": "2025-01-15T10:30:00Z",
    "createdAt": "2025-01-01T00:00:00Z"
  }
}

PUT /v1/addresses/:id/label

Cập nhật nhãn địa chỉ

Sửa đổi nhãn của một địa chỉ

Ví dụ yêu cầu:

{
  "label": "Nhãn mới"
}

Ví dụ phản hồi:

{
  "data": {
    "id": 1,
    "tronAddress": "TYour1Address2Here3...",
    "label": "Nhãn mới",
    "isDefault": false,
    "usageCount": 3,
    "lastUsedAt": "2025-01-15T10:30:00Z",
    "createdAt": "2025-01-01T00:00:00Z"
  }
}

PUT /v1/addresses/:id/default

Đặt địa chỉ mặc định

Đặt địa chỉ được chỉ định làm địa chỉ nhận mặc định

Ví dụ phản hồi:

// HTTP 204 No Content
// Không có nội dung phản hồi

Trả về mã trạng thái 204 không có nội dung khi thành công.

DELETE /v1/addresses/:id

Xóa địa chỉ

Xóa một địa chỉ đã lưu