> 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/park.md).

# Park out-of-range positions

Let your liquidity providers park an out-of-range position in a partner vault, and unpark it into a new range, from their own wallet, with gage-sdk.

A concentrated-liquidity position that is out of range holds one token and earns no fees. **Park** pulls it out on your DEX and deposits that token into a gage partner vault, which lends it at a fixed cost with no liquidation: a loan is never closed early because a price moves, and if a borrower does not repay by the end of its term the vault keeps the collateral. **Unpark** withdraws from the vault and opens a new position in a range your LP picks.

Both run from the LP's own wallet as one ordered list of calls: your position manager's own calls, then the vault's. No gage contract stands between them, nothing is approved to gage, and gage never holds the position or a key. Where the wallet signs a batch (EIP-5792 `wallet_sendCalls`), the whole park is one signature.

This page is for DEX frontends. gage.cash offers the same on its Portfolio wherever it lists a pool.

## Install

`gage-sdk` 0.7.0 or later, with viem 2 as a peer dependency.

```sh
npm install gage-sdk viem
```

## Name your pools

The SDK reads your positions straight from your DEX, never through gage. Name each pool your LPs can park from:

```ts
import { createGage } from "gage-sdk";

const gage = createGage({
  parkPools: [
    // A Uniswap v4 pool by its key, hooked or not, priced by its PoolManager's StateView.
    {
      kind: "uniswap-v4", name: "ETH/USDG", manager: POSITION_MANAGER, stateView: STATE_VIEW,
      key: { currency0: ETH, currency1: USDG, fee: 3000, tickSpacing: 60, hooks: YOUR_HOOK },
    },
    // A Uniswap v3 pool, or a fork that keeps its position manager, by its address.
    { kind: "uniswap-v3", name: "NVDA/USDG 0.05%", manager: NFPM, pool: NVDA_USDG, token0: USDG, token1: NVDA, fee: 500, tickSpacing: 10 },
  ],
});
```

| `kind`       | `manager`                                                          | The pool by                                                       |
| ------------ | ------------------------------------------------------------------ | ----------------------------------------------------------------- |
| `uniswap-v3` | the NonfungiblePositionManager (Uniswap v3, SushiSwap v3, Ouro v3) | its address, tokens in their own order, fee tier and tick spacing |
| `uniswap-v4` | the PositionManager                                                | its key, hooks included, and the `stateView` that prices it       |
| `fables`     | the Fables hook that holds its receipts                            | its key, and the `stateView` that prices it                       |

Each pool is checked when the Gage is made: tokens out of order, or a Fables key that does not name its hook, refuse it.

## List a wallet's out-of-range positions

```ts
const { positions, inRange } = await gage.parkPositions(address, [{ manager: POSITION_MANAGER, id: "1234" }]);
```

A v3-style position manager lists a wallet's positions itself. A v4 PositionManager and a Fables hook cannot: pass the position ids (or Fables range ids) your frontend already knows as the second argument, and each is checked on chain to be the wallet's. Each position answers its pool, its range, the price now, `holds` (the one token it holds, and how much, raw) and `vaults`, the partner vaults that take that token, or a `refusal`: `ETH_NOT_SUPPORTED` (no gage vault takes ETH yet) or `NO_VAULT`. `inRange` counts the positions earning fees, which are not listed.

## Park with wagmi

```ts
import { useAccount, useSendCalls } from "wagmi";

const { address } = useAccount();
const { sendCalls } = useSendCalls();

async function park(id: string) {
  const batch = await gage.parkCalls({ wallet: address, manager: POSITION_MANAGER, id, vault: YOUR_VAULT });
  sendCalls({ calls: batch.calls.map(({ to, data, value }) => ({ to, data, value })) });
}
```

With viem alone, `walletClient.sendCalls({ account, calls })` takes the same calls. A wallet that does not sign batches sends them one by one, in order, each once the one before is mined. Do not ask for the calls again between them: once the liquidity is out, the position is empty. From `gage-sdk` 0.8.0 each call also carries `extraGas`: make its gas limit its own estimate plus that, as a vault's deposit or withdrawal claims for each of the vault's open reward records, which an estimate can miss. A batch's gas is the wallet's to price.

`parkCalls` simulates the whole batch from the wallet before it answers (`SIMULATION_FAILED` names the call that would revert). The calls are, in order:

