> 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/ai-agents/transactions.md).

# Prepare a transaction

Prepare an action, follow its status, and let the wallet's owner confirm each step on gage.cash/review.

A prepare reads the wallet's state from the chain and gage's own services, plans what is left to send, builds the next transaction and simulates it against the chain now. It answers with that one unsigned transaction and the steps after it. gage never signs or sends it.

`wallet` names who acts. It is not authentication or permission to spend: anyone can prepare for any wallet, and only that wallet's owner can sign.

## The answer

| Field     | Meaning                                                                                                                                                                                                 |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`  | `approval_required`, `ready` or `done`.                                                                                                                                                                 |
| `next`    | The next unsigned transaction: `label`, `kind` (`approve` or `action`), `final` and `transaction` (`from`, `to`, `data`, `value`, `chainId`, `gas`). `null` when nothing is left.                       |
| `then`    | The labels of the steps after `next`, in order.                                                                                                                                                         |
| `summary` | `title` and `rows` (`label`, `value`): what the action does, in gage's own words and figures.                                                                                                           |
| `notes`   | What else the owner should know, such as how long a listing stays open.                                                                                                                                 |
| `again`   | `true` when `next` must be mined before the action itself can be planned: a partner vault's settle before a deposit or withdrawal. Send it, wait for its receipt, then prepare again. Absent otherwise. |
| `view`    | The figures the review page draws.                                                                                                                                                                      |
| `review`  | From the hosted service: `url` (`https://gage.cash/review#<token>`) and `expiresAt`. `null` when `next` is.                                                                                             |

Only `next` is built and simulated; each step in `then` is built when its turn comes. `gas` is the simulation's estimate, to which a wallet may add headroom. A partner vault's settle, deposit or withdrawal also carries 250,000 for each loan it books or open reward record it claims for, and two more: an estimate taken while the records have nothing to claim does not see what claiming costs. `value` is `"0"` for every action the hosted service prepares, and every step needs ETH for gas. Through gage-sdk and `gage-mcp`, an `unpark` into a native ETH pool also sends ETH: send the `value` a step names.

## Follow status

| `status`            | Meaning                                                                                                         | Then                                                                                                         |
| ------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `approval_required` | `next` approves the exact amount the following step spends.                                                     | Send it, wait for its receipt, then prepare again.                                                           |
| `ready`             | `next` is a step of the action itself.                                                                          | Send it. If `next.final` is `true`, send it once and stop. Otherwise wait for its receipt and prepare again. |
| `done`              | Nothing is left to send.                                                                                        | Stop.                                                                                                        |
| `partial`           | Nothing to send from what could be read, but part of it did not answer, so more may be ready: `notes` say what. | Prepare again shortly.                                                                                       |

The final step is the action's one-time step: a listing, a loop, a roll, a cash-out, turning on a roll by itself, a deposit, a redemption or a rating. Never prepare again after sending it: a second send lists, loops, rolls, deposits or redeems a second time. Cancelling, repaying and collecting have no final step: prepare again after each one until `done`. A borrow, for example:

```
prepare borrow  ->  approval_required, next "Approve NVDA", then ["Borrow"]
                    send it, wait for its receipt
prepare borrow  ->  ready, next "Borrow", final: true
                    send it once, and stop
```

A simulation reserves nothing and does not guarantee inclusion. Follow each hash to its receipt, and prepare again after any change rather than reuse an older answer.

## Review links

From the hosted service, every answer with a `next` carries a review link. The agent gives it to the wallet's owner, and the page:

1. asks for the wallet the action was prepared for, and plans the action again from the chain;
2. shows gage's own words and figures, never text the agent sent, and lists a borrow only on terms at least one partner vault accepts;
3. walks every remaining step, one confirmation in the owner's wallet each, the service preparing each step again just before it goes out;
4. moves on only when the chain shows that wallet's transaction succeeded exactly as prepared. Once the one-time step is confirmed, or nothing is left to send, the link shows the action done.

