> For the complete documentation index, see [llms.txt](https://docs.gage.cash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gage.cash/developers/sdk-borrow.md).

# Borrow with gage-sdk

Borrow with gage-sdk: the lowest fixed cost the partner vaults accept in one click, exact terms and Loan grades, rolling over, cashing out and leverage.

A loan pledges a token and pays out USDG, or a stock token gage lends, with a fixed amount to repay within a fixed term. There is no liquidation: a loan is never closed early because a price moves; if it is not repaid by the end of its term, the lenders keep the collateral and nothing else is taken. Only partner vaults lend: a borrow lists the loan, gage's keeper funds it from the vaults on its next pass, and the payout waits for the wallet to collect it. A listing is not a loan until the vaults fund it.

## The lowest fixed cost, in one click

```ts
const [asset, term] = await Promise.all([collateralOf(gage, symbol), termOf(gage, days)]);
const quote = await gage.borrowQuote({ token: asset.token, maxCollateral: parseUnits(amount, asset.decimals).toString(), term, wallet: signer.address });
const { action: _, ...terms } = quote.prepare;
// Lists the loan: an exact approval of the pledge first, each step simulated before it is sent.
const listed = await gage.run({ action: "borrow", ...terms }, signer);
```

The quote is the largest loan the partner vaults fund whole now for at most `maxCollateral`, pledging only what it needs, at the lowest fixed cost the vaults funding it accept:

* Each partner vault takes loans down to its own Loan grade's share of the rates model's cost of the loan: A 100%, B 90%, C 75%, D 50%. The quote keeps the loan's size and lowers its cost as far as the vaults funding it still take all of it, checked with gage's funding preview, and never under grade D.
* A listing waits for the keeper's next pass, and a vault's floor rises as the pledge's worth falls, so the cost also holds for a pledge worth less by 2% for a meme and 0.5% for a stock or ETH.
* The quote names the model's cost of the loan (`modelCostBps`), the loan's `grade`, and the loan in words: what you pledge, receive and repay, and when. Its cost is a fixed amount for the term, with its share of the loan in `costBps` (50 is 0.50% for the term).

On mainnet gage-sdk offers the 7- and 21-day terms that `capabilities().terms` lists ([1-day NVDA loans](https://docs.gage.cash/borrow/one-day.md) are on gage.cash only); a term it does not offer is refused (`TERM_NOT_ALLOWED`). A pledge under the token's minimum is refused with that minimum (`COLLATERAL_BELOW_MINIMUM`, the least raw pledge in `details.minimum.raw`).

## Exact terms, for an advanced mode

An app that lets its users choose the loan-to-value and the cost uses the exact quote: `collateral` and `principal`, and `costBps` for a cost of the borrower's own, to a tenth of a basis point.

```ts
const quote = await gage.borrowQuote(input);
if (!("fundsNow" in quote)) throw new Error("An exact quote names collateral and principal");
```

It answers whether the vaults fund the loan now (`fundsNow`) or it would wait for their cash (`waitsFor`), what each Loan grade A to D costs for it and how many vaults would take it at that cost now (`grades`), the lowest cost their settings take (`lowestAcceptedCostBps`) and the largest loan they take at this cost (`largestAccepted`). A borrow no vault's settings take at its exact terms is refused before anything is sent (`TERMS_NOT_ACCEPTED`, with the cost and loan they would take in `details`). The one-click quote needs none of these controls.

`lendAsset`, a stock token's address that `capabilities().lendAssets` lists, borrows that asset instead of USDG: the loan is paid out and repaid in it, so in dollars what you repay moves with its price.

## Wait for funding, then collect

```ts
// gage's keeper funds a listing from the partner vaults on its next pass; the payout waits on the core until collected.
const funded = await gage.waitForFill({ loanId: listed.loan.loanId, engine: listed.loan.engine });
const collected = funded.status === "funded" ? await gage.run({ action: "collect" }, signer) : null;
```

`waitForFill` looks every 10 seconds for 5 minutes by default and answers `funded`, `waiting` (still open to the vaults until its funding deadline), `expired`, `cancelled` or `closed`. An expired listing's collateral comes back with `collect`; `cancel` takes back a listing still waiting.

## Repay, roll over, roll over by itself, cash out

Ask the loan what it can do first: `loan().actions` lists each action open now and who may take it.

```ts
const loan = await gage.loan(at);
if (!offers(loan.actions, step.action)) throw new Error(`Loan ${loanId} offers no ${step.action} here now: ${loan.actions.join("; ") || "nothing"}`);
// The loan's own core, so a loan in a lend asset is acted on where it lives.
const result = await gage.run({ ...step, loanId, engine: loan.engine }, signer);
```

* **`reclaim`** repays a running loan in full before its term ends and takes the collateral back. It goes on while gage's index gives no answer, once the chain proves the loan public; the other moves wait for the index.
* **`roll`** rolls a running loan into a new loan of the same size on the same pledge, in one transaction: you add the old loan's fixed cost and the new fee, or keep what is over. Its price is signed for 30 seconds; a roll that costs more when it is sent is refused (`PRICE_MOVED`).
* **`auto_roll`** leaves a loan to roll over by itself: gage's keeper rolls it in its last hours into a loan of the same size and term, at most `maxCost` each, up to four times. It leaves standing approvals, as `put_auto_roll` does for a put: gage's rollover router may move the wallet's loans on that core and spend the repayments of up to four rolls, and of the rolls its other loans rolling over by themselves there still need, until you withdraw them in your wallet. **`cancel_auto_roll`** ends it.
* **`cash_out`** sells a running loan's whole collateral through an aggregator, repays the loan from the sale and pays you the rest less gage's 0.5% fee, in one transaction. It is refused if the sale pays less than planned (`PRICE_MOVED`), under the `minNet` you name (`BELOW_MIN_NET`), or more than 1% under gage's own route for the collateral (`SALE_BELOW_ROUTE`).

A generation gage has retired rolls nothing: there `roll` and `auto_roll` are refused (`ROLLOVER_CLOSED`) and the loan's `note` says to repay it before it ends.

## Leverage

A loop pledges your tokens with more of the same token, bought with the loan in the same transaction (USDG loans only):

```ts
const quote = await gage.leverageQuote({ token, own, multiple, term, wallet: signer.address });
const { action: _, ...terms } = quote.prepare;
const looped = await gage.run({ action: "leverage", ...terms }, signer);
```

`multiple` is 1.1 to 3. The wallet approves the most the purchase may cost (`maxPurchaseCostUSDG`), and a loop is refused above its quoted cost (`PRICE_ABOVE_LIMIT`) or at a multiple the loan cannot buy with room to spare (`MULTIPLE_TOO_HIGH`). See [Leverage](https://docs.gage.cash/borrow/leverage.md).


---

# 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.gage.cash/developers/sdk-borrow.md?ask=<question>&goal=<user_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.
