> ## Documentation Index
> Fetch the complete documentation index at: https://yieldxyz.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# BorrowKit

> Unified borrowing infrastructure for DeFi lending markets across protocols and networks

The **Borrowing API** is a unified layer for interacting with on-chain lending/borrowing protocols. It provides:

* **Normalized market data** — rates, liquidity, and collateral parameters across venues
* **A consistent action model** — supply, borrow, repay, withdraw, collateral toggles
* **Unified account state** — positions, debt, health factor, and borrow power
* **Transaction construction** — unsigned payloads ready for wallet signing
* **Step-based execution** — multi-transaction flows (e.g., ERC-20 approval → supply/repay)

Request and response shapes are identical across protocols and networks. Whether the underlying venue is **Aave on Ethereum** or **Morpho on Base**, your integration does not change.

***

## What you can build

<CardGroup cols={2}>
  <Card title="Wallets & Super Apps" icon="wallet">
    Embed borrowing flows directly into wallet UX — let users leverage their assets in one tap.
  </Card>

  <Card title="Exchanges & Trading Platforms" icon="chart-line">
    Offer margin-like borrowing powered by DeFi lending protocols with full self-custody.
  </Card>

  <Card title="Neobanks & Fintechs" icon="building-columns">
    Provide crypto-collateralized credit lines backed by on-chain lending markets.
  </Card>

  <Card title="Treasury & Corporate" icon="chart-pie">
    Optimize capital efficiency by borrowing against idle collateral across protocols.
  </Card>
</CardGroup>

***

## Core capabilities

* **Discoverability & capability introspection** — List supported integrations (protocol + product type), see which networks each supports, and inspect available actions with argument schemas.
* **Market discovery (normalized MarketDto)** — Browse markets across protocols and chains with a consistent shape. Compare rates, liquidity, and utilization using stable fields across venues.
* **Portfolio & risk state (positions)** — Read supplied collateral, borrowed debt, and aggregated portfolio metrics: `healthFactor`, `currentLtv`, `availableToBorrowUsd`, liquidation thresholds, net APY, and accrued interest.
* **Transaction building (intent → signable payloads)** — Convert an intent like "borrow 2.5 WETH from market X" into one or more unsigned on-chain transactions (approvals + protocol calls) ready for client-side signing.
* **Execution orchestration (step-based actions)** — Actions that require multiple transactions follow a consistent state machine: create action → sign/submit → poll → step → repeat → success/failure.

***

## Supported protocols

<Tabs>
  <Tab title="Aave">
    | Field              | Value                                                                                              |
    | ------------------ | -------------------------------------------------------------------------------------------------- |
    | **Integration ID** | `aave-borrow`                                                                                      |
    | **Name**           | Aave V3 Borrow                                                                                     |
    | **Market type**    | Pool — shared liquidity across assets; collateral types and debts live under the same pool context |
    | **Networks**       | Ethereum, Optimism, Arbitrum, Polygon, Avalanche, Base, BNB Chain, Gnosis, Sonic, Linea, Plasma    |
  </Tab>

  <Tab title="Morpho">
    | Field              | Value                                                                                        |
    | ------------------ | -------------------------------------------------------------------------------------------- |
    | **Integration ID** | `morpho-blue-borrow`                                                                         |
    | **Name**           | Morpho Blue Borrow                                                                           |
    | **Market type**    | Isolated — each collateral–loan pair is a standalone market with isolated risk and liquidity |
    | **Networks**       | Ethereum, Arbitrum, Avalanche, Base, BNB Chain, Gnosis, Linea, Optimism, Polygon, Sonic      |
  </Tab>
</Tabs>

### Market types: Pool vs Isolated

* **Pool markets (Aave)**: shared liquidity across assets inside a pool; collateral types and debts live under the same pool context.
* **Isolated markets (Morpho Blue)**: each collateral–loan pair is a standalone market with isolated risk and liquidity.

***

## Integration at a glance

