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.

Plain-text reference — POST /v1/actions/liquity/open

Request body

FieldTypeRequiredDescription
chainIdstringyesEVM chain id, as a decimal string. See the ChainId schema.
lenderstringyesPer-branch key, e.g. LIQUITY_V2_1_0
accountstringyesTrove owner (tx sender)
collAmountstringyesCollateral amount, raw units
amountstringyesStable debt to mint, raw units (≥ deployment minDebt)
interestRatestringnoOptional user-set annual rate, WAD (1e16 = 1%). Default: the branch average rate.
ownerIndexstringnoOptional explicit owner index (default: next free)
maxUpfrontFeestringnoOptional fee-guard override, raw stable units

Response 200

FieldTypeDescription
successTrue
dataobjectInformational data (quotes, simulation results, etc.)
actionsobjectTransaction calldata and approvals. Null for quote-only responses (no account provided).
actions.transactionsobject[]Pre-trade setup transactions (e.g. e-mode switch, collateral enable). Execute these before the main swap. Empty when no setup is needed.
actions.transactions[].tostringTarget contract address
actions.transactions[].datastringEncoded calldata
actions.transactions[].valuestringETH value to send with the transaction
actions.transactions[].descriptionstringHuman-readable label. For alternatives, this is the aggregator name (e.g. "Paraswap"). For transactions, describes the setup action (e.g. "Switch e-mode to 1").
actions.alternativesobject[]DEX aggregator swap transactions sorted by best output (descending). Each entry's description is the aggregator name. The client should pick one to execute. Present on loop action endpoints.
actions.alternatives[].tostringTarget contract address
actions.alternatives[].datastringEncoded calldata
actions.alternatives[].valuestringETH value to send with the transaction
actions.alternatives[].descriptionstringHuman-readable label. For alternatives, this is the aggregator name (e.g. "Paraswap"). For transactions, describes the setup action (e.g. "Switch e-mode to 1").
actions.permissionsobject[]Approval/delegation transactions that must execute before both transactions and alternatives. Includes ERC20 allowances (targeting the composer contract) and lender borrow/withdrawal delegations (targeting the lending protocol contract directly). Filtered against on-chain state so only missing approvals are returned. Null when no approvals are needed.
actions.permissions[].tostringTarget contract address
actions.permissions[].datastringEncoded calldata
actions.permissions[].valuestringETH value
actions.permissions[].descriptionstringHuman-readable description of the approval (e.g. "Approve borrow for AAVE_V3", "Approve ERC20")
actions.permissions[].spenderstringERC-20 approve spender (x-chain permissions). Match it against the selected quote's approvalTarget — several bridges can share one spender, so do not match by description.

Example response

{
  "success": true,
  "data": {},
  "actions": {
    "transactions": [
      {
        "to": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
        "data": "0x617ba037000000000000000000000000c02aaa39b2",
        "value": "0",
        "description": "string"
      }
    ],
    "alternatives": [
      {
        "to": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
        "data": "0x617ba037000000000000000000000000c02aaa39b2",
        "value": "0",
        "description": "string"
      }
    ],
    "permissions": [
      {
        "to": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
        "data": "0x617ba037000000000000000000000000c02aaa39b2",
        "value": "0",
        "description": "string",
        "spender": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
      }
    ]
  }
}

Request​

Responses​

Open-trove transaction + approvals