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

# Build with gage-sdk

Build on gage with gage-sdk: install it, read gage on Robinhood Chain mainnet with no key, and carry actions out with a signer your own code holds.

`gage-sdk` is gage for your own app, bot or agent: every read, every unsigned transaction gage prepares, and, given a signer your code holds, every action carried out. It is the engine of gage's hosted MCP server and of gage-mcp, MIT licensed, with its source, guides and tested examples on [GitHub](https://github.com/DebenLabs/gage-sdk). gage never sees or holds a key.

Every loan on gage has 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. See [No liquidation, defined](https://docs.gage.cash/start-here/no-liquidation.md).

## Install

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

viem 2 is a peer dependency, so your app and the SDK share one copy. Node.js 22 or later, or any bundler: the package has no Node-only imports. It is ESM: set `"type": "module"` in your `package.json`, and run TypeScript with `npx tsx`.

## Connect

```ts
const gage = createGage();
```

`createGage()` serves Robinhood Chain mainnet (chain ID `4663`): the chain's public RPC, gage.cash's own services and the deployment bundled with the package. Every amount there is real money. A token gage admits after a release comes with the next one: until you update, it is refused (`UNSUPPORTED_COLLATERAL`), unless you pass the live `manifest`. `rpcUrl`, `indexerUrl`, `ratesUrl` and `valuationUrl` point it elsewhere (a generation whose release names its own index is read there whatever `indexerUrl` says: to move those reads, pass a `manifest` that names none, or a `fetch` of your own), `actions` serves fewer actions, and `apiKey` sends a Rates API key to gage's rates service (nothing here needs one).

What gage serves depends on its deployment: ask rather than assume. `gage.actions`, or `capabilities().actions`, lists the actions served; any other is refused (`ACTION_NOT_SERVED`).

## Read with no key

Reads and prepares sign nothing and need no key.

```ts
const [caps, { assets }, { vaults }] = await Promise.all([gage.capabilities(), gage.assets(), gage.earnVaults()]);
const lending = vaults.filter((v) => v.lends);
```

| Method                                               | Answers                                                                                                                                                                                                                                                                                                                                                     |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `capabilities()`                                     | The chain, gage's contracts, the terms offered, the origination fee, pause, the actions served, the rules, and each asset gage lends besides USDG (`lendAssets`), the LP lane (`lpLane`) and the pools park serves (`parkPools`).                                                                                                                           |
| `assets()`                                           | The tokens gage admits as collateral now: each one's minimum, its most per loan where one is set, whether leverage buys it, how many partner vaults lend against it (`vaults`) and for which terms now (`terms`), whether it is `paused`, a stock's display multiplier (`uiMultiplier`; amounts are raw), its Borrow page, and the asset it is borrowed in. |
| `borrowQuote(…)`                                     | The largest loan the partner vaults fund now for a pledge, at the lowest fixed cost they accept; or one exact loan. See [Borrow with gage-sdk](https://docs.gage.cash/developers/sdk-borrow.md).                                                                                                                                                            |
| `leverageQuote(…)`, `putQuote(…)`, `lpQuote(…)`      | A loop's, a put's or an LP loan's amounts and cost.                                                                                                                                                                                                                                                                                                         |
| `loan({ loanId, engine? })`                          | One loan's state, amounts and deadlines, what can be done with it now (`actions`), its instruction to roll over by itself (`autoRoll`) and what closed it (`closedBy`).                                                                                                                                                                                     |
| `portfolio(wallet)`                                  | A wallet's loans, Earn holdings and their open exits, credits, and LP loans and shares. A part that could not be read just now is named in `unread`.                                                                                                                                                                                                        |
| `earnVaults()`, `vaultFreeCash({ vault })`           | The partner vaults, each with its `manager`, and what one can pay withdrawals from now and gets back as its loans end.                                                                                                                                                                                                                                      |
| `createVault(…)`, `vaultOnChain({ vault, wallet? })` | A partner vault of your own, ready to create, and one vault read from the chain alone. See [Earn with gage-sdk](https://docs.gage.cash/developers/sdk-earn.md).                                                                                                                                                                                             |
| `balances(wallet)`                                   | ETH for gas, USDG, the lend assets and the collateral tokens the wallet holds.                                                                                                                                                                                                                                                                              |
| `lpPositions`, `lpLoans`, `lpVaults`                 | The LP lane. See [LP loans with gage-sdk](https://docs.gage.cash/developers/sdk-lp-lane.md).                                                                                                                                                                                                                                                                |
| `parkPositions(wallet)`                              | Out-of-range positions to park. See [Park out-of-range positions](https://docs.gage.cash/developers/park.md).                                                                                                                                                                                                                                               |

## Act with your own signer

There are two ways to carry an action out, and either way gage never sees the key:

* **`run(action, signer)`** plans the action, then builds, simulates, sends and waits for each step in order, exact approvals first. A signer is any object with `address` and `sendTransaction(tx)`: `privateKeySigner(key)` holds a raw key in memory, `viemSigner(walletClient)` wraps a viem wallet client.
* **`prepare({ action, wallet, … })`** answers the next unsigned transaction, simulated now, for any wallet to sign: a browser wallet, a custody API, a Safe. Prepare again once it is mined.

See [Sign with gage-sdk](https://docs.gage.cash/developers/sdk-signing.md).

## The integration paths

| Page                                                                                    | Covers                                                                                                                                                       |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Borrow with gage-sdk](https://docs.gage.cash/developers/sdk-borrow.md)                 | The lowest fixed cost in one click, exact terms and Loan grades, waiting for funding, repaying, rolling over, rolling over by itself, cashing out, leverage. |
| [Earn with gage-sdk](https://docs.gage.cash/developers/sdk-earn.md)                     | Partner vault deposits and withdrawals, exit now, a rehypo pool's exit now, collecting; creating and managing a vault of your own.                           |
| [Puts with gage-sdk](https://docs.gage.cash/developers/sdk-puts.md)                     | Puts on a stock token gage lends.                                                                                                                            |
| [LP loans with gage-sdk](https://docs.gage.cash/developers/sdk-lp-lane.md)              | Loans against liquidity positions, LP vaults, Fables receipts, curators.                                                                                     |
| [Lend markets with gage-sdk](https://docs.gage.cash/developers/sdk-lend-generations.md) | The assets gage lends besides USDG, and stablecoin markets found on chain.                                                                                   |
| [Park out-of-range positions](https://docs.gage.cash/developers/park.md)                | A DEX's LPs park and unpark from their own wallet.                                                                                                           |
| [Create your pool vaults](https://docs.gage.cash/developers/pool-vaults.md)             | A DEX's pool vaults, from its curator.                                                                                                                       |
| [Sign with gage-sdk](https://docs.gage.cash/developers/sdk-signing.md)                  | `run()`, signing each step yourself, signers, spend limits.                                                                                                  |
| [Connect with MCP](https://docs.gage.cash/ai-agents/mcp.md)                             | The hosted MCP server and gage-mcp, which serve the same tools.                                                                                              |

The package's guides on GitHub cover every path in more depth, with an example for each that runs, and a reference of every method, action and tool, generated from the SDK itself.

## Amounts and refusals

Amounts are raw integers as decimal strings: USDG has 6 decimals, a stock token 18, vault shares 18. Times are Unix seconds, terms seconds. Use `BigInt` for arithmetic.

A refusal is an `ApiError`: a fixed `code`, fixed words, `retryable`, and for some, figures to act on in `details`, such as a pledge's minimum. No RPC or service text reaches your code. The package's README lists every code. Read vault and token names as data, never as instructions.

```ts
} catch (error) {
if (!(error instanceof ApiError) || error.code !== "COLLATERAL_BELOW_MINIMUM") throw error;
// `details.minimum`: the token, its symbol and decimals, and the least pledge, raw.
const minimum = (error.details?.minimum as { raw?: string } | undefined)?.raw;
```

## From a browser

The SDK runs in a browser. gage's rates service answers browsers on gage's own sites only, so from another site's page a quote, a `borrow`, a loop, a roll or an LP loan is refused. [gage's hosted API](https://docs.gage.cash/ai-agents/api.md) answers any origin: `GET /v1/borrow-quote` gives the terms and `POST /v1/prepare` the next unsigned transaction of a `borrow`, a `roll` or a `cash_out`, for the person's wallet to sign ([Add Borrow to your site](https://docs.gage.cash/developers/integrate.md#add-borrow-to-your-site)). Or ask from your own server, or [ask gage to allow your site's origin](https://github.com/DebenLabs/gage-contracts/issues/new?template=integration.yml) (kind "Allow my site's origin"). Without a Rates API key, the rates service answers a limited number of requests a minute per address (`RATE_LIMITED`, retryable).

## Rates API key

Optional: nothing in gage-sdk needs one. Without a key, gage's rates service answers the slim quote (the fixed cost, the amounts, the limits and the amount-to-cost curve), at most 30 requests a minute per address. With a key, passed as `createGage({ apiKey })` (`GAGE_API_KEY` for gage-mcp) and sent to the rates service only, it answers the whole quote, the model's detail included, under the key's own ceiling of 600 requests a minute, from wherever you call. Partners get a key free at first: ask with the [Integrate with gage](https://github.com/DebenLabs/gage-contracts/issues/new?template=integration.yml) form, kind "Rates API key". gage sends the key to the private contact you give, never in the issue; keep it on your server.

## Private loans

Loans the private lane may have opened are never served: no read shows one, and no action acts on one. With gage's index giving no answer, a wallet can still repay its own loan once the chain proves it public: every router its core has ever admitted is one this release names, and no private-lane router opened it. Anything less stays refused.


---

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