> For the complete documentation index, see [llms.txt](https://current-finance.gitbook.io/buildkit/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://current-finance.gitbook.io/buildkit/protocol-interface/lending-entry-point.md).

# Lending Entry Point

This page documents the public entry points for the lending protocol. Each section corresponds to a Move module under `protocol::*`.

***

## Mainnet Packages and Objects

### Protocol IDs

| Field               | Value                                                                |
| ------------------- | -------------------------------------------------------------------- |
| Protocol Package ID | `0xfe1d8929d13b00aaecd7642dec1c6d41cab82882a1b139efa46bf61dfd6380bf` |
| Protocol App ID     | `0xd4395f77a48f6d64af2008280c8dc06ee0fe69953a141e683935f6086d849177` |
| X Oracle Package ID | `0x144c57d6014488bc71c0902bddff482af090d13e2c61333ed903fe088220a92c` |
| X Oracle Object ID  | `0x7aca2c7d1aa11640f8de16c4b6a2c3a672eb69872eddd59ed22a073908840e1a` |

### Markets

| Market Type                                                                                       | Market Object ID                                                     |
| ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `fe1d8929d13b00aaecd7642dec1c6d41cab82882a1b139efa46bf61dfd6380bf::market_type::EthenaMarket`     | `0xeeef7e9abe201e16c3ca6417b91fa49bec28edcb077eb2fd4a1f126c251e6899` |
| `fe1d8929d13b00aaecd7642dec1c6d41cab82882a1b139efa46bf61dfd6380bf::market_type::MatrixGoldMarket` | `0xafe28c816d322a56bdab27b90d4b5e882a0a34ee2d9f02c6a07402a2b69be900` |
| `fe1d8929d13b00aaecd7642dec1c6d41cab82882a1b139efa46bf61dfd6380bf::market_type::AltCoinMarket`    | `0x6f5230c346e27132b8d4d92cb3f4f9c7f4e736d5c32b8f0a2b063c97e67d78f7` |
| `fe1d8929d13b00aaecd7642dec1c6d41cab82882a1b139efa46bf61dfd6380bf::market_type::EmberMarket`      | `0x8e85c433f791685c65fa66923110b8385e13f955daf8792ef805ce2d47139bbc` |
| `fe1d8929d13b00aaecd7642dec1c6d41cab82882a1b139efa46bf61dfd6380bf::market_type::MainMarket`       | `0x41f3d76aee8b20e53f7d0d395fdc09e241e683c7bc5d0f69674b545ee42549df` |

## Enter Market

**Module:** `protocol::enter_market`

Creates a new **obligation** (user position) within a market. The obligation is held by the market, ownership is proven by holding the `ObligationOwnerCap`.

### Functions

#### `enter_market<MarketType>`

**Target:** `<LENDING_PROTOCOL_PACKAGE_ID>::enter_market::enter_market`

Creates an obligation with the default eMode group and transfers the `ObligationOwnerCap` to the caller.

```move
public fun enter_market<MarketType>(
    app: &ProtocolApp,
    market: &mut Market<MarketType>,
    ctx: &mut TxContext,
)
```

#### `enter_market_return<MarketType>`

**Target:** `<LENDING_PROTOCOL_PACKAGE_ID>::enter_market::enter_market_return`

Same as `enter_market`, but returns the `ObligationOwnerCap` instead of transferring it. Useful for composability within programmable transaction blocks (PTBs).

```move
public fun enter_market_return<MarketType>(
    app: &ProtocolApp,
    market: &mut Market<MarketType>,
    ctx: &mut TxContext,
): ObligationOwnerCap
```

#### `enter_market_with_emode<MarketType>`

**Target:** `<LENDING_PROTOCOL_PACKAGE_ID>::enter_market::enter_market_with_emode`

Creates an obligation with a specific eMode group. Requires a `PackageCallerCap` with the `enter_market_with_emode` permission.

```move
public fun enter_market_with_emode<MarketType>(
    app: &ProtocolApp,
    cap: &PackageCallerCap,
    market: &mut Market<MarketType>,
    emode_group: u8,
    ctx: &mut TxContext,
): ObligationOwnerCap
```

### Events

| Event                    | Fields                                                                                 |
| ------------------------ | -------------------------------------------------------------------------------------- |
| `ObligationCreatedEvent` | `sender`, `market_type`, `obligation` (ID), `emode_group`, `obligation_admin_cap` (ID) |

***

## Deposit

**Module:** `protocol::deposit`

Deposits coins as collateral into an obligation. The protocol mints cTokens representing the deposited amount.

### Functions

#### `deposit<MarketType, CoinType>`

**Target:** `<LENDING_PROTOCOL_PACKAGE_ID>::deposit::deposit`

Deposits the provided coin into the obligation as collateral.

```move
public fun deposit<MarketType, CoinType>(
    app: &ProtocolApp,
    market: &mut Market<MarketType>,
    obligation_owner_cap: &ObligationOwnerCap,
    coin: Coin<CoinType>,
    clock: &Clock,
    ctx: &TxContext,
)
```

| Parameter              | Description                               |
| ---------------------- | ----------------------------------------- |
| `obligation_owner_cap` | Proves ownership of the target obligation |
| `coin`                 | The coin to deposit as collateral         |

### Events

| Event          | Fields                                                                                                              |
| -------------- | ------------------------------------------------------------------------------------------------------------------- |
| `DepositEvent` | `minter`, `market`, `obligation`, `deposit_asset`, `deposit_amount`, `ctoken_amount`, `total_ctoken_amount`, `time` |

***

## Oracle Price Update

**Module:** `x_oracle::user_oracle`

Operations that depend on asset prices (borrow, withdraw, liquidation) require fresh Pyth price feeds. Before calling these functions, you must refresh the price for every asset involved in the obligation (all collateral types and borrow types) within the same PTB.

### Functions

#### `refresh_usd_price<CoinType>`

**Target:** `<X_ORACLE_PACKAGE_ID>::user_oracle::refresh_usd_price`

Refreshes the USD price feed for a given coin type using the corresponding Pyth `PriceInfoObject`.

```move
public fun refresh_usd_price<CoinType>(
    x_oracle: &mut XOracle,
    price_info_object: &PriceInfoObject,
    clock: &Clock,
)
```

| Parameter           | Description                                          |
| ------------------- | ---------------------------------------------------- |
| `x_oracle`          | The shared `XOracle` object                          |
| `price_info_object` | The Pyth `PriceInfoObject` registered for `CoinType` |
| `clock`             | The Sui `Clock` object (`0x6`)                       |

Prices are considered stale if they exceed the oracle's delay tolerance (default 5 seconds). A stale price will cause subsequent borrow/withdraw calls to abort.

***

## Borrow

**Module:** `protocol::borrow`

Borrows assets from the market against deposited collateral. The obligation must remain sufficiently collateralized after the borrow.

### Functions

#### `borrow<MarketType, CoinType>`

**Target:** `<LENDING_PROTOCOL_PACKAGE_ID>::borrow::borrow`

Borrows the specified amount from the market and returns it as a `Coin`.

```move
public fun borrow<MarketType, CoinType>(
    app: &ProtocolApp,
    obligation_owner_cap: &ObligationOwnerCap,
    market: &mut Market<MarketType>,
    coin_decimals_registry: &CoinDecimalsRegistry,
    borrow_amount: u64,
    x_oracle: &XOracle,
    clock: &Clock,
    ctx: &mut TxContext,
): Coin<CoinType>
```

| Parameter                | Description                                          |
| ------------------------ | ---------------------------------------------------- |
| `obligation_owner_cap`   | Proves ownership of the obligation to borrow against |
| `borrow_amount`          | Amount to borrow in base units                       |
| `coin_decimals_registry` | Registry for coin decimal lookups                    |
| `x_oracle`               | Oracle for price feeds                               |

### Events

| Event         | Fields                                                                                        |
| ------------- | --------------------------------------------------------------------------------------------- |
| `BorrowEvent` | `borrower`, `market`, `obligation`, `asset`, `amount`, `total_borrow`, `borrow_index`, `time` |

***

## Repay

**Module:** `protocol::repay`

Repays outstanding debt on an obligation. Supports repaying on behalf of another obligation.

### Functions

#### `repay<MarketType, CoinType>`

**Target:** `<LENDING_PROTOCOL_PACKAGE_ID>::repay::repay`

Repays debt and transfers any refund (overpayment) back to the sender. Destroys the refund coin if zero.

```move
public fun repay<MarketType, CoinType>(
    app: &ProtocolApp,
    obligation_owner_cap: &ObligationOwnerCap,
    market: &mut Market<MarketType>,
    coin: Coin<CoinType>,
    clock: &Clock,
    ctx: &mut TxContext,
)
```

#### `repay_coin_refund<MarketType, CoinType>`

**Target:** `<LENDING_PROTOCOL_PACKAGE_ID>::repay::repay_coin_refund`

Same as `repay`, but returns the refund `Coin` instead of transferring it.

```move
public fun repay_coin_refund<MarketType, CoinType>(
    app: &ProtocolApp,
    obligation_owner_cap: &ObligationOwnerCap,
    market: &mut Market<MarketType>,
    coin: Coin<CoinType>,
    clock: &Clock,
    ctx: &mut TxContext,
): Coin<CoinType>
```

#### `repay_on_behalf<MarketType, CoinType>`

**Target:** `<LENDING_PROTOCOL_PACKAGE_ID>::repay::repay_on_behalf`

Repays debt for any obligation by ID — does not require ownership. Returns the refund coin.

```move
public fun repay_on_behalf<MarketType, CoinType>(
    app: &ProtocolApp,
    obligation_id: ID,
    market: &mut Market<MarketType>,
    coin: Coin<CoinType>,
    clock: &Clock,
    ctx: &mut TxContext,
): Coin<CoinType>
```

### Events

| Event        | Fields                                                                                                 |
| ------------ | ------------------------------------------------------------------------------------------------------ |
| `RepayEvent` | `repayer`, `market`, `obligation`, `asset`, `amount`, `total_borrow`, `borrow_index`, `refund`, `time` |

***

## Withdraw

**Module:** `protocol::withdraw`

Withdraws deposited collateral by burning cTokens. The obligation must remain sufficiently collateralized after withdrawal.

### Functions

#### `withdraw<MarketType, CoinType>`

**Target:** `<LENDING_PROTOCOL_PACKAGE_ID>::withdraw::withdraw`

Burns the specified amount of cTokens and transfers the redeemed underlying asset to the sender.

```move
public fun withdraw<MarketType, CoinType>(
    app: &ProtocolApp,
    market: &mut Market<MarketType>,
    obligation_owner_cap: &ObligationOwnerCap,
    coin_decimals_registry: &CoinDecimalsRegistry,
    amount: u64,
    x_oracle: &XOracle,
    clock: &Clock,
    ctx: &mut TxContext,
)
```

#### `withdraw_as_coin<MarketType, CoinType>`

**Target:** `<LENDING_PROTOCOL_PACKAGE_ID>::withdraw::withdraw_as_coin`

Same as `withdraw`, but returns the redeemed `Coin` instead of transferring it.

```move
public fun withdraw_as_coin<MarketType, CoinType>(
    app: &ProtocolApp,
    market: &mut Market<MarketType>,
    obligation_owner_cap: &ObligationOwnerCap,
    coin_decimals_registry: &CoinDecimalsRegistry,
    ctoken_to_burn: u64,
    x_oracle: &XOracle,
    clock: &Clock,
    ctx: &mut TxContext,
): Coin<CoinType>
```

| Parameter        | Description                              |
| ---------------- | ---------------------------------------- |
| `ctoken_to_burn` | Number of cTokens to burn for redemption |

### Events

| Event           | Fields                                                                                                                            |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `WithdrawEvent` | `redeemer`, `market`, `obligation`, `withdraw_asset`, `withdraw_amount`, `ctokens_remaining`, `burn_asset`, `burn_amount`, `time` |

***

## Liquidation

**Module:** `protocol::liquidate`

Handles liquidation of undercollateralized obligations. Adopts **soft liquidation** — the liquidation amount should not exceed what is needed to bring the obligation's risk level back to 1.

{% hint style="warning" %}
All liquidation functions require a `PackageCallerCap` with the appropriate permission (`liquidation` or `adl`). Liquidation is currently whitelisted — only approved liquidators can call these functions. If you are interested in becoming a liquidator, feel free to reach out to us.
{% endhint %}

### Liquidation Types

| Type                | Description                                            |
| ------------------- | ------------------------------------------------------ |
| `NormalLiquidation` | Standard liquidation — repay debt and seize collateral |
| `ADLBorrow`         | Auto-deleverage on the borrow side                     |
| `ADLCollateral`     | Auto-deleverage on the collateral side                 |

### Functions

#### `liquidate<MarketType, DebtType, CollateralType>`

**Target:** `<LENDING_PROTOCOL_PACKAGE_ID>::liquidate::liquidate`

Performs a normal liquidation. Seized collateral and any debt refund are transferred to the caller.

```move
public fun liquidate<MarketType, DebtType, CollateralType>(
    app: &ProtocolApp,
    cap: &PackageCallerCap,
    obligation_id: ID,
    market: &mut Market<MarketType>,
    available_repay_coin: Coin<DebtType>,
    coin_decimals_registry: &CoinDecimalsRegistry,
    x_oracle: &XOracle,
    clock: &Clock,
    ctx: &mut TxContext,
)
```

#### `liquidate_as_coin<MarketType, DebtType, CollateralType>`

**Target:** `<LENDING_PROTOCOL_PACKAGE_ID>::liquidate::liquidate_as_coin`

Same as `liquidate`, but returns the seized collateral and refund as `Coin` objects for composability.

```move
public fun liquidate_as_coin<MarketType, DebtType, CollateralType>(
    app: &ProtocolApp,
    cap: &PackageCallerCap,
    obligation_id: ID,
    market: &mut Market<MarketType>,
    available_repay_coin: Coin<DebtType>,
    coin_decimals_registry: &CoinDecimalsRegistry,
    x_oracle: &XOracle,
    clock: &Clock,
    ctx: &mut TxContext,
): (Coin<CollateralType>, Coin<DebtType>)
```

### Events

| Event            | Fields                                                                                                                                                                                                                                                                                      |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `LiquidateEvent` | `liquidator`, `liquidation_type`, `market`, `obligation`, `collateral_price`, `debt_price`, `collateral_type`, `seized_ctoken_amount`, `seized_collateral_amount`, `ctokens_remaining`, `debt_type`, `total_borrow_remaining`, `borrow_index`, `repay_amount`, `refund_amount`, `timestamp` |

***

## Liquidity Mining

**Module:** `protocol::liquidity_mining`

Allows users to claim accrued rewards from the liquidity mining program.

### Functions

#### `claim_reward<MarketType, CoinType, RewardCoinType>`

**Target:** `<LENDING_PROTOCOL_PACKAGE_ID>::liquidity_mining::claim_reward`

Claims the accrued reward and transfers it to the caller.

```move
public fun claim_reward<MarketType, CoinType, RewardCoinType>(
    app: &ProtocolApp,
    market: &mut Market<MarketType>,
    obligation_owner_cap: &ObligationOwnerCap,
    reward_type: u8,
    reward_index: u64,
    clock: &Clock,
    ctx: &mut TxContext,
)
```

#### `claim_reward_as_coin<MarketType, CoinType, RewardCoinType>`

**Target:** `<LENDING_PROTOCOL_PACKAGE_ID>::liquidity_mining::claim_reward_as_coin`

Same as `claim_reward`, but returns the reward as a `Coin` for composability.

```move
public fun claim_reward_as_coin<MarketType, CoinType, RewardCoinType>(
    app: &ProtocolApp,
    market: &mut Market<MarketType>,
    obligation_owner_cap: &ObligationOwnerCap,
    reward_type: u8,
    reward_index: u64,
    clock: &Clock,
    ctx: &mut TxContext,
): Coin<RewardCoinType>
```

| Parameter      | Description                                     |
| -------------- | ----------------------------------------------- |
| `reward_type`  | The reward category (deposit or borrow reward)  |
| `reward_index` | Index of the specific reward pool to claim from |

### Type Parameters

| Type Parameter   | Description                                                                      |
| ---------------- | -------------------------------------------------------------------------------- |
| `MarketType`     | The market the obligation belongs to                                             |
| `CoinType`       | The asset type the reward was accrued on (e.g., the deposited or borrowed asset) |
| `RewardCoinType` | The type of coin distributed as the reward                                       |

### Events

| Event                | Fields                                                                                  |
| -------------------- | --------------------------------------------------------------------------------------- |
| `RewardClaimedEvent` | `who`, `market`, `obligation`, `coin_type`, `reward_coin_type`, `reward_amount`, `time` |