1. The pull, on your position manager: `decreaseLiquidity` of all of it then `collect` (v3-style), one `modifyLiquidities` with DECREASE\_LIQUIDITY then TAKE\_PAIR (v4, native ETH paid as ETH), or the hook's `withdraw` (Fables).
2. The token approved to the vault, for exactly the amount, where it is not approved already.
3. The deposit into the vault, the shares to the wallet.

Out of range, what the position holds is fixed, and it is the pull's own minimum: if the price comes back into range before the batch lands, the pull reverts and nothing moves. Only the liquidity's amount is deposited; the position's fees come to the wallet (a Fables position's stay claimable on Fables). On a hooked pool whose hook takes part of what leaves, the pull reverts at its minimum.

## Choose your own vault

The vault is yours to choose, usually your DEX's own partner vault. Open one on gage.cash: you set its mandate, its performance fee and the share of deposits it keeps out of loans (its buffer), and you curate it. It must take the token the position holds: USDG in a USDG vault, a stock token in a vault that lends that stock (GLD, NVDA). A vault of another asset is refused (`VAULT_ASSET_MISMATCH`), and ETH is not parked yet. `gage.earnVaults()` lists the partner vaults with each one's asset, fee and free cash.

## Unpark

```ts
const batch = await gage.unparkCalls({
  wallet: address, vault: YOUR_VAULT, manager: POSITION_MANAGER, pool: POOL_ID, tickLower: -199_020, tickUpper: -198_060,
});
sendCalls({ calls: batch.calls.map(({ to, data, value }) => ({ to, data, value })) });
```

`pool` is a v3-style pool's address or a v4 pool's id; the ticks are multiples of its tick spacing. The batch withdraws `amount` (all the vault can pay the wallet now when omitted), approves exactly what the mint takes (through Permit2 for a v4 PositionManager), and mints the position to the wallet:

* **A range on the asset's side of the price** (below it for a pool's second token, above it for its first) takes the withdrawal alone.
* **A range around the price** takes the pool's other token too, from the wallet: at most what the price asks now and `maxSlippageBps` more (50 by default). A v4 pool's native ETH is sent with the mint, and what is left is swept back.
* **A range that holds only the other token** at the price now is refused (`RANGE_WITHOUT_ASSET`).

## What unpark waits on

A partner vault lends what it holds, so it pays out of its free cash: cash it holds, and what it can take back from its reserve now.

* **Free cash.** A withdrawal is paid at once up to the vault's free cash, with no queue. What is out in loans comes back as they are repaid or reach their end, at most 21 days after they start. Unpark withdraws at most what the vault can pay the wallet now, and the rest stays in the vault until it frees up.
* **A loan past its end.** Until someone books its outcome, the vault takes no deposit and pays nothing out. Anyone may book it, and gage's keeper does so on each of its passes. A batch that must book one first answers `again: true` with that call alone: send it, then ask for the batch again.
* **The buffer.** The vault keeps a share of deposits out of loans, which is part of its free cash.

## Refusals

Every refusal is an `ApiError` with a fixed `code`:

| Code                                                              | Meaning                                                                                                                                    |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `IN_RANGE`                                                        | The position is in range and earns fees: it parks once the price leaves its range.                                                         |
| `ETH_NOT_SUPPORTED`                                               | The position holds ETH or WETH, which no gage vault takes yet.                                                                             |
| `VAULT_ASSET_MISMATCH`                                            | The vault takes another token than the position holds.                                                                                     |
| `UNKNOWN_POOL`, `POSITION_NOT_FOUND`, `NOT_OWNER`                 | The pool is not one you named, the position does not exist, or the wallet does not hold it.                                                |
| `NOTHING_TO_PARK`, `BELOW_MINIMUM`                                | The position holds nothing, or less than the vault's least deposit (one whole token).                                                      |
| `VAULT_ASSET_NOT_IN_POOL`, `RANGE_WITHOUT_ASSET`, `INVALID_RANGE` | Unparking from a vault whose asset the pool does not pair, into a range that holds only the other token, or ticks that are not the pool's. |
| `NOTHING_TO_WITHDRAW`, `INSUFFICIENT_LIQUIDITY`                   | The vault can pay the wallet nothing now, or less than the amount asked: try again once its loans come back.                               |
| `SIMULATION_FAILED`                                               | The batch would revert now; the message names the call.                                                                                    |

The full list is in the SDK's [README](https://github.com/DebenLabs/gage-sdk/tree/main/packages/sdk#errors).


---

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