Borrow widget

This guide shows how to turn on Borrow in an existing @stakekit/widget integration. If you already embed the widget for Earn, your Earn setup stays as it is. You update the widget to 0.0.290, add two config props and, if your app manages the wallet, add two methods to your wallet adapter. Once Borrow is on, users supply collateral, borrow, manage positions, repay and withdraw collateral from the widget. To build your own Borrow interface instead, see the Borrow API guide.

At a glance

Item	Value
Widget version	`@stakekit/widget` 0.0.290
API key	The same project key you use for Earn. No extra key.
Borrow access	Borrow is enabled per project by the Yield.xyz team.
Networks in the widget	Ethereum, Base, Arbitrum and Optimism
Integrations	Aave V3, Morpho Blue, SparkLend and Lista Lending
React	React 19 if you use `SKApp`
Fees	Off unless configured for your project. See Borrow monetization.

Prerequisites

Borrow enabled for your project. Email hello@yield.xyz with the API key you test with. Start with your dev environment.
A funded test wallet on Ethereum or Base, holding collateral (for example WETH or cbBTC) and native gas. Testing on Base costs less than on Ethereum.

npm install @stakekit/widget@0.0.290

If you use SKApp, your app needs React 19. The widget now uses its own wallet dialogs instead of RainbowKit, so remove color.connectKit and borderRadius.connectKit from your theme if you set them.

Upgrading from an earlier version

Skip this section for a new integration on 0.0.290. These are the changes since 0.0.282 that can break or change an existing integration.React 19. The react and react-dom peers are >=19. Upgrade your host app first if it is on React 18.Removed props and exports:

Removed	What to do
`createWallet`, `evmChainGroup`, `TrackingContextProvider`	Remove the imports. Pass analytics through the `tracking` prop.
`wagmi.__customConnectors__`, `mapWalletListFn`	Remove them. Use `walletPolicy` to filter and order the built-in wallet picker.
`wagmi.forceWalletConnectOnly`, `forceWalletConnectOnly`	Remove them.
`disableGasCheck`	Remove it.
`color.connectKit`, `borderRadius.connectKit`	Remove these theme properties.
`externalProviders.supportsBorrow`	Remove it. It has no effect; Borrow follows `borrowEnabled`.
`tokensForEnabledYieldsOnly`	Still accepted but has no effect. Earn always lists project-enabled yields.

Wallet dialogs (0.0.290). RainbowKit is gone. The widget ships its own connect, account and chain dialogs and its own WalletConnect. Existing Tron, Cosmos and Polkadot WalletConnect sessions reconnect once after the update.Adapter results (0.0.290). sendTransaction can resolve { type: "cancelled" } when the user declines, and signMessage can resolve a result object (success, cancelled or error) as well as a plain signature string. Borrow methods accept result objects only. signTypedData moved off SKWallet and is now a required Borrow method.Browser renderer. renderSKWidget returns { rerender, unmount }. Call unmount() when your page removes the widget.External provider state sync. The widget syncs your provider snapshot (address, chain, supported chains and callbacks) on every update. Keep externalProviders present while the wallet is disconnected, with currentAddress: "". Adding or removing externalProviders needs a remount.

Turn on Borrow

Borrow needs two props:

dashboardVariant: true. Borrow appears in the dashboard tab bar, next to Manage and Activity.
borrowEnabled: true.

The widget must also group yields by category. With dashboardVariant on, grouping defaults to "category", so remove yieldGrouping: "flat" if you set it. Add the two props:

import "@stakekit/widget/style.css";
import { SKApp, darkTheme } from "@stakekit/widget";

export const Widget = () => (
  <SKApp apiKey={YIELD_API_KEY} theme={darkTheme} dashboardVariant borrowEnabled />
);

Keep your theme and other Earn props as they are. Once Borrow is enabled for your project, the Borrow tab appears next to Earn.

If your app manages the wallet

If you pass your own wallet through externalProviders, your adapter needs two more methods. Your Earn methods (signMessage, switchChain and sendTransaction) stay as they are.

