API 엔드포인트 - API 문서

베이스 URL

프로덕션： https://api.usdtlowfee.com

일반 규칙

단위

• sun: 1 TRX = 1,000,000 sun (모든 금액 필드는 sun 사용)
• energyValue: 에너지 단위 (int64 숫자)
• durationHours: 시간 단위 (int 숫자)

데이터 타입

• ID 필드: int64 숫자 (snowflake ID)
• 금액 필드: int64 숫자 (*Sun 접미사, 예: balanceSun, priceSun)
• 시간 필드: 문자열 (ISO8601 UTC 형식, 예: "2025-01-15T10:30:00Z")
• 불린 필드: true/false

응답 형식

• 성공: { "data": {...}, "meta": {...} } (meta는 선택적)
• 오류: { "error": { "code": "...", "message": "..." } }

계정 관리

지갑 잔액 및 사용자 정보 조회

GET /v1/wallet/balance

잔액 조회

현재 지갑 잔액을 조회합니다

응답 예시：

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

GET /v1/users/me

사용자 정보

현재 사용자의 기본 정보를 조회합니다

응답 예시：

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

주문 관리

에너지 주문 생성 및 조회

POST /v1/energy/orders

주문 생성

지정된 주소에 대한 에너지 대여 주문을 생성합니다 (현재 manual 타입만 지원)

요청 매개변수：

매개변수	타입	필수	설명
type	string	예	주문 타입, 현재 "manual"만 지원
data.tronAddress	string	예	에너지를 받을 TRON 주소 (34자, T로 시작)
data.energyValue	int64	예	에너지 수량 (숫자, 최소 32000, USDT 전송 시 65000 권장)
data.durationHours	int	예	대여 기간 (시간 단위, 유효 값: 1, 24, 72, 168, 336, 720)

요청 예시：

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

응답 예시：

{
  "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

주문 조회

주문 ID로 주문 세부 정보를 조회합니다

응답 예시：

{
  "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

주문 목록 조회

주문 목록을 조회합니다 (페이징 및 필터링 지원)

요청 매개변수：

매개변수	타입	필수	설명
offset	number	아니오	오프셋, 기본값 0
limit	number	아니오	페이지당 항목 수, 기본값 20, 최대 100
status	string	아니오	주문 상태로 필터링: processing, completed, failed

응답 예시：

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

주소 관리

자주 사용하는 수신 주소 관리

POST /v1/addresses

주소 추가

새 주소를 저장합니다

요청 예시：

{
  "tronAddress": "TYour1Address2Here3...",
  "label": "Main Wallet",
  "isDefault": false
}

응답 예시：

{
  "data": {
    "id": 1,
    "tronAddress": "TYour1Address2Here3...",
    "label": "Main Wallet",
    "isDefault": false,
    "usageCount": 0,
    "createdAt": "2025-01-01T00:00:00Z"
  }
}

GET /v1/addresses

주소 목록 조회

저장된 주소 목록을 조회합니다

응답 예시：

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

GET /v1/addresses/:id

주소 상세 조회

단일 주소 정보를 조회합니다

응답 예시：

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

PUT /v1/addresses/:id/label

주소 라벨 수정

주소의 라벨을 수정합니다

요청 예시：

{
  "label": "New Label"
}

응답 예시：

{
  "data": {
    "id": 1,
    "tronAddress": "TYour1Address2Here3...",
    "label": "New Label",
    "isDefault": false,
    "usageCount": 3,
    "lastUsedAt": "2025-01-15T10:30:00Z",
    "createdAt": "2025-01-01T00:00:00Z"
  }
}

PUT /v1/addresses/:id/default

기본 주소 설정

지정된 주소를 기본 수신 주소로 설정합니다

응답 예시：

// HTTP 204 No Content
// 응답 본문 없음

성공 시 상태 코드 204와 함께 내용 없이 반환됩니다.

DELETE /v1/addresses/:id

주소 삭제

저장된 주소를 삭제합니다