Create Loan import { usePostLoan } from '@/services/hooks/mutations/use-post-loan' ; const { mutate : createLoan } = usePostLoan (); createLoan ({ userId: '79f970d7-3b2f-492c-a358-6c1f1c2fd429' , ratio: '1.5' , size: '1' , typeId: 'ETH_USDT' });
Create a new collateralized loan. The loan is immediately active upon creation and begins accruing interest based on the collateral ratio tier.
Request Body Target collateral ratio for the loan. Must meet the minimum collateral ratio requirements for the loan type. Higher ratios result in lower APR rates based on tier structure. Example: "1.5" for 150% collateralization
The loan amount in the size currency (e.g., USDT). Must be within the loan type’s min/max size limits. Example: "1" for 1 USDT
The loan type identifier specifying the collateral and size currencies. Available types: ETH_USDT, BTC_USDT
Response The loan type identifier (e.g., ETH_USDT)
Unique identifier for this loan operation
User ID who created the loan
Current owner of the loan
Timestamp when the loan was opened (ISO 8601)
Timestamp of the last update (ISO 8601)
Timestamp when the loan was closed, or null if still active
Current operation status: ACTIVE, COMPLETED
Currency of the loan amount (e.g., USDT)
Currency of the collateral (e.g., ETH, BTC)
Loan status: ACTIVE, REPAYED, LIQUIDATED
Original loan amount in size currency
Current collateral amount in collateral currency
Total amount repaid so far
Current outstanding debt including interest
Current collateral ratio (collateral value / debt) Example: "1.4999964170901844" represents ~150% collateralization
Liquidation price - the collateral price at which the loan will be liquidated
Current annual percentage rate based on the active tier Example: "0.135" represents 13.5% APR
Current tier index (0-based) determining the APR
Minimum collateral required to maintain the loan
Collateral ratio at loan creation
Initial collateral amount
Initial debt including origination fee
Origination fee charged at loan creation
APR tier structure based on collateral ratio Minimum ratio required for this tier
Minimum collateral price for this tier
Details of the most recent loan event Event type: CREATE, ADD_COLLAT, REM_COLLAT, REPAY, LIQUIDATE
Loan status after this event
APR at the time of the event
Change in collateral amount (delta)
Change in repaid amount (delta)
Amount of collateral liquidated (if applicable)
Collateral price at the time of the event
Fees charged for this event
Change in tier number (delta)
Whether this was a forced liquidation
Whether the loan is subject to forced liquidation
Response Example { "typeId" : "ETH_USDT" , "operation" : { "id" : "2c7ce71e-8dc8-4dd2-97e1-3d9716a1874d" , "creatorId" : "79f970d7-3b2f-492c-a358-6c1f1c2fd429" , "ownerId" : "79f970d7-3b2f-492c-a358-6c1f1c2fd429" , "openedAt" : "2026-01-29T14:44:45.257241494Z" , "updatedAt" : "2026-01-29T14:44:45.257241494Z" , "closedAt" : null , "status" : "ACTIVE" , "type" : "LOAN" }, "sizeCurrencyId" : "USDT" , "collatCurrencyId" : "ETH" , "status" : "ACTIVE" , "size" : "1" , "collat" : "0.00051709" , "repayed" : "0" , "debt" : "1.01" , "interest" : "0" , "ratio" : "1.4999964170901844" , "liqPrice" : "2328.8015625906515307" , "apr" : "0.135" , "tierNum" : 0 , "minCollat" : "0.0005170912351275" , "initialAPR" : "0.135" , "initialRatio" : "1.4999964170901844" , "initialSize" : "1" , "initialCollat" : "0.00051709" , "initialDebt" : "1.0035" , "origFee" : "0.0035" , "tiers" : [ { "minRatio" : "1.2" , "minPrice" : "2328.8015625906515307" , "apr" : "0.135" }, { "minRatio" : "1.5" , "minPrice" : "2911.0019532383144134" , "apr" : "0.0975" }, { "minRatio" : "2" , "minPrice" : "3881.3359376510858845" , "apr" : "0.05" } ], "lastUpdate" : { "createdAt" : "2026-01-29T14:44:45.257241494Z" , "type" : "CREATE" , "status" : "ACTIVE" , "apr" : "0.135" , "dCollat" : "0.00051709" , "dRepayed" : "0" , "liqCollat" : "0" , "price" : "2910.995" , "dFees" : "0.0035" , "dTierNum" : 0 , "forcedLiq" : false }, "forcedLiq" : false }
Repay Loan import { usePostLoanManager } from '@/services/hooks/mutations/use-post-loan-manager' ; const { mutate : repayLoan } = usePostLoanManager ( 'repay' ); repayLoan ({ userId: '79f970d7-3b2f-492c-a358-6c1f1c2fd429' , opId: '2c7ce71e-8dc8-4dd2-97e1-3d9716a1874d' , amount: '1.992138092931196373' });
Repay part or all of an active loan. When the debt is fully repaid, the loan status changes to REPAYED and remaining collateral is returned to the user.
Path Parameters The loan operation ID to repay
Request Body The amount to repay in the size currency. Can be partial or full repayment. Example: "1.992138092931196373" to repay 1.99 USDT
Response Returns the updated loan object with the same structure as the Create Loan response. The repayed field will be updated, and debt will be reduced accordingly.
Liquidate Loan POST /loan/{opId}/liquidate
import { usePostLoanManager } from '@/services/hooks/mutations/use-post-loan-manager' ; const { mutate : liquidateLoan } = usePostLoanManager ( 'liquidate' ); liquidateLoan ({ userId: '79f970d7-3b2f-492c-a358-6c1f1c2fd429' , opId: 'edaa7bd5-00d6-40b6-8b27-f21e3b06c561' , amount: '10.085159966953139616' });
Liquidate collateral to repay part of the loan. This sells collateral at current market price to reduce debt, useful when you want to maintain your loan position while reducing risk.
Path Parameters The loan operation ID to liquidate
Request Body The amount of debt to repay through liquidation (in size currency). The system will liquidate enough collateral at current market price to cover this amount plus liquidation fees. Example: "10.085159966953139616" to liquidate collateral worth ~10 USDT
Response Returns the updated loan object. The lastUpdate.type will be REPAY_COLLAT and will include:
liqCollat: Amount of collateral liquidatedliqCollatValue: Value of liquidated collateral in size currencyprice: Execution pricefee: Liquidation fee charged
Get Loan History import { useLoanHistoryEvents } from '@/services/hooks/use-loan-history-events' ; const { data : historyEvents } = useLoanHistoryEvents ({ userId: '79f970d7-3b2f-492c-a358-6c1f1c2fd429' , opId: '389ae85b-7968-4086-b7e3-2b53dc4fe6ed' , enabled: true });
Retrieve the complete history of events for a loan, including collateral changes, repayments, APR updates, and liquidations.
Path Parameters The loan operation ID to retrieve history for
Response Array of loan history events in chronological order Timestamp when the event occurred (ISO 8601)
Event type:
ADD_COLLAT: Collateral was addedREM_COLLAT: Collateral was removedREPAY_SIZE: Loan repayment in size currencyREPAY_COLLAT: Debt repaid via collateral liquidationUPDATE_APR: APR tier changed due to ratio change Event-specific data fields Currency involved in the event (for ADD_COLLAT, REM_COLLAT, REPAY_SIZE)
Amount of currency involved
Amount of collateral liquidated (for REPAY_COLLAT)
Value of liquidated collateral in size currency
Amount repaid from liquidation
Execution price for liquidation
Fee charged for the liquidation
New APR value (for UPDATE_APR events)
Response Example [ { "createdAt" : "2025-12-09T20:13:57.572519Z" , "type" : "ADD_COLLAT" , "data" : { "currencyId" : "ETH" , "amount" : "0.03122094" } }, { "createdAt" : "2025-12-09T20:14:40.951945Z" , "type" : "REM_COLLAT" , "data" : { "currencyId" : "ETH" , "amount" : "0.04018674" } }, { "createdAt" : "2025-12-09T20:14:40.951945Z" , "type" : "UPDATE_APR" , "data" : { "apr" : "0.135" } }, { "createdAt" : "2025-12-09T20:15:21.621333Z" , "type" : "REPAY_COLLAT" , "data" : { "liqCollat" : "0.003006609357741528" , "liqCollatValue" : "10.08515996695313961624" , "repayed" : "10.085159966953139616" , "price" : "3354.33" , "fee" : "0.035298059884335989" } }, { "createdAt" : "2025-12-09T20:15:28.584195Z" , "type" : "REPAY_SIZE" , "data" : { "currencyId" : "USDT" , "amount" : "1.992138092931196373" } }, { "createdAt" : "2025-12-09T20:15:28.584195Z" , "type" : "REM_COLLAT" , "data" : { "currencyId" : "ETH" , "amount" : "0.002379720642258472" } } ]
TypeScript Types // Loan creation request interface CreateLoanRequest { userId : string ; ratio : string ; // Target collateral ratio size : string ; // Loan amount typeId : string ; // Loan type (e.g., "ETH_USDT") } // Loan management request (add/remove collateral, repay, liquidate) interface LoanManagerRequest { userId : string ; opId : string ; // Loan operation ID amount : string ; // Amount for the operation } // Loan response structure interface Loan { typeId : string ; operation : { id : string ; creatorId : string ; ownerId : string ; openedAt : string ; updatedAt : string ; closedAt : string | null ; status : 'ACTIVE' | 'COMPLETED' ; type : string ; fullType : string ; }; sizeCurrencyId : string ; collatCurrencyId : string ; status : 'ACTIVE' | 'REPAYED' | 'LIQUIDATED' ; size : string ; collat : string ; repayed : string ; debt : string ; interest : string ; ratio : string ; liqPrice : string ; apr : string ; tierNum : number ; minCollat : string ; initialAPR : string ; initialRatio : string ; initialSize : string ; initialCollat : string ; initialDebt : string ; origFee : string ; tiers : Array <{ minRatio : string ; minPrice : string ; apr : string ; }>; lastUpdate : { createdAt : string ; type : 'CREATE' | 'ADD_COLLAT' | 'REM_COLLAT' | 'REPAY' | 'LIQUIDATE' ; status : string ; apr : string ; dCollat : string ; dRepayed : string ; liqCollat : string ; price : string ; dFees : string ; dTierNum : number ; forcedLiq : boolean ; }; forcedLiq : boolean ; } // Loan history event interface LoanHistoryEvent { createdAt : string ; type : 'ADD_COLLAT' | 'REM_COLLAT' | 'REPAY_SIZE' | 'REPAY_COLLAT' | 'UPDATE_APR' ; data : { currencyId ?: string ; amount ?: string ; liqCollat ?: string ; liqCollatValue ?: string ; repayed ?: string ; price ?: string ; fee ?: string ; apr ?: string ; }; }