Method	What it does
`sendBorrowTransaction`	Signs and broadcasts one Borrow transaction through your wallet.
`signTypedData`	Signs an EIP-712 payload when a Borrow step asks for a signature instead of a transaction.

The widget checks for both methods when it mounts. If either is missing, it rejects the configuration with borrow-provider-capability-missing.

The adapter: `SKBorrowWallet`

SKBorrowWallet is your Earn SKWallet plus the two Borrow methods. These types are exported from both @stakekit/widget and @stakekit/widget/bundle: SKWallet, SKBorrowWallet, SKBorrowTx, SKBorrowTxMeta, SKBorrowTxResult, SKBorrowSignatureResult, SKBorrowExternalProviders and SKEip712TypedData.

import type { SKBorrowWallet } from "@stakekit/widget";

export const wallet: SKBorrowWallet = {
  // Unchanged from your Earn adapter.
  signMessage: async (message) => yourWallet.signMessage(message),
  switchChain: async (chainId) => yourWallet.switchChain(chainId),
  sendTransaction: async (tx, txMeta) => {
    const txHash = await yourWallet.sendTransaction(tx.tx);
    return { type: "success", txHash };
  },

  // Sign an EIP-712 payload for a Borrow step.
  signTypedData: async (typedData, txMeta) => {
    const signature = await yourWallet.signTypedData(typedData);
    return { type: "success", signature };
  },

  // Sign and broadcast one Borrow transaction.
  sendBorrowTransaction: async (tx, txMeta) => {
    const txHash = await yourWallet.sendTransaction(tx.tx);
    return { type: "success", txHash };
  },
};

The yourWallet calls are placeholders for your wallet SDK or custody provider. getTransactionReceipt remains optional, as it is for Earn.

Results

Both Borrow methods return a result object. A plain hash or signature string is rejected as Invalid external provider result.

// Broadcast. Resolve as soon as it is broadcast, not after confirmation.
{ type: "success", txHash: "0x..." }

// The user declined in the wallet. Nothing was broadcast.
{ type: "cancelled" }

// Failed before broadcast. The user can retry the step.
{ type: "error", error: "Rejected by approver" }

// Broadcast, then a later check failed (for example a receipt timeout).
// The widget tracks this hash instead of asking to sign again.
{ type: "error", error: "Receipt timeout", txHash: "0x..." }

{ type: "success", signature: "0x..." }
{ type: "cancelled" }
{ type: "error", error: "Signing rejected" }

A rejected promise counts as error without a txHash.

Do not cast an Earn-only adapter to SKBorrowWallet to satisfy the compiler. The widget calls sendBorrowTransaction and signTypedData on it.

What is in `SKBorrowTx`

SKBorrowTx is { type: "evm"; tx }, where tx has:

Field	Type	Notes
`to`	`0x` hex string	Target contract.
`from`	`0x` hex string	The connected address.
`data`	`0x` hex string	Calldata.
`value`	`0x` hex string or `undefined`	Native value, hex encoded.
`gas`	`0x` hex string	Gas limit from the Borrow API.
`chainId`	`0x` hex string	Hex encoded, not a number.
`type`	`"0x0"` or `"0x2"`	`"0x0"` is legacy and carries `gasPrice`. `"0x2"` is EIP-1559 and carries `maxFeePerGas` and `maxPriorityFeePerGas`.

Fee fields are undefined unless the Borrow API quotes them; your signer estimates them in that case. Borrow transactions carry no nonce, so your wallet assigns it.

What is in `SKBorrowTxMeta`

Field	Values
`actionId`	The Borrow action id.
`actionType`	`"supply"`, `"borrow"`, `"repay"`, `"withdraw"`, `"enableCollateral"`, `"disableCollateral"`
`address`	The wallet address for the action.
`integrationId`	The Borrow integration (protocol) the market belongs to.
`txId`	The id of this transaction step.
`txType`	`"APPROVAL"`, `"AUTHORIZE"`, `"DEAUTHORIZE"`, `"SUPPLY"`, `"BORROW"`, `"REPAY"`, `"WITHDRAW"`, `"ENABLE_COLLATERAL"`, `"DISABLE_COLLATERAL"`, `"BUNDLE"`, `"WRAP"`
`rawArguments`	`marketId` (always), plus any of `amount`, `amountRaw`, `borrowAmount`, `collateralAmount`, `collateralAmountRaw`, `collateralTokenAddress`, `repayAll`, `targetLtv` and `tokenAddress`