<Steps>
  <Step title="Discover markets">
    Use `GET /v1/markets` to browse and filter available lending/borrowing markets across protocols and chains.
  </Step>

  <Step title="Fetch current account state (optional)">
    Use `GET /v1/positions` to show balances, risk metrics, and available actions for a user's portfolio.
  </Step>

  <Step title="Create an action">
    Use `POST /v1/actions` with `{ integrationId, action, address, args }` to get unsigned transaction(s).
  </Step>

  <Step title="Sign & submit transactions">
    For each returned `TransactionDto`, sign it with your wallet/custody infrastructure, then `POST /v1/transactions/:transactionId/submit`.
  </Step>

  <Step title="Advance multi-step actions">
    Poll `GET /v1/actions/:id` until `WAITING_FOR_NEXT`, then call `POST /v1/actions/:id/step` for the next transaction(s). Repeat until `hasNextStep=false` and `status=SUCCESS`.
  </Step>

  <Step title="Refresh positions">
    Confirm final state via `GET /v1/positions`.
  </Step>
</Steps>

***

## Integration options

<CardGroup cols={2}>
  <Card title="Option A — Drop-in Widget (React)" icon="puzzle-piece">
    The Yield.xyz Borrowing Widget is a drop-in lending/borrowing frontend module built with React. It handles market discovery, live rates, portfolio state, action construction, and transaction signing — all out of the box.

    **Best for:** wallets, exchanges, and fintech apps that want a turnkey UI.
  </Card>

  <Card title="Option B — Direct API Integration" icon="code">
    Integrate natively while keeping full UI control. Build your own market browser and position UI, use the API for normalized data and transaction construction, and use your own signing/broadcast pipeline.

    **Best for:** custom UX or product-specific abstractions.
  </Card>
</CardGroup>

***

## Key concepts (risk & rates)

### Health factor

```text theme={null}
healthFactor = (totalCollateral × liquidationThreshold) / totalBorrowedValue
```

| Value | Meaning                  |
| ----- | ------------------------ |
| `> 1` | Safe                     |
| `= 1` | At liquidation threshold |
| `< 1` | Eligible for liquidation |

The API returns `healthFactor` on positions and `predictedHealthFactor` in action metadata (preview before signing).

### LTV and liquidation threshold

* **Max LTV** — how much can be borrowed against collateral.
* **Liquidation threshold** — the point where liquidation can occur (typically higher than max LTV, providing a buffer).
* **Liquidation penalty** — bonus paid to liquidators from collateral during liquidation.

### Rates

* **Supply APY** accrues on supplied assets.
* **Borrow APR** accrues on borrowed assets.
* Rates are typically utilization-driven — higher utilization → higher borrow rates and supply yields.

***

## API reference

### Integrations

#### List integrations

`GET /v1/integrations`

Returns all available lending/borrowing integrations with supported actions and argument schemas.

<CodeGroup>
  ```json Response — IntegrationDto[] theme={null}
  {
    "id": "aave-borrow",
    "providerId": "aave",
    "name": "Aave V3 Borrow",
    "networks": ["ethereum", "arbitrum", "optimism", "polygon", "avalanche", "base", "bsc", "gnosis", "sonic", "linea", "plasma"],
    "metadata": {
      "description": "Aave is a decentralized non-custodial liquidity protocol where users can participate as suppliers or borrowers.",
      "externalLink": "https://aave.com",
      "logoURI": "https://assets.stakek.it/providers/aave.svg"
    },
    "actions": [
      {
        "id": "supply",
        "label": "Supply",
        "schema": {
          "type": "object",
          "properties": {
            "marketId": { "type": "string" },
            "amount": { "type": "string" },
            "amountRaw": { "type": "string" }
          },
          "required": ["marketId"]
        }
      }
    ]
  }
  ```
</CodeGroup>

#### Get integration by ID

`GET /v1/integrations/:integrationId`

Returns a single integration by ID.

***

### Markets

#### List markets (paginated)

`GET /v1/markets`

| Parameter       | Type     | Required | Description                         |
| --------------- | -------- | -------- | ----------------------------------- |
| `integrationId` | `string` | No       | Filter by integration               |
| `network`       | `string` | No       | Filter by network                   |
| `offset`        | `number` | No       | Pagination offset (default `0`)     |
| `limit`         | `number` | No       | Page size (default `25`, max `100`) |

