INTRODUCTION

The FLUIDEFI® platform provides near real-time1 analytics, portfolio management, and alerting for thousands of decentralized financial (DeFi) digital assets. FLUIDEFI's analytics are calculated using the transaction logs on the Ethereum blockchain.

The FLUIDEFI RESTful API allows developers to:

1The term "near real-time" refers to the time delay introduced by 1) automated data processing and 2) network transmission between the occurrence of an event and the request of the processed data (the API call). The API responses include as_of_timestamp that specifies the UTC date/time that the API response was generated and last_processed which includes the UTC date/time the information was last calculated. FLUIDEFI uses ISO 8601 format for datetimes.

ACCESS TO THE FLUIDEFI API

Accessing the FLUIDEFI RESTful API requires:

  1. A username and password. This information is provided when enrolling for the FLUIDEFI services.
    NOTE: The API end-point URL for your account is provided when enrolling for the FLUIDEFI services. Do not use the example listed.
  2. Depending on your subscription level, the IP address(es) of your computer(s) making API requests may need to be white-listed with the FLUIDEFI network firewall. Please send an email with your username and the IP address(es) to be whitelisted to FLUIDEFI Support. Static IP addresses are recommended. Note: when using dynamic IP addresses, the FLUIDEFI firewall does not automatically update when your dynamic IP address changes.
All API requests must be made to your designated API URL using HTTPS protocol with TLS v1.3 or later via TCP/IP port 443. All FLUIDEFI servers use SSL certificates with sha256RSA signature algorithms issued by Sectigo RSA Domain Validation Secure Server CA.
 
It is important to note that some API calls can generate very long responses. Please review this documentation for performance recommendations.

FLUIDEFI SUPPORT

Your Service Level Agreement (SLA) is based on your subscription level.

FLUIDEFI'S LIQUIDITY POOL METRICS

