Skip to main content

Close the trove

GET 
/v1/actions/river/close

Close the caller's trove on a market: burns entireDebt − gasCompensation satUSD from the wallet, returns all collateral. Blocked in Recovery Mode (global TCR < 150%). Equivalent to lending/repay with isAll=true.

River (rebranded Satoshi Protocol) is a Prisma-lineage pooled CDP minting satUSD behind one SatoshiXApp diamond per chain (BNB, Base, Hemi). One TroveManager per collateral = one RIVER_<chainId>_<TM_INDEX> market; troves are keyed by OWNER ADDRESS — at most one per user per market, no ids. Interest is protocol-set (currently 0%); the only borrowing cost is a one-off decaying-baseRate mint fee (0.5%–5%) on open/borrow-more, guarded by maxFeePercentage (quoted automatically).

Standard lending actions cover the day-to-day ops:

  • satUSD deposit/withdraw → the single per-chain Stability Pool (attached to market index 0; zero approvals)
  • collateral deposit/withdraw → addColl/withdrawColl (no troveId — address-keyed)
  • borrow → withdrawDebt (mint fee applies)
  • repay → repayDebt clamped to entireDebt − gasComp − minNetDebt; isAll=true routes to closeTrove (burns entireDebt − gasComp from the wallet, returns all collateral; blocked in Recovery Mode)

The 2-satUSD debt-side gas compensation is minted on open and burned from the GasPool on close — it never touches the wallet.

Plain-text reference — GET /v1/actions/river/close

Parameters

ParameterInTypeRequiredDescription
chainIdquerystringyesChain id See the ChainId schema for the full set of supported chains.
lenderquerystringyesPer-market key, e.g. RIVER_8453_0 See the LenderId schema for the full set of accepted values.
operatorquerystringyesTrove owner

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[].chainTypeevmWhich VM executes this step. ABSENT means evm, which is the only value any endpoint returns today — every EVM response is unchanged. A non-EVM chain would return a different shape (a serialized, PERISHABLE transaction rather than to/data/value) carrying its own chainType, so a client that wants to stay forward-compatible should branch on this field rather than assume to is present.
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[].chainTypeevmWhich VM executes this step. ABSENT means evm, which is the only value any endpoint returns today — every EVM response is unchanged. A non-EVM chain would return a different shape (a serialized, PERISHABLE transaction rather than to/data/value) carrying its own chainType, so a client that wants to stay forward-compatible should branch on this field rather than assume to is present.
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.
actions.permissions[].typeERC20, LenderWhat kind of grant this is. A signatures[] offer names the type it replaces via its replaces field.
actions.signaturesobject[]EIP-712 payloads the user can sign INSTEAD of sending the corresponding permissions entry. Only present when the caller opted in with permit=auto|required and a permit path exists. Sign with eth_signTypedData_v4, then POST the same endpoint with {permits: [{permitId, signature}]} (plus builds where the response issued buildIds) — the permit executes inside the main transaction.
actions.signatures[].permitIdstringOpaque, self-describing handle for this permit. Round-trip it verbatim: POST {permits: [{permitId, signature}]} back to the same endpoint.
actions.signatures[].kinderc2612, dai, permit2, aaveCredit, morphoAuth, cometAuthPermit flavour
actions.signatures[].typedDataobjectReady for eth_signTypedData_v4 (domain, types incl. EIP712Domain, primaryType, message). All numeric fields are decimal strings.
actions.signatures[].replacesstringWhich permissions entry this signature replaces (ERC20 | Lender)
actions.signatures[].spenderstringWho the signature authorises. Match against the permission / quote (approvalTarget) it replaces — on multi-spender responses (x-chain) only routes whose approvalTarget equals this spender are covered by the signature.
actions.signatures[].descriptionstringHuman-readable label for this entry.
actions.signatures[].unscopedbooleanTrue when the grant is NOT amount-scoped (full position control until revoked) — surface this to the user.
actions.signatures[].deadlinestringUnix seconds after which the signature is worthless (default: 30 minutes).
actions.permitSkippedobject[]Why a permit was NOT offered for a permission, when one was asked for (permit=auto|required). The corresponding approve transaction stands.
actions.permitSkipped[].replacesstringWhich permission kind stays a transaction (ERC20 | Lender)
actions.permitSkipped[].reasonstring

Example response

{
  "success": true,
  "data": {},
  "actions": {
    "transactions": [
      {
        "chainType": "evm",
        "to": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
        "data": "0x617ba037000000000000000000000000c02aaa39b2",
        "value": "0",
        "description": "string"
      }
    ],
    "alternatives": [
      {
        "chainType": "evm",
        "to": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
        "data": "0x617ba037000000000000000000000000c02aaa39b2",
        "value": "0",
        "description": "string"
      }
    ],
    "permissions": [
      {
        "to": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
        "data": "0x617ba037000000000000000000000000c02aaa39b2",
        "value": "0",
        "description": "string",
        "spender": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
        "type": "ERC20"
      }
    ],
    "signatures": [
      {
        "permitId": "string",
        "kind": "erc2612",
        "typedData": {},
        "replaces": "string",
        "spender": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
        "description": "string",
        "unscoped": true,
        "deadline": "string"
      }
    ],
    "permitSkipped": [
      {
        "replaces": "string",
        "reason": "string"
      }
    ]
  }
}

Request​

Responses​

Close-trove transaction