since the calculation we use is relying on current token prices to calculate the ROI, in some cases it can lead to impossible values.

please add the following rule to the data feed the API returns.

IF {ROI} <= -100%, set it to 0.

the end result should be that if the ROI is smaller than -100% (which is not a viable value), we zero it out.

example:
ROI = -105%
IF -105% <= -100% -> true -> set ROI==0

ROI = -94%
IF 94% <= -100% -> false -> keep ROI as -94%

the example below yields a 500 error, should instead return a meaningful error such as "unsupported token"
https://api.carbondefi.xyz/v1/market-rate?address=0xa6Ec49E06C25F63292bac1Abc1896451A0f4cFB7&convert=USD,EUR,JPY,GBP,AUD,CAD,CHF,CNY,ETH

Endpoint 3 - /orderbook (Order book depth details)

The /orderbook/ticker_id endpoint is to provide order book information with at least depth = 100 (50 each side) returned for a given market pair/ticker.

API para

ticker_id:

• string
• Mandatory
• A ticker such as "BTC_ETH", with delimiter between different cryptoassets

depth

• integer
• Recommended
• Orders depth quantity: [0, 100, 200, 500...]. 0 returns full depth. Depth = 100 means 50 for each bid/ask side.

Example query:
.../api/orderbook?ticker_id=BTC_ETH&depth=200

Note that for more liquid or closely priced pairs, the lack of order depth may result in miscalculation of depth/spread.

data structure

{
"ticker_id": //baseToken_quoteToken,
"ticker_symbols": //baseToken.symbol_quoteToken.symbol
"timestamp": //Unix timestamp in milliseconds for when the last updated time occurred.,
"bids": //An array containing 2 elements. The offer price and quantity for each bid order
"asks": //An array containing 2 elements. The ask price and quantity for each ask order
}

example:
{  
   "ticker_id": "BTC_ETH",
   "timestamp":"1700050000",
   "bids":[  
      [  
         "49.8", //price in quoteToken
         "0.50000000" //amount in baseToken
      ],
      [  
         "49.9", //price in quoteToken
         "6.40000000" //amount in baseToken
      ]
   ],
   "asks":[  
      [  
         "50.1", //price in quoteToken
         "9.20000000" //amount in baseToken
      ],
      [  
         "50.2", //price in quoteToken
         "7.9000000" //amount in baseToken
      ]
   ]
}

calculated values

"bids"