A link lives 30 minutes; after that it answers `REVIEW_EXPIRED`, and the agent prepares again. gage stores only the token's SHA-256, and the token travels in the URL fragment, which browsers do not send to servers.

Use one path for each action: the review link, or the owner's own wallet. Never both: a final step sent from each would act twice.

## Exact approvals

An approval is for the exact amount the next step spends, never unlimited, and is asked for only when the allowance falls short:

| Action         | Approves                                                                                                                                                                                         |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `borrow`       | The collateral pledged.                                                                                                                                                                          |
| `leverage`     | The tokens put in, then USDG up to the most the purchase may cost (`maxPurchaseCostUSDG`).                                                                                                       |
| `reclaim`      | The full repayment.                                                                                                                                                                              |
| `cash_out`     | The loan's reclaim right, to the cash-out router, for this loan only.                                                                                                                            |
| `roll`         | The loan's reclaim right, to the rollover router, for this loan only, then the old loan's full repayment, with what the wallet's other loans rolling over by themselves on that core still need. |
| `earn_deposit` | The amount deposited.                                                                                                                                                                            |

`auto_roll` and `put_auto_roll` are the two exceptions, and each plan says so. `auto_roll`'s approvals stand: gage's rollover router may move every loan of the wallet on that core, so the instruction follows each new loan, and may spend the repayments of up to four rolls, and of the rolls the wallet's other loans rolling over by themselves there still need, until the owner withdraws those approvals in their wallet. An approval replaces the one before it, so `roll` and `auto_roll` size theirs for all those loans: sized for one, it would leave the others' rolls short. Ending the instruction leaves them in place. `put_auto_roll` leaves the same kind with gage's put router: it may move the wallet's loans on that core, take back the payouts of up to four rolls and spend USDG from the wallet on their top-ups, with what the wallet's other puts rolling over by themselves there still need; `put_roll` sizes its approvals for those too.

Exact approvals limit each token allowance; they do not enforce a budget across actions. Keep pending spending in your own accounting.

## The actions

| Action             | Steps                                                                                                             | What to know                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------ | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `borrow`           | Approve, then **Borrow** (final)                                                                                  | The listing stays open to the partner vaults for 24 hours. Once it is funded, the USDG waits as the wallet's credit until `collect` brings it to the wallet. Unfunded after 24 hours, `collect` takes the collateral back.                                                                                                                                                                                                                                                                             |
| `leverage`         | Approve the tokens, approve USDG, then **Open loop** (final)                                                      | One transaction buys more of the pledged token and opens the loan, funded by the partner vaults. Refused above `maxCostBps`. The loop's price is signed for 30 seconds when its transaction is prepared: send it at once, or prepare again. USDG only.                                                                                                                                                                                                                                                 |
| `cancel`           | **Cancel listing**, then **Receive collateral**                                                                   | Only while the loan waits for funding. Any lenders' contributions go back to them. While the token is paused, **Cancel listing** is the last step (final): the collateral waits until it resumes.                                                                                                                                                                                                                                                                                                      |
| `reclaim`          | Approve, **Repay**, then **Receive collateral**                                                                   | Repays the loan in full, before its term ends, from the wallet that holds its reclaim right. While the token is paused, **Repay** is the last step (final): the collateral waits until it resumes, and asking for it then answers `TOKEN_PAUSED`. Never send **Repay** and **Receive collateral** in one all-or-nothing batch: a paused token would fail the repayment with it.                                                                                                                        |
| `cash_out`         | Approve the reclaim right, then **Cash out** (final)                                                              | Sells the loan's whole collateral through an aggregator, repays the loan from the sale and pays the wallet the rest, less gage's 0.5% fee, in one transaction. The sale is quoted again when it is sent and refused if it would pay less than planned (`PRICE_MOVED`).                                                                                                                                                                                                                                 |
| `roll`             | Approve the reclaim right, approve the repayment, then **Roll over** (final)                                      | A new loan of the same size on the same pledge repays this one in full, in one transaction: the wallet adds the old loan's fixed cost and the new loan's fee. `term` may name another allowed term. Its price is signed for 30 seconds when it is prepared: send it at once. Rolled before its last day, the loan is repaid early and the new term starts then.                                                                                                                                        |
| `auto_roll`        | **Let the rollover router follow your loans**, approve the repayments, then **Turn on rolling by itself** (final) | Set on a listing or a running loan. gage's keeper rolls the loan in its last six hours into a loan of the same size and term, at most `maxCost` each (its fixed cost and fee together, never more than the loan's principal; when omitted, twice today's roll quote, held to four times the loan's own cost, or on a listing not yet funded twice the loan's own cost), up to four times. Best effort: a roll the keeper cannot make leaves the loan to end as any other. Its approvals stand (above). |
| `cancel_auto_roll` | **Turn off rolling by itself**                                                                                    | One transaction. Once it is mined the loan has no instruction left, and preparing it again is refused (`NO_AUTO_ROLL`).                                                                                                                                                                                                                                                                                                                                                                                |
| `earn_deposit`     | Approve, then **Deposit** (final)                                                                                 | Receives at least the vault's quoted shares less `maxSlippageBps` (50 when omitted). You may end up holding the collateral instead of USDG.                                                                                                                                                                                                                                                                                                                                                            |
| `earn_redeem`      | **Withdraw** (final)                                                                                              | Paid up to the vault's free cash now, at least the quoted amount less `maxSlippageBps`. Without `shares`, everything the vault can pay now.                                                                                                                                                                                                                                                                                                                                                            |
| `collect`          | One transaction per line                                                                                          | USDG from loans, collateral back (expired listings included), vault earnings and sGAGE rewards. Only from partner vaults the chain bears out as gage's, at most twenty claims at a time, none for sGAGE under a millionth. Each claim is simulated first; one that would revert now is left out, with a note to collect again later. Claims on gage's earlier surfaces are collected on gage.cash.                                                                                                     |
| `feedback`         | **Rate gage** (final)                                                                                             | The wallet's own score for gage, 0 to 100, in ERC-8004's Reputation Registry: once a wallet, optional, and nothing offered for it. The answer to an action's last step says when a rating is open.                                                                                                                                                                                                                                                                                                     |

