Yield API

The Definitive API lets others build on Definitive’s yield and execution infrastructure. The API streamlines and standardizes multiple DeFi protocols within a single unified strategy interface. Today, with just a few lines of code, wallets, custodians, and aggregators can easily launch a DeFi Earn product for their users with Definitive’s powerful infra as foundational bedrock!

Checkout the API Docs below or view the OpenAI spec at https://api.definitive.fi/docs#/. Reach out to [e-mail] if you'd like to integrate and we can set you up with an API key.

Check out the detailed integration guide here.

Get vaults

get

Query parameters

chainstring · enumOptional

Query vaults by chain

Possible values:

protocolstring · enumOptional

Query vaults by protocol

Possible values:

user_addressstringOptional

Show vault NAV for a user

organization_onlybooleanOptional

Only show vaults in org (not community vaults)

Responses

get

HTTPcURLJavaScriptPython

GET /v1/vaults HTTP/1.1
Host: api.definitive.fi
Accept: */*

200

OK

{
  "vaults": [
    {
      "address": "text",
      "adminAddress": "text",
      "alias": "text",
      "apy": "text",
      "apyBreakdown": {
        "apr30d": "text",
        "apr7d": "text",
        "apravg": "text",
        "current": "text"
      },
      "baseCurrency": "text",
      "chain": "ethereum",
      "chainId": "text",
      "depositAssets": [
        {
          "address": "text",
          "chainId": "text",
          "decimals": 1,
          "id": "text",
          "image": "text",
          "name": "text",
          "ticker": "text"
        }
      ],
      "id": "text",
      "llsd": {
        "debtAsset": {
          "address": "text",
          "chainId": "text",
          "decimals": 1,
          "id": "text",
          "image": "text",
          "name": "text",
          "ticker": "text"
        },
        "debtAssetBorrowUtilization": "text",
        "flashloanProtocol": "stargate",
        "lendingProtocol": "stargate",
        "rewardAssets": [
          {
            "address": "text",
            "chainId": "text",
            "decimals": 1,
            "id": "text",
            "image": "text",
            "name": "text",
            "ticker": "text"
          }
        ],
        "stakingProtocol": "stargate",
        "yieldAsset": {
          "address": "text",
          "chainId": "text",
          "decimals": 1,
          "id": "text",
          "image": "text",
          "name": "text",
          "ticker": "text"
        },
        "yieldAssetAPR": "text",
        "yieldAssetSupplyUtilization": "text"
      },
      "lpStaking": {
        "rewardAssets": [
          {
            "address": "text",
            "chainId": "text",
            "decimals": 1,
            "id": "text",
            "image": "text",
            "name": "text",
            "ticker": "text"
          }
        ]
      },
      "name": "text",
      "protocol": "stargate",
      "protocolOverview": "text",
      "protocolTVL": "text",
      "safeRestingAssets": [
        {
          "address": "text",
          "chainId": "text",
          "decimals": 1,
          "id": "text",
          "image": "text",
          "name": "text",
          "ticker": "text"
        }
      ],
      "status": "ACTIVE",
      "strategy": "LPSTAKING",
      "strategyAddress": "text",
      "strategyOverview": "text",
      "tags": [
        "text"
      ],
      "totalReturn": "text",
      "tvl": "text",
      "userNAV": "text",
      "withdrawAssets": [
        {
          "address": "text",
          "chainId": "text",
          "decimals": 1,
          "id": "text",
          "image": "text",
          "name": "text",
          "ticker": "text"
        }
      ]
    }
  ]
}

Get rates

get

Get rates against a specified quote ticker

Query parameters

base_tickersstringRequired

comma separated list of base tickers

quote_tickerstringRequired

quote ticker (ex. USD)

Responses

get

HTTPcURLJavaScriptPython

GET /v1/rates HTTP/1.1
Host: api.definitive.fi
Accept: */*

200

OK

