Skip to main content

Collateral ⇄ debt optimizer

GET 
/v1/data/lending/pairs/optimize

Filter pairs by either or both sides, then optionally compute the opposite-side amount per row.

Asset selection​

collaterals / debts are reinterpreted by chain mode:

  • Single chain (chainId): values are token addresses.
  • Multi-chain or no chain: values are asset groups.

Use collateralGroups / debtGroups to force group semantics in any chain mode. Group params and address params on the same side are OR'd.

The native asset, and why you usually want groups​

The native asset is spelled as the zero address in every 1delta data payload. 0xEeee…EEeE is an encoding-layer sentinel — it is accepted on action inputs and normalised away, but it is never served here and never matches an address filter, so a client filtering by it silently gets zero rows.

Native and wrapped-native markets are different rows (0x0 on Fluid’s ETH vaults, 0xc02a… on Aave WETH) but share one assetGroup (ETH). Selecting by group therefore returns both — which is what you want whenever the two are interchangeable for your purpose (a migrate bridges them by wrapping, a leverage loop can open on either). It also removes any need for a per-chain wrapped-native address table in the client. Each asset also carries props.isNative + props.wrapped (native rows) and props.wnative (wrapped rows) if you need to tell them apart after the fact.

Amount params​

The collateral and debt sides are independent — supply an amount on either side, both, or neither:

  • collateralAmount (token units; requires exactly one collateral asset)
  • collateralAmountUsd (USD; multi-asset OK)
  • debtAmount (token units; requires exactly one debt asset)
  • debtAmountUsd (USD; multi-asset OK)

A collateral input adds maxDebtAmount + maxDebtAmountUsd to each row; a debt input adds minCollateralAmount + minCollateralAmountUsd. Supplying both a collateral and a debt amount returns both column pairs. Within a single side the token-unit and *Usd forms are mutually exclusive (400 otherwise). Un-openable pairs are dropped by default on BOTH legs (includeIlliquid=true keeps them). Unconditionally: a collateral leg with no remaining supply capacity (depositableLong <= 0 — a full or deliberately zeroed supply cap, where the market returns 0 for a max-deposit query). Additionally, when an amount is supplied: a debt leg whose borrow liquidity cannot fund the resulting debt, and a collateral leg whose capacity cannot absorb the required collateral. With no amount supplied, a small-but-real capacity is a real (smaller) opportunity and stays listed; depositableLong: null means uncapped and always passes.

Depth-aware APR​

Whenever an amount is supplied, each row also carries the EFFECTIVE APR at the computed notional: borrowAprAtAmount, depositAprAtAmount, netAprAtAmount. Each is the headline effective rate (depositAprLong / borrowAprShort, which fold in intrinsic yield + rewards) with only its ORGANIC (IRM) component re-priced at the utilization the position moves the pool to — intrinsic + rewards are size-invariant. So a curve lender that borrows near 0% at 0 notional prices materially higher at a real size, and netAprAtAmount is comparable to aprTotal but at the position's actual size/leverage. Pass depth=true to additionally receive the raw borrowDepthShort/supplyDepthLong grids.

Plain-text reference — GET /v1/data/lending/pairs/optimize

Parameters