<CodeGroup>
  ```json Response — PaginatedResponseDto<MarketDto> theme={null}
  {
    "items": [
      {
        "id": "aave-v3-ethereum-usdc",
        "integrationId": "aave-borrow",
        "network": "ethereum",
        "type": "pool",
        "poolAddress": "0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2",
        "loanToken": {
          "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
          "symbol": "USDC",
          "name": "USD Coin",
          "decimals": 6,
          "logoURI": "https://assets.stakek.it/tokens/usdc.svg"
        },
        "collateralTokens": [
          {
            "token": {
              "address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
              "symbol": "WETH",
              "name": "Wrapped Ether",
              "decimals": 18,
              "logoURI": "https://assets.stakek.it/tokens/weth.svg"
            },
            "priceUsd": "2750.00",
            "ltv": "0.80",
            "liquidationThreshold": "0.85",
            "liquidationPenalty": "0.05",
            "supplyRate": "0.0312"
          }
        ],
        "borrowRate": "0.0487",
        "totalSupply": "1250000000.00",
        "totalSupplyRaw": "1250000000000000",
        "totalBorrow": "890000000.00",
        "totalBorrowRaw": "890000000000000",
        "availableLiquidity": "360000000.00",
        "availableLiquidityRaw": "360000000000000",
        "utilizationRate": "0.712",
        "loanTokenPriceUsd": "1.00",
        "isBorrowEnabled": true
      }
    ],
    "total": 142,
    "offset": 0,
    "limit": 25
  }
  ```
</CodeGroup>

#### Get market by ID

`GET /v1/markets/:marketId`

Returns a single market by ID.

***

### Positions

#### Get user positions

`GET /v1/positions`

Returns the user's full supply + borrow state for a given integration + network.

| Parameter       | Type     | Required | Description            |
| --------------- | -------- | -------- | ---------------------- |
| `integrationId` | `string` | Yes      | Integration identifier |
| `network`       | `string` | Yes      | Network identifier     |
| `address`       | `string` | Yes      | User wallet address    |

<CodeGroup>
  ```json Response — PositionDto theme={null}
  {
    "address": "0x1234...",
    "integrationId": "aave-borrow",
    "network": "ethereum",
    "totalSuppliedUsd": "10000.00",
    "totalBorrowedUsd": "8750.00",
    "netWorthUsd": "1250.00",
    "healthFactor": "1.37",
    "currentLtv": "0.72",
    "availableToBorrowUsd": "1250.00",
    "netApy": "0.0089",
    "supplyBalances": [
      {
        "marketId": "aave-v3-ethereum-usdc",
        "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "tokenSymbol": "USDC",
        "balance": "10000.000000",
        "balanceRaw": "10000000000",
        "balanceUsd": "10000.00",
        "apy": "0.0312",
        "isCollateral": true,
        "pendingActions": [
          {
            "type": "withdraw",
            "label": "Withdraw USDC",
            "args": { "marketId": "aave-v3-ethereum-usdc" }
          }
        ]
      }
    ],
    "debtBalances": [
      {
        "marketId": "aave-v3-ethereum-weth",
        "tokenAddress": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
        "tokenSymbol": "WETH",
        "balance": "2.500000000000000000",
        "balanceRaw": "2500000000000000000",
        "balanceUsd": "8750.00",
        "apy": "0.0523",
        "pendingActions": [
          {
            "type": "repay",
            "label": "Repay WETH",
            "args": { "marketId": "aave-v3-ethereum-weth" }
          }
        ]
      }
    ]
  }
  ```
</CodeGroup>

***

### Actions

#### Create an action

`POST /v1/actions`

Creates a lending/borrowing action and returns unsigned transaction(s) for signing.

**Request body — `ActionRequestDto`**