actionType is what the user asked for. txType is what this one transaction does. Use these fields to label the request your users or approvers see.

How a Borrow action runs

One action can need several steps, for example an APPROVAL, then a SUPPLY, then a BORROW. For each step:

The widget asks your adapter for a transaction (sendBorrowTransaction) or a signature (signTypedData).
Your adapter signs, and for a transaction, broadcasts.
Your adapter returns the hash or the signature.
For a transaction, the widget reports the hash to the Borrow API and polls for confirmation: 20 checks, 2 seconds apart, about 40 seconds in total. For a signature, the widget submits it to the Borrow API itself.
Once the step is confirmed, the widget moves to the next one.

The widget waits for your adapter with no timeout, so custody and multi-approval flows that take several minutes still complete. Return the hash only after the transaction is broadcast. If you return it earlier, polling can end before the transaction reaches the chain. Keep passing your adapter through externalProviders, as you do for Earn.

import "@stakekit/widget/style.css";
import { SKApp, darkTheme, type SupportedSKChainIds } from "@stakekit/widget";
import { wallet } from "./wallet";

type Props = {
  address: string | undefined;
  chainId: SupportedSKChainIds;
  chainIds: SupportedSKChainIds[];
};

export const Widget = ({ address, chainId, chainIds }: Props) => (
  <SKApp
    apiKey={YIELD_API_KEY}
    theme={darkTheme}
    dashboardVariant
    borrowEnabled
    externalProviders={{
      type: "generic",
      currentAddress: address ?? "", // "" while disconnected, never null
      currentChain: chainId,
      supportedChainIds: chainIds, // include the Borrow networks you want
      provider: wallet,
    }}
  />
);

import "@stakekit/widget/style.css";
import { renderSKWidget, darkTheme, type SupportedSKChainIds } from "@stakekit/widget/bundle";
import { wallet } from "./wallet";

declare const initialChainId: SupportedSKChainIds; // the chain your app starts on

const baseProps = {
  apiKey: YIELD_API_KEY,
  theme: darkTheme,
  dashboardVariant: true,
  borrowEnabled: true,
};

const provider = (address: string, chainId: SupportedSKChainIds) => ({
  type: "generic" as const,
  currentAddress: address,
  currentChain: chainId,
  provider: wallet,
});

const widget = renderSKWidget({
  container: document.getElementById("yield-widget")!,
  ...baseProps,
  externalProviders: provider("", initialChainId),
});

// On account or chain change:
widget.rerender({ ...baseProps, externalProviders: provider(address, chainId) });

// On teardown:
widget.unmount();

Use the exported chain id constants for currentChain and supportedChainIds, or validate the ids from your SDK, rather than casting a plain number.

Disconnected wallet. Keep externalProviders and set currentAddress: "". Do not pass null or undefined, and do not remove the object. To add or remove externalProviders itself, remount the widget.
Rerender. rerender replaces all props. It does not merge them, so pass the full set each time.
Read at mount. apiKey, baseUrl, borrowApiUrl, yieldsApiUrl and borrowEnabled are read when the widget mounts. Remount to change them. Other props, including borrowMarketsScope, update live.
During a flow. Each step uses the provider you passed most recently. Keep both Borrow methods on every rerender, or the next step fails.

The widget sends your API key as the X-API-KEY header to borrowApiUrl, which defaults to https://borrow.yield.xyz. You do not need to set borrowApiUrl.

Which markets appear

borrowMarketsScope sets which markets the Borrow tab lists for new borrows:

Value	Lists
`"all"`	Default. Every supported market on the wallet’s current network that passes the filters below.
`"enabled"`	Only the markets enabled for your project.