ParameterInTypeRequiredDescription
chainIdquerystringnoSingle chain ID. When set, asset filters operate on token addresses. See the ChainId schema for the full set of supported chains.
chainIdsquerystringnoCSV of chain IDs. When two or more, asset filters operate on asset groups. See the ChainId schema for the full set of supported chains.
lenderquerystringnoSingle lender key See the LenderId schema for the full set of accepted values.
lendersquerystringnoCSV of lender keys (prefix-expanded) See the LenderId schema for the full set of accepted values.
excludeLendersquerystringnoCSV of lender keys to exclude (prefix-expanded)
collateralsquerystringnoCSV of long-side filters. Token addresses (single chain) or asset groups (multi/no chain).
debtsquerystringnoCSV of short-side filters. Same dual semantics as collaterals.
collateralGroupsquerystringnoCSV of long-side asset groups (works in any chain mode).
debtGroupsquerystringnoCSV of short-side asset groups (works in any chain mode).
collateralTagsquerystringnoCSV of property flags the collateral (long) asset must carry, e.g. eth, btc, native, wnative, stablecoin, savings, lst, lrt, pendle, rwa. AND-ed with any collaterals/collateralGroups selection (narrows). Denomination flags (eth/btc) cover canonical base tokens only, not LST/derivative wrappers.
collateralTagsModequeryany, allnoHow to match multiple collateralTags: any (has at least one) or all (has every one).
debtTagsquerystringnoCSV of property flags the debt (short) asset must carry (e.g. eth, btc, native, wnative, stablecoin, savings, lst, lrt, pendle, rwa). Same semantics as collateralTags. Example: collateralTags=lst&debtTags=wnative for leveraged staking.
debtTagsModequeryany, allnoHow to match multiple debtTags: any or all.
includeExpiredquerybooleannoInclude pairs whose collateral or debt is an expired Pendle PT. Excluded by default (judged live off props.pendle.expiry/expired).
collateralAmountquerynumbernoToken-unit collateral amount. Requires exactly one collateral asset.
collateralAmountUsdquerynumbernoUSD collateral amount. Multi-asset selections OK.
debtAmountquerynumbernoToken-unit debt amount. Requires exactly one debt asset.
debtAmountUsdquerynumbernoUSD debt amount. Multi-asset selections OK.
depthquerybooleannoWhen true, also return the raw borrowDepthShort/supplyDepthLong rate-at-depth grids. The *AtAmount depth-aware scalars are returned whenever an amount is supplied, regardless of this flag.
includeIlliquidquerybooleannoBy default the optimizer drops collateral legs with no remaining supply capacity, and — when an amount is supplied — pairs whose borrow liquidity cannot fund the resulting debt or whose collateral capacity cannot absorb the required collateral. Set true to keep such (un-openable) pairs.
minAprquerynumbernoMinimum total APR
maxAprquerynumbernoMaximum total APR
minLeveragequerynumbernoMinimum leverage
minDepositAprquerynumbernoMin deposit APR including intrinsic yield (long side)
maxBorrowRatequerynumbernoMax borrow rate including intrinsic yield (short side)
minLtvquerynumbernoMinimum LTV (0-1)
maxUtilizationLongquerynumbernoMax collateral-side utilization (0-1)
maxUtilizationShortquerynumbernoMax debt-side utilization (0-1)
minLiquidityUsdLongquerynumbernoMin collateral-side liquidity USD. This is withdrawable CASH in the market, NOT deposit capacity — capacity is gated separately (see includeIlliquid).
minBorrowLiquidityUsdquerynumbernoMin debt-side borrow liquidity USD
minDepositsUsdLongquerynumbernoMin collateral-side deposits USD
minDebtUsdShortquerynumbernoMin debt-side total debt USD
maxRiskScorequerynumbernoBackwards-compat alias for maxConfigRiskScore
maxConfigRiskScorequerynumbernoMax config risk score
maxTokenRiskScorequerynumbernoMax token risk score
maxChainRiskScorequerynumbernoMax chain risk score
maxLenderRiskScorequerynumbernoMax lender risk score
startqueryintegernoPagination offset
countqueryintegernoPage size (max 100)
sortByqueryaprTotal, aprBase, maxLeverage, ltv, depositAprLong, borrowAprShort, … (15 values)noSort field
sortDirqueryASC, DESCnoSort direction

Response 200

FieldTypeDescription
successTrue
dataobject
data.chainIdsstring[]EVM chain ids, as decimal strings. See the ChainId schema.
data.collateralsstring[]
data.debtsstring[]
data.collateralAmountnumber
data.collateralAmountUsdnumber
data.debtAmountnumber
data.debtAmountUsdnumber
data.startinteger
data.countintegerNumber of entries in items.
data.itemsobject[]The result set for this response.
data.items[].chainIdstringEVM chain id, as a decimal string. See the ChainId schema.
data.items[].lenderstringProtocol identifier. See the LenderId schema.
data.items[].fixedTermobjectFixed-term descriptor for this pair's lender, joined by lender key. Absent on variable-rate lenders. For Term Finance (model: "term"), gate the borrow/loop CTA on fixedTerm.auction.canBorrow: origination only happens inside scheduled sealed-bid auction rounds and most repos sit between rounds, so a pair can carry a maturity, an LTV and a rate and still be impossible to borrow. Note also that aprBase/aprTotal on such a pair are computed against a variableBorrowRate of 0 and therefore read as an enormous leveraged yield with a free debt leg — show them as indicative, not obtainable, whenever canBorrow is false.
data.items[].marketLongUidstringMarket UID of the collateral side
data.items[].marketShortUidstringMarket UID of the debt side
data.items[].marketNameLongstringDisplay name of the collateral market/vault (e.g. the Euler eVault name). Disambiguates rows that share the collateral/debt token symbols and lender.
data.items[].marketNameShortstringDisplay name of the debt market/vault. For Euler this is the controller (debt) eVault — the primary way to tell otherwise-identical WETH→USDC rows apart.
data.items[].curatorNameLongstringCurator/brand of the collateral market (Euler: resolved from the vault governor). Null for lenders without a curator, or until the curator registry is seeded. Render as "curatorName + symbol", falling back to marketNameLong.
data.items[].curatorNameShortstringCurator/brand of the debt (controller) market. Same semantics as curatorNameLong.
data.items[].assetLongstring
data.items[].assetShortstring
data.items[].assetGroupLongstring
data.items[].assetGroupShortstring
data.items[].symbolLongstringCollateral token symbol
data.items[].nameLongstringCollateral token name
data.items[].symbolShortstringDebt token symbol
data.items[].nameShortstringDebt token name
data.items[].aprBasenumberLeverage-weighted net APR % EXCLUDING rewards — the SUSTAINABLE rate (reward incentives are typically transient).
data.items[].aprTotalnumberLeverage-weighted net APR % INCLUDING rewards. The reward contribution is aprTotal − aprBase.
data.items[].maxLeveragenumberHighest leverage multiple reachable in this market.
data.items[].ltvnumberLoan-to-value ratio, as a fraction between 0 and 1.
data.items[].depositAprLongnumberEffective deposit APR (depositRate + intrinsicYield)
data.items[].borrowAprShortnumberEffective borrow APR % (borrowRate + intrinsicYield − rewards, plus any 1y-amortized origination fee — see originationFeeShort). For Liquity-family CDPs the amortized origination fee is the whole borrow cost (variable rate is 0).
data.items[].originationFeeShortnumberOne-time origination / mint fee on the debt side, PERCENT (Liquity-family CDPs: River, Felix, Nerite, Ebisu, Soneta, USDAf, Liquity). NOT an APR — it is already folded (1y-amortized) into borrowAprShort / aprTotal, and surfaced raw so consumers can re-amortize over a different holding horizon. Null/absent for markets without one.
data.items[].totalDepositsUsdLongnumber
data.items[].totalDepositsUsdShortnumber
data.items[].totalDebtUsdLongnumber
data.items[].totalDebtUsdShortnumber