A partner vault with a loan past its end that nobody has booked yet takes no deposit or withdrawal. Its `earn_deposit` or `earn_redeem` then starts with **Settle the vault's loans**, which anyone may send, and the answer carries `again: true`: send it, wait for its receipt, and prepare the deposit or withdrawal again. Booking a loan past its end unpaid writes it off, which lowers the share price.

gage-mcp and gage-sdk also prepare, on mainnet, puts (`put_open`, `put_close`, `put_roll`, `put_auto_roll`, `put_cancel_auto_roll`; see [Puts with gage-sdk](https://docs.gage.cash/developers/sdk-puts.md)), the LP lane's fourteen actions ([LP loans with gage-sdk](https://docs.gage.cash/developers/sdk-lp-lane.md)), `park` and `unpark` ([Park out-of-range positions](https://docs.gage.cash/developers/park.md)) and exit now (`earn_exit_now`, `earn_exit_list`, `earn_exit_cancel`, `earn_exit_collect` and `rehypo_exit_now`; see [Earn with gage-sdk](https://docs.gage.cash/developers/sdk-earn.md#exit-now)). Those pages give their steps.

The hosted service prepares `borrow`, `leverage`, `cancel`, `reclaim`, `earn_deposit`, `earn_redeem`, `collect` and `feedback`, and answers every other action `ACTION_NOT_SERVED`: the wallet's owner does those on gage.cash, and rolls or cashes out from Portfolio or the loan's page (see [Extend](https://docs.gage.cash/borrow/the-decision.md#extend)).

## Repayment and the end of the term

Loans have a fixed cost and a fixed term, with 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. There is no grace period: the repayment must be mined before the term's last second, and `reclaim` is refused from then on (`TERM_ENDED`). Repay early rather than at the deadline.

Anything owed to a wallet is credited to it on gage's contracts and withdrawn by that wallet, never pushed to it: `collect` gathers everything ready.


---

# 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/ai-agents/transactions.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.