{
  "quote": "text",
  "rates": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Get vault by ID

get

Path parameters

idstringRequired

vault ID

Query parameters

user_addressstringOptional

show vault NAV for a user

Responses

get

HTTPcURLJavaScriptPython

GET /v1/vaults/{id} HTTP/1.1
Host: api.definitive.fi
Accept: */*

200

OK

{
  "vault": {
    "address": "text",
    "adminAddress": "text",
    "alias": "text",
    "apy": "text",
    "apyBreakdown": {
      "apr30d": "text",
      "apr7d": "text",
      "apravg": "text",
      "current": "text"
    },
    "baseCurrency": "text",
    "chain": "ethereum",
    "chainId": "text",
    "depositAssets": [
      {
        "address": "text",
        "chainId": "text",
        "decimals": 1,
        "id": "text",
        "image": "text",
        "name": "text",
        "ticker": "text"
      }
    ],
    "id": "text",
    "llsd": {
      "debtAsset": {
        "address": "text",
        "chainId": "text",
        "decimals": 1,
        "id": "text",
        "image": "text",
        "name": "text",
        "ticker": "text"
      },
      "debtAssetBorrowUtilization": "text",
      "flashloanProtocol": "stargate",
      "lendingProtocol": "stargate",
      "rewardAssets": [
        {
          "address": "text",
          "chainId": "text",
          "decimals": 1,
          "id": "text",
          "image": "text",
          "name": "text",
          "ticker": "text"
        }
      ],
      "stakingProtocol": "stargate",
      "yieldAsset": {
        "address": "text",
        "chainId": "text",
        "decimals": 1,
        "id": "text",
        "image": "text",
        "name": "text",
        "ticker": "text"
      },
      "yieldAssetAPR": "text",
      "yieldAssetSupplyUtilization": "text"
    },
    "lpStaking": {
      "rewardAssets": [
        {
          "address": "text",
          "chainId": "text",
          "decimals": 1,
          "id": "text",
          "image": "text",
          "name": "text",
          "ticker": "text"
        }
      ]
    },
    "name": "text",
    "protocol": "stargate",
    "protocolOverview": "text",
    "protocolTVL": "text",
    "safeRestingAssets": [
      {
        "address": "text",
        "chainId": "text",
        "decimals": 1,
        "id": "text",
        "image": "text",
        "name": "text",
        "ticker": "text"
      }
    ],
    "status": "ACTIVE",
    "strategy": "LPSTAKING",
    "strategyAddress": "text",
    "strategyOverview": "text",
    "tags": [
      "text"
    ],
    "totalReturn": "text",
    "tvl": "text",
    "userNAV": "text",
    "withdrawAssets": [
      {
        "address": "text",
        "chainId": "text",
        "decimals": 1,
        "id": "text",
        "image": "text",
        "name": "text",
        "ticker": "text"
      }
    ]
  }
}

Request a deposit payload

post

Request a payload to sign and send to chain

Path parameters

idstringRequired

vault ID

addressstringRequired

user address

Body

disableValidationbooleanOptional

do not simulate the transaction

slippagestringOptional

Optional. Slippage tolerance when converting underlying to shares

Responses

post

HTTPcURLJavaScriptPython

POST /v1/vaults/{id}/deposit/{address} HTTP/1.1
Host: api.definitive.fi
Content-Type: application/json
Accept: */*
Content-Length: 96

{
  "depositAmounts": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "disableValidation": true,
  "slippage": "text"
}

200

OK

{
  "estimatedPriceImpact": "text",
  "payload": {
    "data": "text",
    "to": "text",
    "value": "text"
  }
}

Get historical APR

get

Get the historical APR for a vault

Path parameters

idstringRequired

vault ID

Query parameters

start_tsstringOptional

start timestamp

end_tsstringOptional

end timestamp

limitintegerOptional

max datapoints

pagination_tokenstringOptional

pagintation token

Responses

get

HTTPcURLJavaScriptPython

GET /v1/vaults/{id}/historical_apr HTTP/1.1
Host: api.definitive.fi
Accept: */*

200

OK

{
  "historicalApr": [
    {
      "apr": "text",
      "apr7d": "text",
      "maxAPR": "text",
      "minAPR": "text",
      "ts": "text"
    }
  ],
  "paginationToken": "text"
}

Get historical TVL

get

Get the historical TVL for a vault

Path parameters

idstringRequired

vault ID

Query parameters

start_tsstringOptional

start timestamp

end_tsstringOptional

end timestamp

pagination_tokenstringOptional

pagintation token

limitintegerOptional

max datapoints

Responses

get

HTTPcURLJavaScriptPython

GET /v1/vaults/{id}/historical_tvl HTTP/1.1
Host: api.definitive.fi
Accept: */*

200

OK

{
  "historicalTvl": [
    {
      "amount": {
        "address": "text",
        "amount": "text",
        "baseCurrency": {
          "amount": "text",
          "ticker": "text"
        },
        "chainId": "text",
        "decimals": 1,
        "id": "text",
        "image": "text",
        "name": "text",
        "notional": "text",
        "ticker": "text"
      },
      "ts": "text",
      "tvl": "text"
    }
  ],
  "paginationToken": "text"
}

Get vault monitors

get

Path parameters

idstringRequired

vault ID

Responses

get

HTTPcURLJavaScriptPython

GET /v1/vaults/{id}/monitors HTTP/1.1
Host: api.definitive.fi
Accept: */*

200

OK

{
  "emergencyState": {
    "active": true,
    "ts": "text",
    "unsafeAssets": [
      {
        "address": "text",
        "chainId": "text",
        "decimals": 1,
        "id": "text",
        "image": "text",
        "name": "text",
        "ticker": "text"
      }
    ]
  },
  "monitors": [
    {
      "base": "text",
      "description": "text",
      "lastStatus": {
        "max": "text",
        "min": "text",
        "target": "text",
        "ts": "text",
        "value": "text"
      },
      "max": "text",
      "min": "text",
      "quote": "text",
      "target": "text",
      "type": "relativeLiquidityMonitor"
    }
  ],
  "safeRestingAssets": [
    {
      "address": "text",
      "chainId": "text",
      "decimals": 1,
      "id": "text",
      "image": "text",
      "name": "text",
      "ticker": "text"
    }
  ]
}

Get vault monitor history

get

Get historical data for a vault monitor

Path parameters

idstringRequired

vault ID

typestring · enumRequired

monitor type

Possible values:

Query parameters

pairstringOptional

required if asset pair monitor

start_tsstringOptional

start timestamp

end_tsstringOptional

end timestamp

limitintegerOptional

max datapoints

pagination_tokenstringOptional

pagintation token

Responses

get

HTTPcURLJavaScriptPython

GET /v1/vaults/{id}/monitors/{type}/history HTTP/1.1
Host: api.definitive.fi
Accept: */*

200

OK

{
  "history": [
    {
      "max": "text",
      "min": "text",
      "target": "text",
      "ts": "text",
      "value": "text"
    }
  ],
  "paginationToken": "text"
}

Get vault balances by address

get

Path parameters

idstringRequired

vault ID

addressstringRequired

user address

Responses

get

HTTPcURLJavaScriptPython

GET /v1/vaults/{id}/position/{address} HTTP/1.1
Host: api.definitive.fi
Accept: */*

200

OK

{
  "balances": [
    {
      "address": "text",
      "amount": "text",
      "baseCurrency": {
        "amount": "text",
        "ticker": "text"
      },
      "chainId": "text",
      "decimals": 1,
      "id": "text",
      "image": "text",
      "name": "text",
      "notional": "text",
      "ticker": "text"
    }
  ],
  "deposits": [
    {
      "address": "text",
      "amount": "text",
      "baseCurrency": {
        "amount": "text",
        "ticker": "text"
      },
      "chainId": "text",
      "decimals": 1,
      "id": "text",
      "image": "text",
      "name": "text",
      "notional": "text",
      "ticker": "text"
    }
  ],
  "fees": {
    "address": "text",
    "amount": "text",
    "baseCurrency": {
      "amount": "text",
      "ticker": "text"
    },
    "chainId": "text",
    "decimals": 1,
    "id": "text",
    "image": "text",
    "name": "text",
    "notional": "text",
    "ticker": "text"
  },
  "llsd": {
    "collateral": [
      {
        "address": "text",
        "amount": "text",
        "baseCurrency": {
          "amount": "text",
          "ticker": "text"
        },
        "chainId": "text",
        "decimals": 1,
        "id": "text",
        "image": "text",
        "name": "text",
        "notional": "text",
        "ticker": "text"
      }
    ],
    "debt": [
      {
        "address": "text",
        "amount": "text",
        "baseCurrency": {
          "amount": "text",
          "ticker": "text"
        },
        "chainId": "text",
        "decimals": 1,
        "id": "text",
        "image": "text",
        "name": "text",
        "notional": "text",
        "ticker": "text"
      }
    ],
    "ltv": "text",
    "unclaimedRewards": [
      {
        "address": "text",
        "amount": "text",
        "baseCurrency": {
          "amount": "text",
          "ticker": "text"
        },
        "chainId": "text",
        "decimals": 1,
        "id": "text",
        "image": "text",
        "name": "text",
        "notional": "text",
        "ticker": "text"
      }
    ]
  },
  "lpStaking": {
    "claimedRewards": [
      {
        "address": "text",
        "amount": "text",
        "baseCurrency": {
          "amount": "text",
          "ticker": "text"
        },
        "chainId": "text",
        "decimals": 1,
        "id": "text",
        "image": "text",
        "name": "text",
        "notional": "text",
        "ticker": "text"
      }
    ],
    "lpToken": {
      "address": "text",
      "amount": "text",
      "baseCurrency": {
        "amount": "text",
        "ticker": "text"
      },
      "chainId": "text",
      "decimals": 1,
      "id": "text",
      "image": "text",
      "name": "text",
      "notional": "text",
      "ticker": "text"
    },
    "lpTokenRepresentation": [
      {
        "address": "text",
        "amount": "text",
        "baseCurrency": {
          "amount": "text",
          "ticker": "text"
        },
        "chainId": "text",
        "decimals": 1,
        "id": "text",
        "image": "text",
        "name": "text",
        "notional": "text",
        "ticker": "text"
      }
    ],
    "unclaimedRewards": [
      {
        "address": "text",
        "amount": "text",
        "baseCurrency": {
          "amount": "text",
          "ticker": "text"
        },
        "chainId": "text",
        "decimals": 1,
        "id": "text",
        "image": "text",
        "name": "text",
        "notional": "text",
        "ticker": "text"
      }
    ]
  },
  "nav": "text",
  "navBasis": {
    "amount": "text",
    "ticker": "text"
  },
  "shareConversions": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "totalReturn": {
    "address": "text",
    "amount": "text",
    "baseCurrency": {
      "amount": "text",
      "ticker": "text"
    },
    "chainId": "text",
    "decimals": 1,
    "id": "text",
    "image": "text",
    "name": "text",
    "notional": "text",
    "ticker": "text"
  },
  "withdrawals": [
    {
      "address": "text",
      "amount": "text",
      "baseCurrency": {
        "amount": "text",
        "ticker": "text"
      },
      "chainId": "text",
      "decimals": 1,
      "id": "text",
      "image": "text",
      "name": "text",
      "notional": "text",
      "ticker": "text"
    }
  ]
}

Get historical NAV

get

Get historical NAV of a vault for an address

Path parameters

idstringRequired

vault ID

addressstringRequired

user address

Query parameters

start_tsstringOptional

start timestamp

end_tsstringOptional

end timestamp

limitintegerOptional

max datapoints

pagination_tokenstringOptional

pagintation token

Responses

get

HTTPcURLJavaScriptPython

GET /v1/vaults/{id}/position/{address}/historical_nav HTTP/1.1
Host: api.definitive.fi
Accept: */*

200

OK

{
  "historicalNav": [
    {
      "amount": {
        "address": "text",
        "amount": "text",
        "baseCurrency": {
          "amount": "text",
          "ticker": "text"
        },
        "chainId": "text",
        "decimals": 1,
        "id": "text",
        "image": "text",
        "name": "text",
        "notional": "text",
        "ticker": "text"
      },
      "nav": "text",
      "totalReturn": {
        "address": "text",
        "amount": "text",
        "baseCurrency": {
          "amount": "text",
          "ticker": "text"
        },
        "chainId": "text",
        "decimals": 1,
        "id": "text",
        "image": "text",
        "name": "text",
        "notional": "text",
        "ticker": "text"
      },
      "ts": "text"
    }
  ],
  "paginationToken": "text"
}

Get transaction history

get

Get transaction history of a vault for an address

Path parameters

idstringRequired

vault ID

addressstringRequired

user address

Responses

get

HTTPcURLJavaScriptPython

GET /v1/vaults/{id}/position/{address}/transaction_history HTTP/1.1
Host: api.definitive.fi
Accept: */*

200

OK

{
  "transactions": [
    {
      "deposit": {
        "assets": "text",
        "shares": "text"
      },
      "depositUnderlying": {
        "amounts": [
          {
            "address": "text",
            "amount": "text",
            "baseCurrency": {
              "amount": "text",
              "ticker": "text"
            },
            "chainId": "text",
            "decimals": 1,
            "id": "text",
            "image": "text",
            "name": "text",
            "notional": "text",
            "ticker": "text"
          }
        ],
        "shares": "text"
      },
      "mint": {
        "amounts": [
          {
            "address": "text",
            "amount": "text",
            "baseCurrency": {
              "amount": "text",
              "ticker": "text"
            },
            "chainId": "text",
            "decimals": 1,
            "id": "text",
            "image": "text",
            "name": "text",
            "notional": "text",
            "ticker": "text"
          }
        ],
        "shares": "text"
      },
      "redeem": {
        "amounts": [
          {
            "address": "text",
            "amount": "text",
            "baseCurrency": {
              "amount": "text",
              "ticker": "text"
            },
            "chainId": "text",
            "decimals": 1,
            "id": "text",
            "image": "text",
            "name": "text",
            "notional": "text",
            "ticker": "text"
          }
        ],
        "shares": "text"
      },
      "rewardClaim": {
        "feeAmount": {
          "address": "text",
          "amount": "text",
          "baseCurrency": {
            "amount": "text",
            "ticker": "text"
          },
          "chainId": "text",
          "decimals": 1,
          "id": "text",
          "image": "text",
          "name": "text",
          "notional": "text",
          "ticker": "text"
        },
        "fromAmounts": [
          {
            "address": "text",
            "amount": "text",
            "baseCurrency": {
              "amount": "text",
              "ticker": "text"
            },
            "chainId": "text",
            "decimals": 1,
            "id": "text",
            "image": "text",
            "name": "text",
            "notional": "text",
            "ticker": "text"
          }
        ],
        "percentClaim": "text",
        "toAmount": {
          "address": "text",
          "amount": "text",
          "baseCurrency": {
            "amount": "text",
            "ticker": "text"
          },
          "chainId": "text",
          "decimals": 1,
          "id": "text",
          "image": "text",
          "name": "text",
          "notional": "text",
          "ticker": "text"
        }
      },
      "transactionId": "text",
      "transfer": {
        "amount": "text",
        "from": "text",
        "to": "text"
      },
      "ts": "text",
      "type": "DEPOSIT",
      "withdraw": {
        "assets": "text",
        "shares": "text"
      },
      "withdrawOneUnderlying": {
        "amount": {
          "address": "text",
          "amount": "text",
          "baseCurrency": {
            "amount": "text",
            "ticker": "text"
          },
          "chainId": "text",
          "decimals": 1,
          "id": "text",
          "image": "text",
          "name": "text",
          "notional": "text",
          "ticker": "text"
        },
        "shares": "text"
      },
      "withdrawUnderlying": {
        "amounts": [
          {
            "address": "text",
            "amount": "text",
            "baseCurrency": {
              "amount": "text",
              "ticker": "text"
            },
            "chainId": "text",
            "decimals": 1,
            "id": "text",
            "image": "text",
            "name": "text",
            "notional": "text",
            "ticker": "text"
          }
        ],
        "shares": "text"
      }
    }
  ]
}

Get addresses in vault

get

Get all address with funds deposited in the vault

Path parameters

idstringRequired

vault ID

Responses

get

HTTPcURLJavaScriptPython

GET /v1/vaults/{id}/users HTTP/1.1
Host: api.definitive.fi
Accept: */*

200

OK

{
  "addresses": [
    "text"
  ]
}

Request a withdrawal payload

post

Request a payload to sign and send to chain

Path parameters

idstringRequired

vault ID

addressstringRequired

user address

Body

additionalFeePctstringOptional

Optional. Specify additional withdrawal fee percentage.

slippagestringOptional

Optional. Slippage tolerance when converting underlying to shares

withdrawAmountstringRequired

Specify number of shares to withdraw.

withdrawOneAddressstringOptional

Optional. Specify if the request is for one underlying asset.

Responses

post

HTTPcURLJavaScriptPython

POST /v1/vaults/{id}/withdraw/{address} HTTP/1.1
Host: api.definitive.fi
Content-Type: application/json
Accept: */*
Content-Length: 97

{
  "additionalFeePct": "text",
  "slippage": "text",
  "withdrawAmount": "text",
  "withdrawOneAddress": "text"
}

200

OK

{
  "estimatedPriceImpact": "text",
  "payload": {
    "data": "text",
    "to": "text",
    "value": "text"
  }
}