Skip to main content

Open a trove

POST 
/v1/actions/liquity/open

Open a trove: deposit collateral and mint stable debt at a user-set annual interest rate.

Liquity V2 family is a pooled CDP — one branch per collateral, troves = sub-accounts (troveId, the sub-account id from user data), user-set adjustable interest rates, and a per-branch Stability Pool as the stable-token earn side. Deployments: LIQUITY_V2 (Ethereum) + friendly forks (USDAF, FELIX, NERITE, QUILL, ENOSYS_LOANS, SONETA, EBISU) — all share this surface; per-fork parameters (min debt, rate bounds, gas compensation) come from metadata.

Standard lending actions cover the day-to-day ops for a <DEPLOYMENT>_<chainId>_<COLL_INDEX> market key:

  • stable-token deposit/withdraw → Stability Pool (earn; isAll withdraw uses the protocol sentinel)
  • collateral deposit/withdraw → addColl/withdrawColl (pass troveId)
  • borrow → withdrawBold (pass troveId; upfront-fee guard quoted automatically, override with maxUpfrontFee)
  • repay → repayBold clamped to entireDebt − minDebt; isAll=true routes to closeTrove (burns the full live debt from the wallet, returns collateral + the WETH gas compensation)

The endpoints in this section handle the trove lifecycle ops that need more than one amount or no amount at all. Fees to know: the upfront borrowing fee (≈7 days of average branch interest on any debt increase) and the premature rate-adjustment fee (same formula on the WHOLE debt when changing the rate within the cooldown). Repaying itself is always free.

Validates the deployment's min debt + rate bounds, quotes SortedTroves insert hints and the maxUpfrontFee guard on-chain, and picks the next free owner index. Returns the transaction plus the collateral (+ gas-compensation WETH) approvals.

interestRate is OPTIONAL: omit it and the trove opens at the branch average user-set rate (the rate the market data quotes as the branch borrow rate — mid-pack in the redemption queue). The applied rate is returned as interestRate in the response data; change it later with POST /v1/actions/liquity/set-rate.

Request​

Responses​