Borrow

Borrow records debt on an existing lending account and pays tokens to the selected recipient. The caller must own the account’s position NFT or hold an active delegate grant. Start with Supply and the health-factor and LTV gates.

Check borrowing headroom

Each borrow entry is (HubAssetKey, amount) in token base units. Amounts must be positive; duplicate market entries are summed. Before submitting, check that:

Each market exists on an active hub and is listed as borrowable on the account’s spoke.
The protocol and each listing are unpaused; listings are unfrozen.
Borrow caps, position limits, pool cash, and utilization limits permit the request.
The resulting account passes LTV coverage, health factor, and the minimum-borrow-collateral floor.
If debt remains, each collateral position below 3 decimals holds at least two token base units.
Every asset needed for account valuation has a valid price.

Borrowing also preserves a liquidation cash buffer of 200 BPS (2%) of the market’s floor-valued total supply. Cash available for borrowing can therefore be less than total pool cash. Markets below 3 token decimals cannot be borrowed. One unusable price reverts valuation. Simulate the complete borrow against current ledger state; headroom and prices can change before execution.

Build and authorize the call

borrow(
    caller: Address,
    account_id: u64,
    borrows: Vec<(HubAssetKey, i128)>,
    to: Option<Address>,
)

Tokens go to to when supplied, otherwise to caller. The recipient cannot be the controller or pool. Changing to does not change whose authority is checked.

stellar contract invoke \
  --id "$CONTROLLER" \
  --source-account "$IDENTITY" \
  --network testnet \
  -- borrow \
  --caller "$CALLER_ADDRESS" \
  --account_id 42 \
  --borrows '[[{"hub_id":1,"asset":"<XLM>"}, "2000000000"]]' \
  --to null

Set the shell variables as in the quickstart. Replace the token and account inputs. This example borrows 200 XLM. The caller authorizes the controller call; the pool authorizes its token payout. Prepare the transaction before signing it.

Verify the borrow

Read get_borrow_amount(account_id, hub_asset) in token base units and get_health_factor(account_id) in WAD (1e18). Confirm the recipient’s token balance as well as the account’s resulting debt. The controller emits UpdatePositionBatchEvent at ["position", "batch_update"], with Borrow legs. The pool emits PoolMarketStateBatchEvent at ["market", "batch_state_update"].

Common errors

Error	Cause	Fix
`#107 AssetNotBorrowable`	Spoke asset is not borrowable.	Borrow an allowed asset.
`#312 SpokeBorrowCapReached`	Spoke borrow cap exceeded.	Borrow less or wait for cap headroom.
`#100 InsufficientCollateral`	LTV gate fails.	Add collateral or borrow less.
`#47 BorrowRoundsToZeroShares`	The amount is too small to mint one scaled debt share.	Borrow more.
`#112 InsufficientLiquidity`	Payout exceeds cash or leaves less than the 2% liquidation cash buffer.	Borrow less or wait for liquidity.
`#126 MinBorrowCollateralNotMet`	Debt remains but collateral is below the configured floor.	Add collateral or reduce debt.
`#127 UtilizationAboveMax`	Post-borrow utilization is too high.	Borrow less or wait for more supply.

Use Repay to reduce debt, or Strategies to change debt and collateral in one transaction.

Start here

Core concepts

Lending actions

Strategies and integrations

System behavior

Reference

Operations

Check borrowing headroom

Build and authorize the call

Verify the borrow

Common errors

​Check borrowing headroom

​Build and authorize the call

​Verify the borrow

​Common errors

Check borrowing headroom

Build and authorize the call

Verify the borrow

Common errors