Key Description
open_timestamp_utc Start date/time for information in this record. The first record will begin on this date
close_timestamp_utc End date/time for information in this record. The close of the last record is this date
total_period_return Total rate of return for a liquidity pool in the specified period
yield_on_lp_fees Return from fees in the specified period
price_change_ret Return from the change in price of the underlying tokens in the specified period
misc_return Return from fees earned from flashloans and incentives
hodl_return Return if tokens were held (not staked in a liquidity pool) in the specified period
fees_apy Return from fees in the specified period, annualized
total_apy Total rate of return for a liquidity pool in the specified period, annualized
token_0_fees_croi Cumulative return from fees earned in the form token 0
token_1_fees_croi Cumulative return from fees earned in the form token 1
misc_croi Cumulative total return on investment for misc (see above) in base_currency
total_croi Cumulative total return on investment in base_currency
fees_croi Cumulative return from fees in base_currency
price_change_croi Cumulative return from the change in underlying tokens' values, this includes impermanent loss
hodl_token_0_croi Cumulative total return for token 0's hodler
hodl_token_1_croi Cumulative total return for token 1's hodler
hodl_croi Cumulative total return for a hodler of both token 0 and token 1
token_0_fees_return Return from fees in the specified period for token 0
token_1_fees_return Return from fees in the specified period for token 1
accumulated_token_0_fees Amount of token 0 earned from the liquidity pool
accumulated_token_1_fees Amount of token 1 earned from the liquidity pool
open_lp_token_price Open Liquidity Pool Open Price in the specified period
close_lp_token_price Close Liquidity Pool Open Price in the specified period
impermanent_loss_level The percentage difference in portfolio value between staking tokens in an AMM and holding tokens in a wallet. Fees are not taken into account in this calculation
impermanent_loss_impact The percentage difference in ROI between staking tokens in an AMM and holding tokens in a wallet. Fees are not taken into account in this calculation
volume_0 Number of token 0's traded
volume_1 Number of token 1's traded
volume_0_base_curr Token 0's volume in base_currency (default is USD) in the specified time period
volume_1_base_curr Token 1's volume in base_currency (default is USD) in the specified time period
volume Volume in USD in the specified time period
transactions_period Number of transactions recorded during the time_period specified
num_swaps Number of swaps in the specified period
num_swaps_0 Number of swaps of token 0 in the specified period
num_swaps_1 Number of swaps of token 1 in the specified period
num_mints Number of mint events in the specified period
num_burns Number of burn events in the specified period
num_liquidity_events Total number of liquidity events in the specified period for this platform
open_reserve_0 Reserves of token 0 at the first transaction in time_period specified
open_reserve_1 Reserves of token 1 at the first transaction in time_period specified
close_reserve_0 Reserves of token 0 at the last transaction in time_period specified
close_reserve_1 Reserves of token 1 at the last transaction in time_period specified
open_reserve_0_base_curr Reserves of token 0 in base_currency (default is USD) at the first transaction in time_period specified
open_reserve_1_base_curr Reserves of token 1 in base_currency (default is USD) at the first transaction in time_period specified
close_reserve_0_base_curr Reserves of token 0 in base_currency (default is USD) at the last transaction in time_period specified
close_reserve_1_base_curr Reserves of token 1 in base_currency (default is USD) at the last transaction in time_period specified
open_poolsize Pool size in USD at the first transaction in time_period specified
close_poolsize Pool size in USD at the last transaction in time_period specified
poolsize Same as close_poolsize; Kept for backwards compatibility
open_price_0 Price of token 0 in USD at the beginning of the specified time period
open_price_1 Price of token 1 in USD at the beginning of the specified time period
high_price_0 Highest price of token 0 in USD in the specified time period
high_price_1 Highest price of token 1 in USD in the specified time period
low_price_0 Lowest price of token 0 in USD in the specified time period
low_price_1 Lowest price of token 1 in USD in the specified time period
close_price_0 Price of token 0 in USD at the end of the specified time period
close_price_1 Price of token 1 in USD at the end of the specified time period
last_processed Last Date/time UTC this liquidity pool was processed through FLUIDEFI's algorithms
token0_collateral Collateral of token 0 in liquidity pool
token1_collateral Collateral of token 1 in liquidity pool
token0_symbol Symbol of token 0 in liquidity pool
token1_symbol Symbol of token 1 in liquidity pool
token0_address Contract address of token 0 in liquidity pool
token1_address Contract address of token 1 in liquidity pool
id FLUIDEFI unique ID number for liquidity pool. Required for other API calls such as Portfolio_update
platform_id FLUIDEFI unique ID number for decentralized exchange
lp_name Name of liquidity pool using token abbreviations (Note: ETH often listed as WETH or 'wrapped ETH')
contract_address Contract Address of smart contract for liquidity pool
url URL of liquity pool on platform
Note: these metrics are updated approximately 5 minutes after the beginning of every hour

CRYPTOCURRENCY PRICES

FLUIDEFI relies on Uniswap V2 and Sushiswap V2's liquidity pools to construct a price index for a particular cryptocurrency.

Assume we would like to find the price of wBitcoin. The following steps are taken:

  1. Identify all pools where wBTC is paired with BUSD, USDC, USDT, or WETH.
  2. Compute the implied price of wBTC from each pool (by assuming equal value of reserves for both tokens)
  3. Compute a poolsize-weighted average of the implied prices, so that bigger pools have more say on what the price should be

APR VS. APY: WHAT’S THE DIFFERENCE?

Both annual percentage yield (APY) and annual percentage rate (APR) refer to the annual return generated from an investment, but they do so in different ways.

APY takes into account the compounding effect, and reports the annual return using one piece of information: the annual return itself. However, APR's calculation does not factor in compounding, and therefore reports the annual return using two pieces of information: the APR + the compounding frequency.

Here's an example of how both metrics are computed. Assume that for the past month, the total return for an investment is 2%. We calculate APR and APY as follows:

In this case, APY > APR due to the compounding effect that is not taken into account by APR.

Also, note that these two statements are equivalent and both report how much return to expect in a year:

  1. Annual return of this investment is 26.82%
  2. This investment has an APR of 24%, compounded monthly

APY is the simpler way of reporting the same information. For this reason, FLUIDEFI only provides APY figures.

SUPPORTED BASE CURRENCIES FOR CALCULATIONS

FLUIDEFI currently supports 12 fiat currencies, gold, silver, and 8,000+ cryptocurrencies. Examples: USD, WETH, GBP, CAD, CHF, JPY, AUD, NZD, HKD, EUR, NOK, SEK, SGD, CNY, KRW, AED, BRL, XAU8, & XAG. If you need a fiat currency that is not listed here, contact support using the method below.

