npm install @hellobtu/sdk
# or
yarn add @hellobtu/sdk
Prerequisites
Download the required WASM file:
Get
Place it in your project's public/ directory
Network Support
The SDK supports testnet and EVM-compatible chain:
Use 'bitcoin_testnet' for testnet operations
Use 'BTUApi' for EVM-compatible chain operations
Registration
Check User's Status
import { getProInfo } from '@hellobtu/sdk'
// Check if a Bitcoin address is PRO
const info = await getProInfo('bitcoin_testnet', 'tb1q...')
console.log(info)
Returns:
{
feeAddress: string,
fee: number,
committee: string,
consumer: string,
isPro: 'none' | 'processing' | 'completed'
}
Upgrade to PRO
Note: You must first send the required fee to the feeAddress before calling this function.
import { upgradeToPro } from '@hellobtu/sdk'
// Upgrade a Bitcoin address to PRO status
const result = await upgradeToPro('bitcoin_testnet', 'tb1q...')
Bitcoin SDK
import { stakeBitcoin } from '@hellobtu/sdk'
// Configure staking parameters
const stakeProps = {
// Your Bitcoin address
address: 'tb1q...',
// Your Bitcoin public key
pubkey: '02...',
// Committee address to stake to
committee: 'tb1q...',
// Amount to stake (in satoshis)
amount: '1000000',
// Transaction fee rate (in sat/vB)
feeRate: 5,
// Destination chain ID (e.g., 11155111 for Sepolia testnet)
chainId: 11155111,
// Recipient address on the destination chain
recipient: '0x...',
// Your wallet provider (must implement signPsbt)
signer: walletProvider
}
// Execute staking transaction
const txHash = await stakeBitcoin('bitcoin_testnet', stakeProps)
console.log('Staking Transaction Hash:', txHash)
EVM SDK
Query functions
import { BTUApi } from '@hellobtu/sdk'
// Example
const btuApi = new BUTApi('chain_rpc_url')
await btuApi.getTotalSupplyForBTCC(token_contract_address)
await btuApi.getTotalSupplyForBTU(token_contract_address)
// Check channel deposit status
await btuApi.isDepositPaused(channel_contract_address)
// Get deposit channel fee.
await btuApi.depositFee(channel_contract_address)
// Get minium withdraw amount
await btuApi.miniumWithdrawAmount(channel_contract_address)
// Get maximum withdraw amount
await btuApi.maximumWithdrawAmount(channel_contract_address, user_address)
// Get withdraw channel fee.
await btuApi.withdrawFee(channel_contract_address)
// Basic borrow info
await btuApi.getBorrowInfo(stableVault_contract)
/**
* Fetch all borrowing records for the current user
* @param contract stableVault contract address
* @param address user address
* @param isAll true: get all history, false: get current unclosed record
* @returns BorrowRecord[]
*/
await btuApi.getBorrowHistory(stableVault_contract, user_address, isAll)
/**
* Fetch liquidation list
* @param contract stableVault Contract address
* @param start Start index
* @param end End index
* @returns -{start: number, total: number, records: BorrowRecord[] }
*/
await btuApi.getLiquidationList(stableVault_contract, start_index, end_index)
/**
* Calculate the BTCC received from liquidation given the BTU amout
* @param contract stableVault contract address
* @param amount Remaining borrowed for BTU
* @returns Receive BTCC amount
*/
await btuApi.computeReceiveBTCCAmount(stableVault_contract, BTU_amount, receive_BTCC)
Before borrowing BTU, you should prepare all the borrowing information like rates and the currency.
// Get the rate information
- stableVaulte.getAllRate()
The collateralization rate returns 15000 indicates 150%.
The interest rate returns 200 indicates 2%.
// Get the currency of BTCC/USDT
- stableVaulte.getPrice()
The price returns 90000000000, means 1 BTCC = 90,000 BTU
// Get the service fee
- stableVaulte.getFee()
The fee returns 10000, means 1 BTU.
// Initiate the process of borrowing
- BTCC.deposit(uint256 _amount, uint256 _time)
// Example
Using 1.5 BTCC as collateral to borrow BTU for 1 year
You should input (1.5 * 1e18, 3600*24*365) into the following function:
BTCC.deposit(1500000000000000000,31536000)
The user will receive 1.5 / 150% * 90000 = 90000 BTU as the principal of the borrowing.
And the interest fee is 90000 * 2% * 31536000 / 31536000 = 1,800 BTU.
Meanwhile, the fixed service fee is 1 BTU.
So the user needs to prepare a total of 90,000 + 1,800 + 1 = 91,801 BTU as the repayment.
Here are two ways to get detailed bill record information:
// Get the deposit and debt of a bill
- stableVault.getDebt(address addr_)
// Get more details of a bill by its index
- stableVault.getRecord(uint256 index_)
The index can be obtained through:
// Get the historical bill index list
- stableVault.getRecordHistoryIndex(address addr_)
// Get the current order index
- stableVault.getRecordIndex(address addr_)
Important:
the index should be used as (index_ - 1) as a funtion parameter.
Case 2. Add More Collateral
You can increase BTCC to your own address or others' address.
- BTCC.inc(address _usr, uint256 _amount)
// Add 0.4 BTCC to a debt address
BTCC.inc(0xa.., 400000000000000000)
Case 3. Repay Your Loan with BTU
// Before the deadline, users can make partial repayments
The current debt has a deposit of 1.9 BTCC and an outstanding balance of 91,801 BTU.
Assuming the user repays 35,801 BTU, at the current price of 1 BTCC = 84,000 BTU,
the repayment can be executed by calling BTU.withdraw(35801000000000000000000).
After the repayment, the outstanding balance of the bill will be 56,000 BTU.
The system only needs to retain 56,000 * 150% / 84,000 == 1 BTCC to maintain a healthy state.
Finally, 1.9 - 1 = 0.9 BTCC will be returned to the user.
// For full repayment, all BTCC will be returned to the user
This can be done by calling BTU.withdraw(90000000000000000000000).
An event, emit Repay(user_, btu_amount_), will be triggered to indicate the repayment (user address, repaid amount).
// The calculation formula of Repayment
((BBTC - BBTC') * Price) / (BTU - BTU') = 150%
BBTC: Initial collateral amount
BBTC': Returned collateral amount after repayment
BTU: Total debt amount
BTU': Current repayment amount
Case 4. Liquidate others' Debts
Process:
A liquidator repays the BTU owed by the borrower and receives the corresponding amount of BTCC based on the current market price. If there are any remaining BTCC, it will be returned to the borrower.
Example:
User A has collateralized 15 BTCC with a current price of 1 BTCC = 100 BTU. As the collateralization rate is 150%, user A can borrow 1000 BTU.
The system price is a delayed price. When the price drops to 1 BTCC = 80 BTU, the account is facing liquidation. At this time, user B liquidates the debt owed by user A with 1000 BTU.
According to the current market price, 1000 BTU is equivalent to 12.5 BTCC. The reward rate is 0.2%. So user B receives 12.5 BTCC as the liquidation principal and 0.025 BTCC (12.5 BTCC * 0.2%) as the liquidation reward.
The remaining 15 - 12.5 - 0.025 = 2.475 BTCC is returned to user A.
Profit:
Liquidation Reward: The liquidator receives 0.025 BTCC as the liquidation reward from the borrower.
Market Arbitrage: When the market price goes up to 1 BTCC = 85 BTU, user B can choose to sell BTCC to cash.
Assuming a price drop causes the bill to become insolvent, or if the bill is overdue, liquidation can be initiated.
After an order times out, there will be a delay period. Liquidation can only occur after the delay period has passed.
// To get the Delay period
- stableVault.getBufferPeriod()
// To check the current Loan-to-Value (LTV) ratio of a user's debt bill
stableVault.getCurLtvRate(address addr_)
// To query for liquidatable bills in pages
- stableVault.getliqRecord(uint256 begin, uint256 end)
// To liquidate an order
- BTU.liquidate(address _liqAddress)
// After a debt is liquidated, view the liquidation history index
- stableVault.getRecordLiquidationHistoryIndex(address user)
// To query the liquidation reward rate
- stableVault.getRewardsRate()