| Field           | Type     | Required | Description                                     |
| --------------- | -------- | -------- | ----------------------------------------------- |
| `integrationId` | `string` | Yes      | Integration identifier                          |
| `action`        | `string` | Yes      | Action type (see [Action types](#action-types)) |
| `address`       | `string` | Yes      | User wallet address                             |
| `args`          | `object` | Yes      | Action arguments                                |

**Action args (common)**

| Field                    | Type     | Required | Notes                                           |
| ------------------------ | -------- | -------- | ----------------------------------------------- |
| `marketId`               | `string` | Yes      | Target market identifier                        |
| `amount`                 | `string` | No\*     | Human amount (e.g. `"1.5"`)                     |
| `amountRaw`              | `string` | No\*     | Base units (e.g. `"1500000"`)                   |
| `tokenAddress`           | `string` | No       | Used when market needs explicit token selection |
| `collateralTokenAddress` | `string` | No       | For markets where collateral must be specified  |
| `collateralAmount`       | `string` | No       | Human collateral amount                         |
| `collateralAmountRaw`    | `string` | No       | Base units collateral amount                    |

<Note>
  Provide either `amount` or `amountRaw`, not both.
</Note>

<CodeGroup>
  ```json Supply example theme={null}
  {
    "integrationId": "aave-borrow",
    "address": "0x1234...",
    "action": "supply",
    "args": {
      "marketId": "aave-v3-ethereum-usdc",
      "amount": "10000"
    }
  }
  ```

  ```json Borrow example theme={null}
  {
    "integrationId": "aave-borrow",
    "address": "0x1234...",
    "action": "borrow",
    "args": {
      "marketId": "aave-v3-ethereum-weth",
      "amount": "2.5"
    }
  }
  ```
</CodeGroup>

<CodeGroup>
  ```json Response — ActionDto theme={null}
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "integrationId": "aave-borrow",
    "action": "supply",
    "address": "0x1234...",
    "status": "CREATED",
    "currentStep": 1,
    "totalSteps": 2,
    "hasNextStep": true,
    "transactions": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "network": "ethereum",
        "chainId": "1",
        "type": "APPROVAL",
        "status": "CREATED",
        "address": "0x1234...",
        "signingFormat": "EVM_TRANSACTION",
        "signablePayload": "0x..."
      }
    ],
    "metadata": {
      "currentHealthFactor": "1.82",
      "predictedHealthFactor": "1.37",
      "currentLtv": "0.55",
      "predictedLtv": "0.72",
      "liquidationThreshold": "0.85",
      "predictedTotalSupplyUsd": "20000.00",
      "predictedTotalDebtUsd": "8750.00"
    },
    "createdAt": "2026-02-23T12:00:00.000Z"
  }
  ```
</CodeGroup>

#### Get action

`GET /v1/actions/:id`

Returns the current state of an action (use for polling).

#### List actions (paginated)

`GET /v1/actions`

| Parameter       | Type     | Required | Description             |
| --------------- | -------- | -------- | ----------------------- |
| `address`       | `string` | No       | Filter by wallet        |
| `integrationId` | `string` | No       | Filter by integration   |
| `action`        | `string` | No       | Filter by action type   |
| `status`        | `string` | No       | Filter by action status |
| `offset`        | `number` | No       | Default `0`             |
| `limit`         | `number` | No       | Default `25`, max `100` |

#### Advance to next step

`POST /v1/actions/:id/step`

For multi-step actions, call after the current step confirms. Returns the next transaction(s) to sign.

***

### Transactions

#### Submit a signed transaction

`POST /v1/transactions/:transactionId/submit`

Submit either a `signedPayload` (API broadcasts) or a `transactionHash` (client already broadcast).

**Request body — `SubmitTransactionDto`**

| Field             | Type     | Description                           |
| ----------------- | -------- | ------------------------------------- |
| `signedPayload`   | `string` | Signed transaction payload (max 1 MB) |
| `transactionHash` | `string` | `0x` + 64 hex chars                   |

<CodeGroup>
  ```json Response — SubmitTransactionResponseDto theme={null}
  {
    "transactionHash": "0xabc123...",
    "link": "https://etherscan.io/tx/0xabc123...",
    "status": "BROADCASTED"
  }
  ```
</CodeGroup>

***

## Reference tables

### Action types

| Action              | Description                                                         |
| ------------------- | ------------------------------------------------------------------- |
| `supply`            | Deposit assets into a lending pool as collateral / to earn interest |
| `borrow`            | Borrow assets against supplied collateral                           |
| `repay`             | Repay borrowed debt (partial or full)                               |
| `withdraw`          | Withdraw supplied assets                                            |
| `enableCollateral`  | Enable a supplied asset as collateral                               |
| `disableCollateral` | Disable a supplied asset as collateral                              |

### Transaction types

| Type                 | Description                           |
| -------------------- | ------------------------------------- |
| `APPROVAL`           | ERC-20 approval (before supply/repay) |
| `SUPPLY`             | Deposit into the protocol             |
| `BORROW`             | Borrow from the protocol              |
| `REPAY`              | Repay debt                            |
| `WITHDRAW`           | Withdraw supplied assets              |
| `ENABLE_COLLATERAL`  | Enable collateral usage               |
| `DISABLE_COLLATERAL` | Disable collateral usage              |

### Transaction statuses

| Status                  | Meaning                                         |
| ----------------------- | ----------------------------------------------- |
| `CREATED`               | Ready for signing                               |
| `BLOCKED`               | Waiting on prior transaction                    |
| `WAITING_FOR_SIGNATURE` | Sent to signer                                  |
| `SIGNED`                | Signed by user                                  |
| `BROADCASTED`           | Broadcast submitted                             |
| `PENDING`               | Awaiting confirmations                          |
| `CONFIRMED`             | Confirmed on-chain                              |
| `FAILED`                | Failed on-chain                                 |
| `SKIPPED`               | Not needed (e.g., allowance already sufficient) |

***

## End-to-end examples

### Supply → Borrow (step-based)

```text theme={null}
1) GET  /v1/markets?integrationId=aave-borrow&network=ethereum

2) POST /v1/actions
   { integrationId:"aave-borrow", action:"supply", address:"0x...",
     args:{ marketId:"...", amount:"10000" } }

3) Sign tx(s) in ActionDto.transactions

4) POST /v1/transactions/{transactionId}/submit
   { signedPayload:"0x..." }

5) Poll GET /v1/actions/{actionId} until status=WAITING_FOR_NEXT

6) POST /v1/actions/{actionId}/step
   → next tx(s) (e.g., SUPPLY)

7) Sign + submit, then poll until status=SUCCESS

8) POST /v1/actions
   { integrationId:"aave-borrow", action:"borrow", address:"0x...",
     args:{ marketId:"...", amount:"2.5" } }

9) Sign + submit borrow tx, poll until SUCCESS

10) GET /v1/positions?integrationId=aave-borrow&network=ethereum&address=0x...
```

### Repay → Withdraw

```text theme={null}
1) POST /v1/actions (repay)
   → may return APPROVAL + REPAY as multi-step

2) For each step:
   - sign + submit tx(s)
   - poll until WAITING_FOR_NEXT
   - POST /v1/actions/{actionId}/step

3) POST /v1/actions (withdraw)
   - sign + submit
   - poll until SUCCESS
```

### Multi-step action lifecycle

Some actions require multiple on-chain transactions (e.g., ERC-20 approval before supply/repay):

1. `POST /v1/actions` → returns **step 1** transaction(s)
2. Submit step 1 → poll action
3. When action is `WAITING_FOR_NEXT` → `POST /v1/actions/:id/step`
4. Repeat until `hasNextStep=false` and `status=SUCCESS`

***

## Where to go next

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/documentation/quickstart">
    Make your first borrowing request
  </Card>

  <Card title="StakeKit" icon="coins" href="/documentation/kits/stakekit">
    Explore staking infrastructure
  </Card>

  <Card title="DeFiKit" icon="chart-line" href="/documentation/kits/defikit">
    Explore DeFi yield infrastructure
  </Card>

  <Card title="Contact Us" icon="envelope" href="mailto:hello@yield.xyz?subject=BorrowKit%20Access">
    Get in touch for integration support
  </Card>
</CardGroup>