Subgraph Reference
The Graph is a decentralized protocol for indexing and querying data from blockchains. Anyone can build and publish open APIs, called subgraphs, making data easily accessible in a decentralized and reliable way. Subgraphs make it possible for anyone to query data that would otherwise be difficult to directly query on-chain. Each subgraph pays attention to events of a project’s contracts and maps that event data to data that The Graph stores in its database. Learn more about The Graph here.
GraphQL is the underlying query language utilized in The Graph. GraphQL is especially useful for calls requiring lots of information where instead of making multiple API calls one only needs to do one subgraph call to get all of the information needed. Learn more about GraphQL here.
Version | Network | Subgraph address |
|---|---|---|
Notional v2 | Mainnet | |
Notional v2 | Kovan | |
Notional v2 | Goerli | |
Notional v1 | Mainnet | |
Notional v1 | Kovan |
Version | Repository |
|---|---|
Notional v2 | |
Notional v1 |
One can easily build subgraph queries using The Graph’s playground (see links above). The playground works as follows:
- Build your query by modifying the example query on the left side of the screen. You can always refer to the subgraph’s schema on the right side of your screen to explore the subgraph’s data and structure.
- Execute the query by pressing the play button which will display the results in the middle portion of the screen.
- Most variables in Notional’s subgraph are 8 decimals (10^8). This includes the following variables: depositShares, balances, portfolio assets, asset Cash, fCash, TVL and many more.
- Rates variable are all 9 decimals (10^9). This includes the following variables: lastImpliedRates, oracleRates, totalFeeBasisPoints, fCashHaircutBasisPoints, annualizedAnchorRates, leverageThresholds, proportions, settlementPenaltyRateBasisPoints etc.
- When querying a specific account id or set of account ids, they must be in lower case format. Each results 'page' returns 100 entries by default. This can be increased to a maximum of 1000 entries per page by specifying (first:1000, skip:0). The skip variable can be used to iterate through results ex: (first:1000, skip:1000).
- Variables that are labeled as assetCash can be yield baring assets instruments in the underlying currency (ex: cTokens). As an example USDC cash assets in Notional are cUSDC tokens. In order to get the value of cash asset in the underlying currency (ex: convert cUSDC to USDC) one needs to use the historical asset exchange rates (see query example below).
- Notional uses currency ids to identify the different currencies in its system. Here is a list of the underlying currency symbols by currency ids:
- Currency id #1 = ETH
- Currency id #2 = DAI
- Currency id #3 = USDC
- Currency id #4 = WBTC
- Market Indexes identify the tenor of active markets using a predefined tenor cadence:
- 3 month (market index = 1)
- 6 month (market index = 2)
- 1 year (market index = 3)
- 2 year (market index = 4)
- 5 year (market index = 5)
- 10 year (market index = 6)
- 20 year (market index = 7)
As an example, a market index of 1 would be a 3 Month fCash market and a market with an index of 3 would be a 1 Year fCash market.
To run these queries through python one can use the following script and modify the url to the appropriate endpoint and modify the GQL query:
from gql import gql, Client from gql.transport.requests
import RequestsHTTPTransport
#Connect with theGraph
sample_transport = RequestsHTTPTransport( url="https://api.thegraph.com/subgraphs/name/notional-finance/mainnet-v2", # change to the appropriate endpoint
verify=True, retries=10, ) client = Client( transport=sample_transport )
#Update the GQL query
query = gql('''
{
trades(first: 100, skip: 0){
id
timestamp
maturity
tradeType
netfCash
netUnderlyingCash
}
}''')
response = client.execute(query)
Here are a few example queries to play with in the subgraph playgrounds.
To get a list of all account addresses that used Notional:
{
accounts(first:1000, skip:0){
id
}
}
To get historical borrow and lend fCash trades:
{
trades(first: 1000, skip:0){
id
timestamp
tradeType
maturity
netfCash
netUnderlyingCash
currency{underlyingSymbol}
market{marketIndex}
account{id}
}
}
To get the last implied interest rate and oracle rate of different markets:
{
markets{
lastImpliedRate
oracleRate
currency{underlyingSymbol}
marketIndex
maturity
}
}
To get an account portfolio assets and balances. As mentioned above the account id has to be lower case:
{
accounts(where:{id:"0x193991827e291599a262e7fa7d212ff1ae31d110"}){
id
balances{
currency{underlyingSymbol}
assetCashBalance
nTokenBalance
}
portfolio{
currency{underlyingSymbol}
maturity
assetType
notional
}
}
}
To get nToken account portfolios:
{
nTokens{
name
account{
id
balances{
currency{underlyingSymbol}
assetCashBalance
nTokenBalance
}
portfolio{
currency{underlyingSymbol}
maturity
assetType
notional
}
}
}
}
To get nToken governance parameters where the depositShares and incentiveEmissionRate are 8 decimals and rates (annualizedAnchorRates, proportions, leverageThresholds) are 9 decimals:
{
nTokens{
name
depositShares
pvHaircutPercentage
liquidationHaircutPercentage
leverageThresholds
annualizedAnchorRates
proportions
incentiveEmissionRate
}
}
To get governance parameters where fCashHaircutBasisPoints, debtBufferBasisPoints, liquidationfCashHaircutBasisPoints, liquidationDebtBufferBasisPoints, settlementPenaltyRateBasisPoints and totalFeeBasisPoints variables are 9 decimals:
{
cashGroups{
rateScalars
rateOracleTimeWindowSeconds
totalFeeBasisPoints
reserveFeeSharePercent
fCashHaircutBasisPoints
liquidationfCashHaircutBasisPoints
debtBufferBasisPoints
liquidationDebtBufferBasisPoints
settlementPenaltyRateBasisPoints
liquidityTokenHaircutsPercent
}
}
To get the currency underlying symbol per currency id:
{
currencies(where:{id:1}){
underlyingSymbol
}
}
To get Notional’s total TVL in USD and the TVL breakdown per currency:
{
tvlHistoricalDatas(first:1, orderBy: timestamp, orderDirection:desc){
timestamp
usdTotal
perCurrencyTvl{
currency{underlyingSymbol}
usdValue
}
}
}
To get the latest asset exchange rate (ex: the cUSDC to USDC exchange rate):
{
assetExchangeRateHistoricalDatas(first:1, orderBy:timestamp, orderDirection:desc){
timestamp
value
currency{underlyingSymbol}
}
}
To get the latest ETH exchange rate (ex: the USDC to ETH exchange rate):
{
ethExchangeRateHistoricalDatas(first:1, orderBy:timestamp, orderDirection:desc){
id
timestamp
value
currency{underlyingSymbol}
}
}
To get historical Notional liquidations. The netLocalFromLiquidator is the amount of cash asset (ex: cTokens) the liquidator paid in local currency to buy the collateral of fCash currency. If the collateralOrFcashCurrency is null, the collateral currency is the local currency.
{
liquidations(first:100, skip:0){
timestamp
type
account{id}
liquidator{id}
localCurrency{underlyingSymbol}
collateralOrFcashCurrency{underlyingSymbol}
netLocalFromLiquidator
netNTokenTransfer
netCollateralTransfer
fCashNotionalTransfer
fCashMaturities
}
}
Last modified 7mo ago