User, Bank, Wallet, History

Modul ini mencakup endpoint data pengguna yang sudah login: bind phone/2FA, rekening bank, wallet & coins, histori transaksi, pajak, serta API key.

Semua response mengikuti envelope di docs/bitwewe/api-conventions.

Ringkasan route

API v1 (protected: auth.xtoken, verified:api)

Method	Path	Controller@method
POST	/api/users/phone-bind	UserController@bindPhone
POST	/api/users/twofa-bind	UserController@bindTwoFA
POST	/api/users/twofa-unbind	UserController@unBindTwoFA
GET	/api/user/bank	UserController@getBankList
POST	/api/user/bank	UserController@addBank
PUT	/api/user/bank	UserController@editBank
DELETE	/api/user/bank/{id}	UserController@deleteBank
GET	/api/users/coins	UserController@listCoin
GET	/api/users/wallet	UserController@retrieveWallet
POST	/api/users/wallet-address-check	UserController@walletAddressCheck
GET	/api/users/transaction-histories	UserController@listTransactionHistory
GET	/api/users/history/v2/deposit-withdraw	UserController@listDepositWithdrawalHistory
GET	/api/users/history/deposit-withdraw	UserController@v2ListDepositWithdrawalHistory
GET	/api/users/history/tax	UserController@listTaxHistory
GET	/api/users/history/tax/report	UserController@listTaxHistoryReport
PATCH	/api/users/language	UserController@updateLanguage
PATCH	/api/users/currency	UserController@updateCurrency
POST	/api/user/api-key	UserController@addApiKey
PUT	/api/user/api-key	UserController@editApiKey
DELETE	/api/user/api-key	UserController@deleteApiKey
GET	/api/user/api-key	UserController@listApiKey
POST	/api/user/suspend	UserController@suspend

---

Bind phone

• Route: POST /api/users/phone-bind
• Request validation: BindPhoneRequest

Payload

Field	Type	Required	Catatan
phone	string	Ya	phone:countryCode, harus unik
countryCode	string	Ya	required_with phone
dialCode	string	Ya	contoh +62
otpCode	string	Ya	OTP SMS

Behavior penting

• Cek blacklist phone.
• Batasi percobaan OTP per IP + nomor; jika berulang gagal bisa masuk blacklist.
• OTP diverifikasi via SmsUtil->verifyOtp().

Response sukses

message: api.mobile_verified

Response gagal umum

• api.phone_number_blacklisted
• api.otp_verification_code_invalid
• pesan validasi request

---

Bind / Unbind 2FA

• Bind: POST /api/users/twofa-bind
• Unbind: POST /api/users/twofa-unbind
• Request validation: BindTwoFARequest

Payload

{ "otpCode": "123456" }

Behavior

• Verifikasi OTP Google Authenticator dengan secret user.
• Bind: set bind2FA = true.
• Unbind: set bind2FA = false, generate secret baru.

Response gagal umum

• auth.otp_failed (HTTP 403)

---

Rekening bank user

• List: GET /api/user/bank
• Add: POST /api/user/bank
• Edit: PUT /api/user/bank
• Delete: DELETE /api/user/bank/{id}

Payload add (BankAddRequest)

Field	Type	Required
bankId	string/number	Ya
bankName	string	Ya
account	number	Ya
bankOwner	string	Ya
address	string	Ya

Payload edit (BankEditRequest)

Semua field add + userBankAddressId (required).

Response sukses

• add: api.bank_added_successfully
• edit: api.bank_updated_successfully
• delete: api.bank_deleted_successfully
• list: api.user_banks_retrieved_successfully (data array)

Response gagal umum

• api.bank_not_found (edit/delete)
• pesan validasi request

---

Wallet & coins

Endpoints

Method	Path	Fungsi
GET	/api/users/coins	daftar coin, balance, jaringan alamat, withdrawal fee
GET	/api/users/wallet	total worth user (fiat + BTC)
POST	/api/users/wallet-address-check (v1)	cek apakah address+chain ada di sistem

Wallet address check (v1)

Payload:

{
  "address": "0x...",
  "chain_id": 1
}

Output data:

{
  "address": "0x...",
  "chain_id": 1,
  "exists": true
}

---

Transaction history & tax

Transaction histories

• GET /api/users/transaction-histories

Query opsional:

• symbol
• action
• per_page
• page
• sortBy
• sort

Response data biasanya berisi:

• data (array transaksi)
• currentPage
• totalData
• perPage
• nextPage

Deposit/withdraw history gabungan

• GET /api/users/history/v2/deposit-withdraw
• GET /api/users/history/deposit-withdraw

Query umum:

• currencyType (FIAT / COIN)
• symbol
• startDate
• endDate
• per_page
• page

Controller menggabungkan data dari cash_deposit, user_deposit, user_withdrawal dengan union query.

Tax history

• GET /api/users/history/tax
• GET /api/users/history/tax/report (v1)

Filter umum:

• pair
• side
• year
• month (berlaku saat year diisi)

---

Update preferensi user

• PATCH /api/users/language

  • payload: { "language": "id" }
  • message sukses: api.language_updated_successfully

• PATCH /api/users/currency

  • payload: { "currency": "IDR" }
  • message sukses: api.currency_updated_successfully

---

API key user

• create: POST /api/user/api-key
• edit: PUT /api/user/api-key
• delete: DELETE /api/user/api-key
• list: GET /api/user/api-key

Validation dari ApiKeyRequest:

POST

Field	Required
apiName	Ya
emailOtpCode	Ya
permissions	Ya (array)
phoneOtpCode	Opsional

PUT

Field	Required
apiKeyId	Ya
apiKey	Ya
permissions	Ya (array)
secretKey	Opsional

DELETE

Field	Required
apiKeyId	Ya
apiKey	Ya

Response sukses:

• create: api.generate_key_successful (mengembalikan key+secret baru)
• edit: api.edit_api_key_successful
• delete: api.delete_api_key_successful
• list: api.list_api_key_successful

Response gagal umum:

• api.email_otp_error
• api.user_api_key_not_found