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

# Flash positions

> Create account debt through a receiver callback and supply declared collateral receipts.

`flash_position` borrows into a lending account, forwards tokens to a receiver
contract, and supplies the collateral the receiver sends to the controller.
The account keeps the debt, and the strategy charges no flash fee.

Use this entrypoint for a custom leveraged-position callback. Read
[account modes and authority](/docs/stellar-lending/dev/accounts-and-risk) and
[health-factor requirements](/docs/stellar-lending/dev/health-factor) first.

## Prepare the account and receiver

```rust theme={"system"}
flash_position(
    caller: Address,
    account_id: u64,
    spoke_id: u32,
    mode: PositionMode,
    debt: HubAssetKey,
    amount: i128,
    receiver: Address,
    data: Bytes,
    collaterals: Vec<(HubAssetKey, i128)>,
    refund_assets: Vec<Address>,
) -> u64
```

Pass `account_id = 0` to create the account. An existing account requires owner
or active delegate authority, and its stored spoke and mode must match the
arguments. Supported modes are `Multiply`, `Long`, and `Short`.

The debt amount must be positive. Its market must be borrowable on the account's
spoke, belong to an active hub, and have `is_flashloanable = true`, including
when its flash-loan fee is nonzero. This entrypoint still charges zero.
Borrow caps, position limits, pool cash, and utilization limits apply.

The protocol must be unpaused. The receiver must be a deployed Wasm contract
and cannot be the controller or pool. Valid prices are fetched for the account
and strategy assets before funding or the callback.

## Declare collateral minimums

`collaterals` lists the markets whose callback receipts become supply. Each
amount is a minimum controller receipt in that token's native units.

The controller validates the declarations before the callback:

* The list is nonempty and has at most `max_supply_positions` entries.
* Minimums are nonnegative, with at least one positive minimum.
* Neither market keys nor underlying token addresses repeat.
* Each market is listed on the account's spoke, collateralizable, and allowed for supply.
* The declared positions fit the account's position-count limit.

The controller snapshots balances after forwarding the borrowed tokens and
measures increases during the callback. It submits each positive collateral
delta for supply; the pool then credits its measured receipt.

| Callback receipt | Result |
| - | - |
| Above the minimum | The full controller delta is submitted for supply. |
| Below the minimum | Reverts with `#504 CollateralMinimumNotMet`. |
| Zero with a zero minimum | Skips that market. |
| Zero for all declared collateral | Reverts with `#504 CollateralMinimumNotMet`. |

Supply caps and final position counts apply to measured deposits after the
callback. Declaration checks do not reserve cap headroom. A controller receipt
minimum is not a guarantee of equal final collateral when the subsequent token
transfer delivers a different amount.

## Declare refund assets

`refund_assets` lists token addresses whose positive callback balance deltas
are paid to `caller`. Refunds exclude balances already held by the controller
before the callback. The recipient is the caller, including when a delegate
initiates the transaction.

Each refund asset must be listed and active on the account's spoke under
`debt.hub_id`. The list has at most `max_supply_positions` entries, contains no
duplicates, and cannot overlap any declared collateral token. Invalid list
shape raises `#16 InvalidPayments`; listing checks can also reject a token.

<Warning>
  Returned debt tokens do not repay the account. A debt token declared as a refund
  is paid to the caller; one declared as collateral is supplied. Any undeclared
  token remains in the controller, which has no sweep or rescue entrypoint.
  Declare every token the callback can return before submitting the transaction.
</Warning>

## Implement the callback

The receiver exports:

```rust theme={"system"}
execute_flash_position(
    initiator: Address,
    account_id: u64,
    asset: Address,
    amount: i128,
    fee: i128,
    amount_received: i128,
    controller: Address,
    data: Bytes,
)
```

`fee` is zero. `amount` is the debt principal; `amount_received` is the receiver's
measured receipt and can differ from the principal. Size callback spending from
`amount_received`.

Authenticate the configured trusted controller and validate the expected
initiator, account, asset, principal, and request data. Send resulting collateral
and declared refunds to that controller. Callback arguments alone do not prove
that the operation is authorized.

The flash guard covers funding, forwarding, balance snapshots, and the callback.
Guarded financial controller operations reject reentry with
`#400 FlashLoanOngoing`. The receiver cannot repay this account through a
nested controller call.

## Simulate and verify

Build against the controller signature above and simulate the complete call
before signing. The published SDK 1.0.228 has no dedicated flash-position
builder. A custom builder must preserve this argument order and validate the
prepared invocation and authorization entries against your own request.

Follow [Wallet integration](/docs/stellar-lending/dev/wallet-integration) to persist
the original network, signed XDR, and hash before submission. Resolve an unknown
outcome by that hash on the same network; do not repeat or replace the callback
automatically.

The final account must retain debt in `debt` and at least one supply position.
Otherwise, the call raises
`#505 FlashPositionClosed`. Finalization refreshes listed collateral LTV, then
checks LTV coverage, health factor, and the configured USD collateral floor.
Each collateral position with fewer than three decimals must retain at least
two base units after floor conversion. Failure reverts the whole transaction.

Persist the returned account id and confirm native balances through
`get_collateral_amount` and `get_borrow_amount`. The position batch tags the debt
increase as `FlashPos` (16) and supplied collateral as `Supply` (0).
`FlashPositionEvent` reports principal, measured receiver receipt, and `fee = 0`.

There is no dedicated refund preview or refund field in the return value or
`FlashPositionEvent`. Confirm refunds from token transfer events and caller
balances. Transaction simulation can estimate execution against its ledger
state, but state can change before submission.

For standard route-based leverage, use [Strategies](/docs/stellar-lending/dev/strategies).
For borrowing repaid within a callback, use [Flash loans](/docs/stellar-lending/dev/flash-loans).


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