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

# Supply and borrow on Stellar

> Controller supply and borrow entrypoints, current ABI, preconditions, events, and common errors.

Supply and borrow go through the controller. The controller resolves the account,
loads spoke configuration, checks oracle policy, moves tokens, and calls the
central pool. Pool state is keyed by `HubAssetKey`.

**Read first:** [Accounts and risk](/stellar-lending/dev/accounts-and-risk),
[Markets](/stellar-lending/dev/markets), and
[Health factor](/stellar-lending/dev/health-factor).

## Supply

```rust theme={"system"}
supply(
  caller: Address,
  account_id: u64,
  spoke_id: u32,
  assets: Vec<(HubAssetKey, i128)>,
) -> u64
```

Passing `account_id = 0` creates a new account owned by `caller` and bound to
`spoke_id`. Existing accounts keep their stored spoke; the supplied `spoke_id`
must match that account.

### Preconditions

* `caller` authorizes the call and token transfers.
* Each `HubAssetKey` is listed in the pool.
* The account's spoke lists the hub asset.
* The spoke asset is collateralizable and not blocked for increases.
* Supply caps and position limits leave enough headroom.

### Example

```bash theme={"system"}
stellar contract invoke \
  --id <CONTROLLER> \
  --source-account <CALLER> \
  --network testnet \
  -- supply \
  --caller <CALLER> \
  --account_id 0 \
  --spoke_id 1 \
  --assets '[[{"hub_id":1,"asset":"<USDC>"}, "10000000000"]]'
```

### Common Errors

| Error                        | Cause                                       | Fix                                                  |
| ---------------------------- | ------------------------------------------- | ---------------------------------------------------- |
| `#104 NotCollateral`         | Spoke asset cannot be used as collateral.   | Use a collateralizable asset or another spoke.       |
| `#311 SpokeSupplyCapReached` | Spoke supply cap exceeded.                  | Supply less or wait for cap headroom.                |
| `#109 PositionLimitExceeded` | Account already holds max supply positions. | Consolidate positions or wait for a limit change.    |
| `#315 SpokeAssetPaused`      | Spoke asset is paused.                      | Wait for governance to unpause or use another asset. |
| `#316 SpokeAssetFrozen`      | Position increase is frozen.                | Exit-only actions may still be available.            |

## Borrow

```rust theme={"system"}
borrow(
  caller: Address,
  account_id: u64,
  borrows: Vec<(HubAssetKey, i128)>,
  to: Option<Address>,
)
```

Borrow records debt on `account_id`. Tokens go to `to` when set, otherwise to
`caller`.

### Preconditions

* `caller` owns the account or is authorized for it.
* Each borrowed hub asset is listed by the account's spoke and borrowable.
* Borrow caps, liquidity, and utilization caps leave enough headroom.
* Post-borrow LTV and health factor pass.
* Strict oracle policy passes for every priced asset.

### Example

```bash theme={"system"}
stellar contract invoke \
  --id <CONTROLLER> \
  --source-account <CALLER> \
  --network testnet \
  -- borrow \
  --caller <CALLER> \
  --account_id 42 \
  --borrows '[[{"hub_id":1,"asset":"<XLM>"}, "2000000000"]]' \
  --to null
```

### 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.        |
| `#102 HealthFactorTooLow`        | Post-borrow health factor is below one.                    | Reduce borrow or add collateral.      |
| `#112 InsufficientLiquidity`     | Pool `cash` is below requested amount.                     | 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.  |

## Verification

Successful supply or borrow emits controller position and market-state events.
Read back state through controller views such as `get_account_positions`,
`collateral_amount_for_hub_asset`, `borrow_amount_for_hub_asset`, and
`health_factor`.

## Next

<CardGroup cols={2}>
  <Card title="Withdraw and repay" icon="arrow-up-from-line" href="/stellar-lending/dev/withdraw-and-repay">
    Exit collateral and repay debt.
  </Card>

  <Card title="Flash loans" icon="bolt" href="/stellar-lending/dev/flash-loans">
    Borrow and repay inside one callback.
  </Card>
</CardGroup>