> For the complete documentation index, see [llms.txt](https://docs.bsc.lista.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bsc.lista.org/for-developer/lista-lending/broker-reference.md). # Broker Reference A **broker** is registered per market and, where present, gates origination: only the broker may call `borrow` or `repay` on that market. So on a broker market the broker *is* the borrowing surface — a direct Moolah call reverts. Brokers are what add **fixed-term, fixed-rate** borrowing on top of Moolah's variable-rate markets. The deployed broker markets, with their LLTV, cap and market id, are on [BSC Lending Brokers](/for-developer/lista-lending/smart-contract/smart-contract-bsc-brokers.md). Check whether a market is broker-gated: ```solidity function brokers(Id id) external view returns (address); ``` > Lista Credit uses a different broker, `CreditBroker`, with credit-scoring gates on top. It has its own page: [Loan Lifecycle](/for-developer/credit-loans/loan-lifecycle.md). *** ## Terms A broker offers a set of fixed terms. Read them before borrowing — `termId` is what you pass to open a fixed position: ```solidity struct FixedTermAndRate { uint256 termId; uint256 duration; // seconds uint256 apr; } // IBroker.sol. CreditBroker declares a DIFFERENT struct of the same name with a // fourth field, `FixedTermType termType` — decoding one with the other's ABI // misreads the tuple. See Credit Loan Lifecycle. function getFixedTerms() external view returns (FixedTermAndRate[] memory); ``` `apr` is RAY-scaled as **`1e27 + rate`**, not as the rate itself. Divide by `1e27` and subtract 1 to get the annual figure: `1036821445287206735200000000` is **3.68%**, not 103.68%. A term whose `apr` is at or below `1e27` accrues nothing. On a `LendingBroker` term, interest accrues **linearly per second** on outstanding principal and stops at the position's `end` — it is not charged upfront. (`CreditBroker` terms carry a `termType` and one of its two modes *is* upfront — see [Credit Loan Lifecycle](/for-developer/credit-loans/loan-lifecycle.md).) Repaying before `end` adds an early-repay penalty, roughly half the remaining term's interest on the principal being repaid, which is what recovers the forgone term interest. ## Posting collateral first The broker gates **origination only**. Collateral goes into the underlying Moolah market directly: ```solidity MOOLAH.supplyCollateral(marketParams, assets, onBehalf, ""); // approve Moolah for the collateral token ``` The broker table gives you a market **id**, not `MarketParams` — read the struct with `MOOLAH.idToMarketParams(id)` first. If that market's collateral token is provider-gated (`MOOLAH.providers(id, collateralToken)` is non-zero), route the collateral through that provider instead; see [Providers](/for-developer/lista-lending/providers.md). ## Borrowing ```solidity function borrow(uint256 amount) external; // variable-rate ("dynamic") position function borrow(uint256 amount, uint256 termId) external; // fixed-term position ``` Both of these borrow against **`msg.sender`'s** position and send the loan token to the caller — **unwrapped to native BNB** where the broker supports it. A third overload borrows on someone else's behalf: ```solidity function borrow(uint256 amount, uint256 termId, address user, address receiver) external; ``` It opens the position on `user` and pays `receiver`, and requires `MOOLAH.isAuthorized(user, msg.sender)` — this is the path `PositionManager` uses. Unlike the two above, **this overload always pays in ERC-20, never native**, and it reverts `ZeroAddress()` on a zero `receiver`. All three are `nonReentrant`, require the market id to be set, and revert `ZeroAmount()` on a zero amount. They are additionally pausable in two independent ways — a global pause and a borrow-specific pause — so a broker can stop new borrowing while leaving repayment open. ## Repaying ```solidity function repay(uint256 amount, address onBehalf) external payable; // variable position function repay(uint256 amount, uint256 posId, address onBehalf) external payable; // one fixed position function repayAll(address onBehalf) external payable; // everything ``` **Approve the broker**, not Moolah: on an ERC-20 market the broker pulls the loan token from the caller with `transferFrom`. All three are `payable`, so a native-BNB market can instead be repaid by sending value — the broker wraps it for you and refunds the excess. `repayAll` pulls principal, accrued interest **and the full early-repay penalty on every open fixed position**. `getUserTotalDebt(onBehalf)` does **not** include that penalty, so an allowance sized at it reverts for any borrower holding an un-matured fixed position — the normal case. Sum `previewRepayFixedLoanPosition` across the open positions, or allow a buffer above `getUserTotalDebt`. The fixed-position form needs the `posId` from the user's positions (below). Preview what a partial repayment settles before sending it: ```solidity function previewRepayFixedLoanPosition(address user, uint256 amount, uint256 posId) external view returns (uint256 interestRepaid, uint256 penalty, uint256 principalRepaid); ``` Note the three-way split: interest comes first, a penalty may apply, and only the remainder reduces principal. ### Converting a variable position within one broker ```solidity function convertDynamicToFixed(uint256 amount, uint256 termId) external; ``` Moves part of your variable ("dynamic") position at this broker onto one of its fixed terms. It acts on `msg.sender` only — no authorization, no flash loan. To cross from a plain Moolah market into a broker-gated one, use [`PositionManager`](/for-developer/lista-lending/position-conversion.md) instead. ## Reading positions ```solidity function userFixedPositions(address user) external view returns (FixedLoanPosition[] memory); function userDynamicPosition(address user) external view returns (DynamicLoanPosition memory); function getUserTotalDebt(address user) external view returns (uint256 totalDebt); ``` `getUserTotalDebt` is the **borrower's** total across their fixed and variable positions, priced with the broker's current rate — not a market-wide figure. ## Pricing, and why it matters for liquidation ```solidity function peek(address token, address user) external view returns (uint256 price); ``` On a broker market, health is not computed the way it is elsewhere. `Moolah._isHealthy` prices the collateral at the **plain market price** but substitutes the **broker's** debt figure for the borrower's Moolah shares. The per-user `peek` price shapes the seize math once a liquidation runs. This is the reason [Liquidator Integration](/for-developer/lista-lending/liquidator-integration.md) warns that `PublicLiquidator.loanTokenAmountNeed` over-quotes on broker markets: that helper prices with `Moolah.getPrice(marketParams)`, which is the market price with `user = address(0)`, while the liquidation itself prices with the borrower. Use the broker's own `peek(token, user)` and `getUserTotalDebt(user)` to size a broker-market liquidation. *** ## See also * [Integration Patterns](/for-developer/lista-lending/integration-patterns.md) — how providers and brokers compose. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.bsc.lista.org/for-developer/lista-lending/broker-reference.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.