PRECISION

FLUIDEFI supports a precision of 160, which is the size of sqrtX96 variable in many smart-contracts used vr DeFi platforms. The precision of a number is the total count of significant digits in the whole number, or, in other words, the number of digits to both sides of the decimal point. For example: the number 123.4567 has a precision of 7. It is not uncommon to have amounts displayed as 8 digits to the left of the decimal and 16 digits to the right.

DATETIME FORMAT

FLUIDEFI supports ISO 8601 standard format date and datetimes. All datetimes are in UTC. The GET methods support YYYY-MM-DD. Example: "2021-06-01". POST methods support datetimes. Example: "2021-10-18T19:19:06.982417".

RATE LIMITING

Rate limits are based on your subscription level and vary between 5 and 60 calls per second.

"CURRENTLY IN ALPHA" AND "CURRENTLY IN BETA"

From time to time FLUIDEFI documentation may indicate an API call or parameter is currently in Alpha or Beta. "Currently in Beta" functionality is available to FLUIDEFI customers with access to our staging environment. "Currently in Alpha" functionality is available upon request to FLUIDEFI customers with dedicated servers.

STATUS CODES AND ERROR RESPONSES

All error responses have error code and a human-readable message. All error messages are in English.

Code Description
200 Successful GET request
201-202 Successful PUT or POST request
204 Successful request, but the call did not generate any results to return.
400 Bad Request - Please check the parameters passed to the API call.
500-505 Server Error - Please try again later or contact FLUIDEFI Support.
See a full list of HTTP Status Code definitions.

RESPONSE CODES FOR TRANSACTION ROUTES

The following is a list of response codes and messages that will be included in the response when an error is encountered in a request to execute a transaction or encode transaction data fields.

GENERAL

Code Description
1000 Desired network not found in available options
1100 Cannot connect to desired network
1200 No valid account credentials found
2000 Desired platform not found in available options
3000 Invalid address
3100 Not the address of a valid token
4000 Given deadline less than minimum
4050 Gas price too low
5000 Sender's balance is 0 for input asset
5050 Sender's balance is 0 for input asset. Warning: Input asset is WETH
5100 Sender has insufficient balance for input asset
5150 Sender has insufficient balance for input asset. Warning: Input asset is WETH
5200 EVM execution error (error message will be provided if available)

SWAPS

Code Description
6000 Invalid swap mode. Valid options are exactinput or exactoutput
6100 Swap path too short. List must have a minimum of 2 assets
6200 Only one of input asset and output asset can be ETH - not both
6300 For exactinput swaps, amount_in is a required field
6400 For exactouput swaps, amount_out is a required field
6500 Invalid swap path: A pool does not exist for one or more pairs of sequential tokens in path
6550 Insufficient liquidity: One or more of the pairs in the swap path does not have enough liquidity for the swap amounts
6600 Warning: Input asset is WETH. This requires sender has WETH tokens. Use ETH as input asset for swapping from ether
6610 Warning: Output asset is WETH. This will deliver WETH tokens to the recipient. Use ETH as output asset for receiving ether

LIQUIDITY - GENERAL

Code Description
7000 Token A and token B must not be the same asset
7100 A pair does not currently exist for the given assets

ADDING LIQUIDITY

Code Description
8000 Warning: Token A is WETH. This requires sender has WETH tokens. Use ETH as token A for adding liquidity from ether
8010 Warning: Token B is WETH. This requires sender has WETH tokens. Use ETH as token B for adding liquidity from ether
8020 Sender has insufficient balance of token A
8030 Sender has insufficient balance of token B

REMOVING LIQUIDITY

Code Description
9000 Amount provided in liquidity field must be greater than 0
9100 Sender has insufficient balance of LP tokens for amount provided in liquidity field
9200 Warning: Token A is WETH. Recipient will receive WETH tokens. Use ETH as token A for removing liquidity to ether
9210 Warning: Token B is WETH. Recipient will receive WETH tokens. Use ETH as token B for removing liquidity to ether

 
©2021 FLUIDEFI® INC. All rights reserved.
FLUIDEFI® is a Registered Trademark of FLUIDEFI INC.

©2021 FLUIDEFI® INC. All rights reserved.
FLUIDEFI® is a Registered Trademark of FLUIDEFI INC.