> ## Documentation Index
> Fetch the complete documentation index at: https://xoxno.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Borrow

> Borrow against an existing account and verify debt, recipient balances, and health.

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](/docs/stellar-lending/dev/supply) and the
[health-factor and LTV gates](/docs/stellar-lending/dev/health-factor).

## 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

```rust theme={"system"}
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.

```bash theme={"system"}
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](/docs/stellar-lending/dev/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](/docs/stellar-lending/dev/repay) to reduce debt, or
[Strategies](/docs/stellar-lending/dev/strategies) to change debt and collateral in
one transaction.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.