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

# Yield.xyz Borrow

> Let your users supply collateral and borrow assets on Aave, Morpho, SparkLend and Lista with the Yield.xyz integration.

## Overview

Portal integrates with [Yield.xyz Borrow](https://docs.yield.xyz/reference/positionscontroller_getpositions_v1) so your users can supply collateral, borrow, repay and withdraw on leading lending protocols (Aave V3, Morpho Blue, SparkLend and Lista) with their Portal wallets. Portal proxies the Borrow API server-side using the API key you store in the Portal Dashboard, so the key never ships in your app.

<Note>
  Borrowing uses the same Yield.xyz API key and the same Portal integration as [Yield.xyz](/integrations/Yield/yield-xyz). If you have already enabled Yield.xyz in the Portal Dashboard, the Borrow endpoints below work right away; there is no separate card or key to add.
</Note>

This page covers how lending and borrowing works, the one-time setup in Yield.xyz and the Portal Dashboard, and what the proxied endpoints return.

## How lending and borrowing works

A lending market is a pool: suppliers deposit an asset and earn its **supply APY**; borrowers draw that asset out and pay the **borrow APY**. To borrow, a user first **supplies collateral** and can then borrow up to the market's `maxLtv` of that collateral's USD value (for example 75% for USDC on Aave V3 Base: supply \$100, borrow up to \$75). Same-asset positions are allowed: supply USDC, borrow USDC.

There is no term and no repayment schedule. Debt accrues interest continuously, and the position stays open until the user repays (`repay`, or `repayAll: true` to clear it) and withdraws. The only enforcement is **liquidation**: each position has a `healthFactor` (collateral value × `liquidationThreshold` ÷ debt). While it stays above `1` nothing happens; if accruing interest or a drop in the collateral's price pushes it below `1`, anyone can repay part of the debt and take the equivalent collateral plus a bonus (`liquidationPenalty`, typically 5-7.5%). Liquidations are partial, so the user keeps the remaining collateral. With stablecoin collateral this takes years of interest; with volatile collateral it can happen within hours of a price move.

<Note>
  Every `POST /actions` response includes `metadata.predictedHealthFactor` and `metadata.predictedLtv`. Show them before the user signs, and treat a predicted health factor near `1` as a hard stop in your UI.
</Note>

### Why offer it

* **Liquidity without selling.** Users who hold ETH, BTC or a yield-bearing token can borrow stablecoins against it to spend or invest without a taxable sale and without giving up upside, the on-chain equivalent of a margin loan or a securities-backed line of credit.
* **Keeps balances in your product.** Without it, a user who wants leverage or liquidity withdraws to a DeFi front-end. With it, collateral and debt live in the wallet you already manage, and you can add your own spread or origination fee (markets expose `originationFeeBps` / `feeWrapperAddress`).
* **Same integration as earning.** Yield.xyz's lending markets are the other side of the yield opportunities you may already offer; it is one API key, one dashboard toggle and one set of Portal endpoints.

## Steps to enable borrowing

### 1. Enable lending markets in Yield.xyz

* Create or access your Yield.xyz account [here](https://dashboard.yield.xyz/sign-up/register-interest?referred_by=portal).
* In the Yield.xyz dashboard, enable the lending markets you want to offer (for example Aave V3 on Base). Only enabled markets are returned by `GET /markets` by default; pass `scope=all` to browse every market Yield.xyz supports.
* Generate an API key per Portal environment if you have not already (`Development` and `Production`). The same key is used for Yield.xyz's Yield and Borrow APIs.

### 2. Enable the Yield.xyz integration in Portal

1. Open the [Portal Dashboard](https://app.portalhq.io).
2. Navigate to the `Integrations` page and find `Yield.xyz` under `Yield`. It is one integration that covers both yield and lending & borrowing.
3. Add it and paste your Yield.xyz API key for the selected Portal environment, then save.

Portal validates the key against Yield.xyz when you save it. Once saved, Portal proxies your SDK/API calls to Yield.xyz Borrow using this key from Portal's servers.

<Warning>
  Integrations are environment-scoped. Repeat these steps for each Portal environment (for example Development and Production).
</Warning>

<Note>
  Yield.xyz Borrow integrations (Aave V3, Morpho Blue, SparkLend, Lista) are live on mainnets only; there are no Sepolia or other EVM testnet markets. Test with small amounts on an inexpensive chain such as Base.
</Note>

## Endpoints

All endpoints live under `https://api.portalhq.io/api/v3/clients/me/integrations/yield-xyz-borrow` and accept a Client API Key or Client Session Token as a bearer token.

| Method | Path                                   | What it does                                                                                                                            |
| ------ | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `GET`  | `/integrations`                        | List lending/borrowing integrations (Aave V3, Morpho Blue, SparkLend, Lista) with supported networks and actions                        |
| `GET`  | `/integrations/{integrationId}`        | Details for one integration, including the argument schema for each action                                                              |
| `GET`  | `/markets`                             | Paginated lending markets with rates, LTVs, liquidation thresholds and liquidity                                                        |
| `GET`  | `/markets/{marketId}`                  | One market                                                                                                                              |
| `GET`  | `/positions`                           | Supply and debt balances, health factor and LTV for an address on an integration + network                                              |
| `GET`  | `/positions/liquidations`              | Paginated liquidation history for an address (Morpho Blue integrations)                                                                 |
| `POST` | `/actions`                             | Build unsigned transaction(s) for `supply`, `borrow`, `repay`, `withdraw`, `enableCollateral`, `disableCollateral` or `supplyAndBorrow` |
| `GET`  | `/actions`                             | Paginated actions for an address                                                                                                        |
| `GET`  | `/actions/{id}`                        | One action with its transactions and step progress                                                                                      |
| `POST` | `/actions/{id}/step`                   | Next transaction(s) of a multi-step action (when `hasNextStep` is `true`)                                                               |
| `POST` | `/transactions/{transactionId}/submit` | Submit a signed payload for Yield.xyz to broadcast, or report a transaction hash you broadcast yourself                                 |
| `GET`  | `/health`                              | Yield.xyz Borrow API health                                                                                                             |

Every success response is wrapped as `{ "data": ... }`.

### Typical flow

1. `GET /integrations` and `GET /markets?integrationId=aave-borrow&network=eip155:8453` to discover what your user can do.
2. `POST /actions` with the wallet address, the action and its `args` (always includes `marketId`, copied exactly as `GET /markets` returned it; Aave `supply`/`withdraw` also need `tokenAddress`). The response contains one or more `transactions` with a `signablePayload`.
3. Sign each transaction with the Portal SDK or Enclave MPC API, then `POST /transactions/{transactionId}/submit` with the `signedPayload` (or the `transactionHash` if you broadcast it yourself).
4. If the action has `hasNextStep: true`, wait for confirmation and call `POST /actions/{id}/step` for the next transaction(s).
5. `GET /positions` to show balances, health factor and available borrow.

```bash theme={null}
# 1. Build a supply transaction
curl --request POST \
  --url 'https://api.portalhq.io/api/v3/clients/me/integrations/yield-xyz-borrow/actions' \
  --header 'Authorization: Bearer [clientApiKey|clientSessionToken]' \
  --header 'Content-Type: application/json' \
  --data '{
    "integrationId": "aave-borrow",
    "action": "supply",
    "address": "0x1234...",
    "args": {
      "marketId": "aave-borrow-base-0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount": "100"
    }
  }'

# 2. Read the position back
curl --request GET \
  --url 'https://api.portalhq.io/api/v3/clients/me/integrations/yield-xyz-borrow/positions?integrationId=aave-borrow&network=eip155:8453&address=0x1234...' \
  --header 'Authorization: Bearer [clientApiKey|clientSessionToken]'
```

## Chain identifiers

Portal uses [CAIP-2 chain ids](/resources/chain-id-formatting) everywhere. Pass `network` as CAIP-2 (for example `eip155:1`, `eip155:8453`, `eip155:42161`) and Portal translates it to the Yield.xyz network name; `network` values in responses are translated back to CAIP-2. Requests for a chain Portal does not support are rejected with a `400` before they reach Yield.xyz.

Vendor discovery responses (for example an integration's `networks` list) can include chains Portal does not support; those keep the Yield.xyz network name so you can still recognize them.

## Errors

Yield.xyz Borrow errors are returned as Portal errors:

* `400`: invalid request (the message names the field), an unsupported chain id, a request Yield.xyz rejected (its message is passed through), or a Yield.xyz API key that is missing or was rejected
* `404`: unknown market, integration, action or transaction id
* `429`: Yield.xyz rate limit hit; back off and retry
* `503`: Yield.xyz is unreachable or failed upstream
* `500` with `id: INTEGRATION_RESPONSE_SCHEMA_DRIFT`: Yield.xyz changed a response shape and Portal did not forward it. Treat it as a temporary outage of that feature; see [Error codes](/resources/error-codes)

Response enumerations (action and transaction statuses, action types) may gain values over time; treat values you do not recognize as opaque rather than failing.

## Guides

* [Lend and borrow with Yield.xyz](/apis/enclave-mpc/guide/yield-xyz-borrow) using the Enclave MPC API

## API reference

<Card title="Yield.xyz Borrow API Reference" icon="arrow-right" href="/api-reference/yieldxyz-borrow/get-positions">
  Open the interactive Yield.xyz Borrow endpoints reference.
</Card>

<Tip>
  Need some advice on legal disclaimers when offering borrowing? Check out [Yield.xyz's disclaimer guidelines here](https://stakekit.notion.site/Yield-Disclaimer-Index-2a35318e934e806f863fecea64be38a8).
</Tip>