<SKApp apiKey={YIELD_API_KEY} dashboardVariant borrowEnabled borrowMarketsScope="enabled" />

To use "enabled", send the Yield.xyz team the markets you want for your project. Until a list is set, "enabled" shows no markets, so keep "all" until then. Existing positions stay visible and manageable under either scope. Markets load for the wallet’s current network only, on Ethereum, Base, Arbitrum and Optimism. A market is listed for new borrows only when:

borrowing is enabled on it,
it has at least $10,000 of available liquidity (a loan token with no USD price counts as no liquidity),
its borrow rate is 100% or lower, and
it has at least one collateral with a max LTV of 1% or more that is not the loan token itself.

Lists are sorted by available liquidity. Aave V3 and SparkLend are pooled markets, labeled by loan token, where all collateral sits in one account. Morpho Blue and Lista are isolated markets, labeled by their collateral and loan token pair. The widget handles both, so no per-protocol code is needed.

What the user sees

Borrow tab

The dashboard tab bar shows the Earn category tabs, then Borrow, then Manage and Activity.

Pick a market and collateral

The user picks a market for the wallet’s network, then a collateral. Collateral the wallet holds is listed first. The user enters amounts, with a Max shortcut.

Review

The review shows the action, the loan-to-value and health factor before and after, and any warnings. If the Borrow API rejects the action, its reason shows here.

Steps

The widget runs each transaction or signature in order. Each one has its own collapsible step, with an explorer link once it is submitted.

Manage and Activity

Borrow positions appear under Manage next to Earn positions, where the user repays or withdraws collateral. Borrow actions appear in Activity, with a Borrow filter and a receipt showing the market, fees, loan-to-value and health factor.

Risk checks. The health factor limit applies to every change that adds risk. The max LTV limit blocks only changes that add debt. A withdrawal past max LTV with a health factor of 1 or more shows a warning instead. Loan-to-value turns amber from 90% of max LTV and red past it; the health factor turns amber at 1.1 or below and red below 1. A full repayment can go ahead when the wallet balance appears insufficient, because the Borrow API checks the live balance when it builds the transaction. If you pass tracking, Borrow adds these page names: "Borrow", "Borrow review", "Borrow steps" and "Borrow complete", and these events: "Borrow market selected", "Borrow collateral selected", "Borrow page max clicked" and "Borrow review clicked".

Testing

Update to 0.0.290 and turn on Borrow in your dev environment.
If you pass your own wallet, implement both Borrow methods.
Connect the test wallet on Base or Ethereum.
Open Borrow, pick a USDC market (for example on Aave V3 or Morpho Blue), supply collateral and borrow a small amount, such as 10 USDC.
Approve each step in your wallet. If you pass your own wallet, check that each request shows the expected txType.
Open Manage and check that the position shows the collateral and the debt. Check that the action shows in Activity.
Repay in full, then withdraw all collateral. Check that the position is gone from Manage.

If you pass your own wallet, also check that declining a request returns { type: "cancelled" }, that signTypedData works when a step asks for it, that an empty currentAddress keeps the widget running, and that switching networks updates the market list. Compare the behavior with the demo.

Troubleshooting

The widget logs errors to the browser console. Configuration problems include an issue code and the prop path. Each entry is titled with the console message, or with the symptom when there is no message.

Configuration

Initial Widget Configuration is invalid

After you add borrowEnabled, the Borrow tab does not appear or the widget does not start. The widget logs this message on first mount with one of these issues:

Issue	Path	Fix
`borrow-requires-dashboard`	`dashboardVariant`	Set `dashboardVariant: true`.
`borrow-requires-category-grouping`	`yieldGrouping`	Remove `yieldGrouping: "flat"`.
`borrow-provider-capability-missing`	`externalProviders.provider`	Implement both `sendBorrowTransaction` and `signTypedData`.
`host-configuration-decode-failed`	`externalProviders.provider`	The `provider` object is missing from `externalProviders`.

Widget Configuration update rejected

The Borrow tab opens but shows no markets

