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

chainanyOptional

Query vaults by chain

protocolanyOptional

Query vaults by protocol

user_addressanyOptional

Show vault NAV for a user

organization_onlyanyOptional

Only show vaults in org (not community vaults)

Responses

application/json

objectOptional

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_tickersanyRequired

comma separated list of base tickers

quote_tickeranyRequired

quote ticker (ex. USD)

Responses

application/json

objectOptional

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

idanyRequired

vault ID

Query parameters

user_addressanyOptional

show vault NAV for a user

Responses

application/json

objectOptional

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

idanyRequired

vault ID

addressanyRequired

user address

Body

depositAmountsobjectOptional

A map of the underlying tokens being deposited as address:amount

disableValidationbooleanOptional

do not simulate the transaction

slippagestringOptional

Optional. Slippage tolerance when converting underlying to shares

Responses

application/json

objectOptional

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

idanyRequired

vault ID

Query parameters

start_tsanyOptional

start timestamp

end_tsanyOptional

end timestamp

limitanyOptional

max datapoints

pagination_tokenanyOptional

pagintation token

Responses

application/json

objectOptional

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

idanyRequired

vault ID

Query parameters

start_tsanyOptional

start timestamp

end_tsanyOptional

end timestamp

pagination_tokenanyOptional

pagintation token

limitanyOptional

max datapoints

Responses

application/json

objectOptional

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

idanyRequired

vault ID

Responses

application/json

objectOptional

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

idanyRequired

vault ID

typeanyRequired

monitor type

Query parameters

pairanyOptional

required if asset pair monitor

start_tsanyOptional

start timestamp

end_tsanyOptional

end timestamp

limitanyOptional

max datapoints

pagination_tokenanyOptional

pagintation token

Responses

application/json

objectOptional

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

idanyRequired

vault ID

addressanyRequired

user address

Responses

application/json

objectOptional

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

idanyRequired

vault ID

addressanyRequired

user address

Query parameters

start_tsanyOptional

start timestamp

end_tsanyOptional

end timestamp

limitanyOptional

max datapoints

pagination_tokenanyOptional

pagintation token

Responses

application/json

objectOptional

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

idanyRequired

vault ID

addressanyRequired

user address

Responses

application/json

objectOptional

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

idanyRequired

vault ID

Responses

application/json

objectOptional

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

idanyRequired

vault ID

addressanyRequired

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

application/json

objectOptional

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"
  }
}