Yield.xyz Borrow

Overview

Portal integrates with Yield.xyz Borrow 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.

Borrowing uses the same Yield.xyz API key and the same Portal integration as 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.

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.

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.

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

Open the Portal Dashboard.
Navigate to the Integrations page and find Yield.xyz under Yield. It is one integration that covers both yield and lending & borrowing.
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.

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

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.

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

GET /integrations and GET /markets?integrationId=aave-borrow&network=eip155:8453 to discover what your user can do.
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.
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).
If the action has hasNextStep: true, wait for confirmation and call POST /actions/{id}/step for the next transaction(s).
GET /positions to show balances, health factor and available borrow.

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

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 using the Enclave MPC API

API reference

Yield.xyz Borrow API Reference

Open the interactive Yield.xyz Borrow endpoints reference.

Need some advice on legal disclaimers when offering borrowing? Check out Yield.xyz’s disclaimer guidelines here.

Getting Started

SDKs

APIs

Integrations

Resources

Yield.xyz Borrow

Overview

How lending and borrowing works

Why offer it

Steps to enable borrowing

1. Enable lending markets in Yield.xyz

2. Enable the Yield.xyz integration in Portal

Endpoints

Typical flow

Chain identifiers

Errors

Guides

API reference

Yield.xyz Borrow API Reference

​Overview

​How lending and borrowing works

​Why offer it

​Steps to enable borrowing

​1. Enable lending markets in Yield.xyz

​2. Enable the Yield.xyz integration in Portal

​Endpoints

​Typical flow

​Chain identifiers

​Errors

​Guides

​API reference

Yield.xyz Borrow API Reference

Overview

How lending and borrowing works

Why offer it

Steps to enable borrowing

1. Enable lending markets in Yield.xyz

2. Enable the Yield.xyz integration in Portal

Endpoints

Typical flow

Chain identifiers

Errors

Guides

API reference