1. price in quote token -> calculating the price in quoteToken. (for reference, use the process from the frontend as reference
2. amount in baseToken -> showing the available liquidity in baseToken (for reference, use the process from the frontend as reference

"asks"

same as bids

we would like to maintain a price history database that would be used for the simulator and future development of the charting modal. once we have the data, we would be able to switch out of tradingView and use a customised library.

historical price would have 2 tables:

7 day history

maintaining the most recent 7 days data

• 7 days sliding window
• 1 min price tick
• include the following data points:
  -- high: max(priceAtPointN, priceAtPointN-1)
  -- low: min(priceAtPointN, priceAtPointN-1)
  -- start: priceAtPointN-1
  -- end: priceAtPointN

6 months history

maintaining the data for the last 6 months

• 6 months sliding window
• 1 hour price tick
• include the following data points:
  -- high: max(priceAtPointN, priceAtPointN-1)
  -- low: min(priceAtPointN, priceAtPointN-1)
  -- start: priceAtPointN-1
  -- end: priceAtPointN

data structure:

pair: baseToken_quoteToken
{ 
  base_id: base token address
  base_name: base token name
  base_symbol: base token symbol
  quote_id: quote token address
  quote_name: quote token name
  quote_symbol: quote token symbol
  last_price: Last transacted price of base currency based on given quote currency
  base_volume: 24-hour trading volume denoted in BASE currency
  quote_volume: 24 hour trading volume denoted in QUOTE currency
}

Calculating values:

last_price

using the last known trade, use the sourceAmount and targetAmount to calculate the effective price of the last trade.
last_price =

• IF sourceToken = baseToken, targetAmount/sourceAmount
• ELSE (sourceToken = quoteToken), sourceAmount/targetAmount

example:
ex:1
100 baseToken -> 5321.123 quoteToken
if sourceToken=baseToken,
last_price= targetAmount/sourceAmount = 5321.123/100 = 5.321123 quoteToken

ex:2 
5321.123 quoteToken -> 100 baseToken
if sourceToken=baseToken, //false
else, sourceToken != baseToken,
last_price = sourceAmount/targetAmount = 5321.123/100 = 5.321123 quoteToken

base_volume

aggregating all transactions amounts and denoting in the BASE token.
=sum(transaction.baseToken.amount)

ex:
trade 100 baseToken -> 5321.123 quoteToken
base_volume = 100

quote_volume

aggregating all transactions amounts and denoting in the QUOTE token.
=sum(transaction.quoteToken.amount)

ex:
trade 100 baseToken -> 5321.123 quoteToken
quote_volume = 5321.123

Examples:

{
    "0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599_0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2": {
        "base_id": "0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599",
        "base_name": "Wrapped BTC",
        "base_symbol": "WBTC",
        "quote_id": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
        "quote_name": "Wrapped Ether",
        "quote_symbol": "WETH",
        "last_price": "30.45692523596447546478",
        "base_volume": "1725.0451867",
        "quote_volume": "52450.878529932577252127"
    },
    "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2_0xdAC17F958D2ee523a2206206994597C13D831ec7": {
        "base_id": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
        "base_name": "Wrapped Ether",
        "base_symbol": "WETH",
        "quote_id": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
        "quote_name": "Tether USD",
        "quote_symbol": "USDT",
        "last_price": "345.2244580923542612263",
        "base_volume": "195644.931427163765765227",
        "quote_volume": "67443916.533922"
    },

Endpoint 4 - /historical_trades (Historical Data)

The /historical_trades/ticker_id is used to return data on historical completed trades for a given market pair.

Endpoint parameters:

• ticker_id: A pair such as "BTC_ETH", with delimiter between different cryptoassets
• type: To indicate nature of trade - buy/sell
• limit: Number of historical trades to retrieve from time of query. [0, 200, 500...]. 0 returns full history.
• start_time: Start time from which to query historical trades from
• end_time: End time for historical trades query

Example query:
.../api/historical_trades?ticker_id=BTC_ETH&limit=10

Response parameters:

• "trade_id": transactionHash,
• "price": Transaction price of baseToken in quoteToken.,
• "base_volume": Transaction amount in base pair volume.,
• "target_volume": Transaction amount in target pair volume.,
• "trade_timestamp": Unix timestamp in milliseconds for when the transaction occurred.
• "type": Used to determine the type of the transaction that was completed.
  -- Buy – Identifies an ask that was removed from the order book.
  -- Sell – Identifies a bid that was removed from the order book.

Example response:

“buy”: [  
   {        
      "trade_id":1234567,
      "price":"50.1",
      "base_volume":"0.1",
      "target_volume":"1",
      "trade_timestamp":"1700050000",
      "type":"buy"
   }
],
“sell”: [
   {        
      "trade_id":1234567,
      "price":"50.1",
      "base_volume":"0.1",
      "target_volume":"1",
      "trade_timestamp":"1700050000",
      "type":"sell"
   }
]

as a user, i would like to have access to my account history (carbon related) and see transaction performed by me and trades that have used my strategy. the information should include display currency value at the time of transaction (historically).

Case 1: user creates a new strategy to sell 10 ETH

Flow:

1. we keep track of the transaction
2. we keep track of the ETH to USD rate at the time of transaction
3. we keep track of the USD to {list of supported display currency} at the time of transaction

Case 2: trade happens against a carbon strategy (or a list of them)

Flow:

1. we keep track of the transaction
2. we break the transaction details into multiple orders and identify the relevant details (token amounts in/out) from each strategy id
3. we keep track of the base/quote token to USD rate at the time of transaction
4. we keep track of the USD to {list of supported display currency} at the time of transaction

https://dexscreener.notion.site/DEX-Screener-Adapter-Specs-cc1223cdf6e74a7799599106b65dcd0e

API requirements:
Publicly accessible, no-authentication API endpoints are required
Reasonable rate limits to ensure tickers/pairs list, market data, orderbook data can be queried on a minutely basis.
Data available in JSON format.
To whitelist CoinGecko’s IP address where necessary.

Endpoint 2 - /tickers (Market Info)

The /tickers endpoint provides 24-hour pricing and volume information on each market pair available on an exchange.

Response details

same information required for #1 plus:

• pool_id: pool/pair address or unique ID. we would like to pass the unique pool value here (token0, token1)
• liquidity_in_usd: Pool liquidity in USD //checking to see if we can skip this
• bid: Current highest bid price
• ask: Current lowest ask price
• high: Rolling 24-hours highest transaction price
• low: Rolling 24-hours lowest transaction price

Calculated values

liquidity in usd

for a specific pair,
= sum(token0.balance)*token0.usdRate + sum(token1,balance)*token1.usdRate
including all orders, in both directions.

bid

last wei of liquidity on the "sell" baseToken side

ask

last wei of liquidity on the "buy" baseToken side