Example response

{
  "success": true,
  "data": {
    "chainIds": [
      "1"
    ],
    "collaterals": [
      "string"
    ],
    "debts": [
      "string"
    ],
    "collateralAmount": 1.0,
    "collateralAmountUsd": 1.0,
    "debtAmount": 1.0,
    "debtAmountUsd": 1.0,
    "start": 1,
    "count": 1,
    "items": [
      {
        "chainId": "1",
        "lender": "AAVE_V3",
        "fixedTerm": {
          "model": "term",
          "maturity": 1,
          "fees": {},
          "earlyRepay": {},
          "provider": {},
          "auction": {
            "status": "open",
            "canBorrow": true,
            "canLend": true,
            "secondsUntilClose": 263000,
            "implications": [
              "string"
            ],
            "id": "string",
            "startTime": 1,
            "revealTime": 1,
            "endTime": 1,
            "minBorrowAmount": "1000000000",
            "minLendAmount": "1000000000"
          }
        },
        "marketLongUid": "string",
        "marketShortUid": "string",
        "marketNameLong": "string",
        "marketNameShort": "string",
        "curatorNameLong": "string",
        "curatorNameShort": "string",
        "assetLong": "string",
        "assetShort": "string",
        "assetGroupLong": "string",
        "assetGroupShort": "string",
        "symbolLong": "string",
        "nameLong": "string",
        "symbolShort": "string",
        "nameShort": "string",
        "aprBase": 1.0,
        "aprTotal": 1.0,
        "maxLeverage": 1.0,
        "ltv": 1.0,
        "depositAprLong": 1.0,
        "borrowAprShort": 1.0,
        "originationFeeShort": 1.0,
        "totalDepositsUsdLong": 1.0,
        "totalDepositsUsdShort": 1.0,
        "totalDebtUsdLong": 1.0,
        "totalDebtUsdShort": 1.0,
        "totalLiquidityUsdLong": 1.0,
        "totalLiquidityUsdShort": 1.0,
        "borrowLiquidityShort": 1.0,
        "utilizationLong": 1.0,
        "utilizationShort": 1.0,
        "maxDebtAmount": 1.0,
        "maxDebtAmountUsd": 1.0,
        "minCollateralAmount": 1.0,
        "minCollateralAmountUsd": 1.0,
        "borrowAprAtAmount": 1.0,
        "depositAprAtAmount": 1.0,
        "netAprAtAmount": 1.0,
        "netAprAtAmountBase": 1.0,
        "borrowDepthShort": {},
        "supplyDepthLong": {},
        "risk": {
          "maxTokenScore": 1,
          "breakdown": [
            {
              "category": "lender",
              "score": 1,
              "label": "low",
              "curatorIds": [
                "string"
              ]
            }
          ]
        }
      }
    ]
  }
}

Request​

Responses​

Optimizer pairs