Check that the wallet is on Ethereum, Base, Arbitrum or Optimism, and that the chain is in supportedChainIds. With borrowMarketsScope: "enabled", check that markets are enabled for your project, or switch to "all".

Signing

Borrow typed-data signing capability is unavailable

A step needs an EIP-712 signature and the provider has no signTypedData. Implement it, and keep it on every rerender.

Borrow transaction capability is unavailable

A step started and the provider had no sendBorrowTransaction. Keep both Borrow methods on every provider you pass.

Invalid external provider result

The adapter returned something other than a result object, such as a plain hash string. Return { type: "success", txHash } or { type: "success", signature }.

The signed transaction payload is not available.

The adapter reported success without a hash. Return the hash after broadcast, or return { type: "error", error }.

Confirmation

Transaction confirmation polling was exhausted.

The hash came back, but the Borrow API did not see a confirmed transaction within about 40 seconds. Return the hash only after broadcast, and check that it is on the chain in tx.tx.chainId.

Borrow transaction ended with FAILED status.

Also appears as Borrow transaction ended with NOT_FOUND status. The transaction reverted, or the hash is wrong or on another chain. Compare the hash in your wallet with the one you returned.

Wallet sync

Wallet Runtime invariant violated

externalProviders was added or removed after mount (external-provider-presence-changed). Keep the object present with currentAddress: "" while the wallet is disconnected, or remount the widget. Account and chain changes do not need a remount.

External provider connection failed

The widget tried to connect the currentAddress you passed and the connection failed. Check that the address and currentChain match the account and chain active in your wallet.

Build

The build fails after the update

Look for the removed props and exports in Upgrading from an earlier version, and check that React is on version 19.

FAQ

Do we need a new API key for Borrow?

No. Borrow uses the same project key as Earn. Yield.xyz enables Borrow for that project.

Does turning on Borrow change our Earn integration?

No. Earn stays as it is. Borrow adds a tab and adds Borrow positions and actions to Manage and Activity. If your app manages the wallet, you add the two Borrow methods.

Can we limit the widget to certain markets?

Why does the widget support only four networks?

Does Borrow work with custody and multi-approval wallets?

Yes. The widget waits for your adapter with no timeout. Return the hash once the transaction is broadcast, and the widget tracks confirmation from there.

Are there fees?

Not unless they are configured for your project. Fees apply to Morpho Blue markets. Contact hello@yield.xyz and see Borrow monetization.

Get started

AI & Agents

Earn

Trade

Borrow

Widgets & UI

Dashboards

Integrations & signing

Enterprise

Legacy & migration

At a glance

Prerequisites

Update the widget

Turn on Borrow

If the widget connects the wallet

If your app manages the wallet

The adapter: `SKBorrowWallet`

Results

What is in `SKBorrowTx`

What is in `SKBorrowTxMeta`

How a Borrow action runs

Pass your wallet to the widget

Which markets appear

What the user sees

Testing

Troubleshooting

Configuration

Signing

Confirmation

Wallet sync

Build

FAQ

Next steps

Borrow API

Core concepts

​At a glance

​Prerequisites

​Update the widget

​Turn on Borrow

​If the widget connects the wallet

​If your app manages the wallet

​The adapter: SKBorrowWallet

​Results

​What is in SKBorrowTx

​What is in SKBorrowTxMeta

​How a Borrow action runs

​Pass your wallet to the widget

​Which markets appear

​What the user sees

​Testing

​Troubleshooting

​Configuration

​Signing

​Confirmation

​Wallet sync

​Build

​FAQ

​Next steps

Borrow API

Core concepts

At a glance

Prerequisites

Update the widget

Turn on Borrow

If the widget connects the wallet

If your app manages the wallet

The adapter: `SKBorrowWallet`

Results

What is in `SKBorrowTx`

What is in `SKBorrowTxMeta`

How a Borrow action runs

Pass your wallet to the widget

Which markets appear

What the user sees

Testing

Troubleshooting

Configuration

Signing

Confirmation

Wallet sync

Build

FAQ

Next steps