--- description: Guavy Crypto Server API alwaysApply: true applyTo: "**" downloadedFrom: https://guavy.com/llms.txt version: 1.0.0 --- # Guavy Crypto Server API Guavy Crypto Server provides a comprehensive API for accessing cryptocurrency market data, sentiment analysis, and trading signals. ## Getting Started To use the API, you need an API key. You can sign up for one at [Get API Access](https://guavy.com/get-api-access). Authentication is done via the `Authorization` header: `Authorization: Bearer YOUR_API_KEY` ## Instruments ### GET /api/v1/instruments/list-symbols List symbols for all available instruments with optional pagination. **Path**: `/api/v1/instruments/list-symbols?limit=&skip=` **Example**: `https://guavy.com/api/v1/instruments/list-symbols?limit=4&skip=3` **Parameters**: - `skip` (integer): Number of symbols to skip for pagination. Defaults to 100. - `limit` (integer): Maximum number of symbols to return. Defaults to 0. **Response Fields**: - `symbols` (array[string]): An array of instrument symbols. ### GET /api/v1/instruments/get-detail Retrieve detailed instrument information using its symbol. **Path**: `/api/v1/instruments/get-detail/` **Example**: `https://guavy.com/api/v1/instruments/get-detail/btc` **Parameters**: - `symbol` (string) [Required]: The symbol of the instrument to fetch details for. **Response Fields**: - `logo` (string): URL to the instrument's logo image. - `name` (string): The instrument's name. - `symbol` (string): The instrument's unique symbol. ### GET /api/v1/instruments/search-instruments Search for instruments in our database using a query string. Returns up to 5 matches on symbol or name. **Path**: `/api/v1/instruments/search-instruments/` **Example**: `https://guavy.com/api/v1/instruments/search-instruments/bit` **Parameters**: - `query` (string) [Required]: The text to find instrument matches on symbol or name. **Response Fields**: - `instruments` (array[object]): Array of instruments objects with the following keys: - `logo` (string): URL to the instrument's logo image. - `name` (string): The name of the instrument. - `symbol` (string): The symbol of the instrument. ## Newsroom ### GET /api/v1/newsroom/get-recent-briefs Fetch news briefs for a specific instrument using its symbol. **Path**: `/api/v1/newsroom/get-recent-briefs/?limit=` **Example**: `https://guavy.com/api/v1/newsroom/get-recent-briefs/btc?limit=2` **Parameters**: - `symbol` (string) [Required]: The symbol to fetch news for. - `limit` (integer): The maximum number of news briefs to return. Defaults to 100. **Response Fields**: - `briefs` (array[object]): The array of news brief objects, with the following keys: - `article_id` (string): The unique identifier of the associated article. - `body` (string): The text body of the brief. This may contain HTML tags. - `clout` (integer): A score, between 0 and 100, of the publisher's audience, credibility, and trust. - `date` (string): Date of publication. - `fud_fomo_score` (integer): Intensity of emotional bias in the article's language. Scores range from 0 (neutral/factual) to 10 (pure manipulation with almost no factual content). - `fud_fomo_bias` (string): Direction of emotional bias: 'neutral' (balanced/factual), 'fud' (fear, uncertainty, doubt), or 'fomo' (fear of missing out, hype). - `impacted_coins` (array[object]): Directional price outlooks for coins mentioned in the article. Each entry includes the following keys: - `asset` (string): Ticker symbol of the referenced coin (e.g., BTC, ETH). - `confidence` (integer): Confidence score from 0 (low) to 10 (high). - `direction` (string): Predicted direction: bullish, bearish, or neutral. - `timeframe` (string): Duration of the outlook, either short, long, or short to long. - `sentiment` (integer): A sentiment score for the article between -5 (very negative) and +5 (very positive). - `speculation_score` (integer): Quantifies how much an article relies on opinion, prediction, or unverified claims versus confirmed, factual reporting. Scores range from 0 (entirely factual, verified information) to 10 (pure speculation with no factual grounding). - `symbols` (array[string]): The list of symbols mentioned in the article. - `timestamp` (integer): UNIX timestamp (in milliseconds) of publication. - `title` (string): The title of the brief. - `tone` (string): The tone of the brief ### GET /api/v1/newsroom/get-instrument-analysis Retrieve a qualitative analysis of an instrument using its symbol. **Path**: `/api/v1/newsroom/get-instrument-analysis/` **Example**: `https://guavy.com/api/v1/newsroom/get-instrument-analysis/btc` **Parameters**: - `symbol` (string) [Required]: The symbol of the instrument to retrieve an analysis for. **Response Fields**: - `analysis` (string): The AI-generated summary of an instrument's market performance and trends. This may contain HTML tags. - `date` (string): The date for which the analysis applies. - `timestamp` (integer): The UNIX timestamp (in milliseconds) of the analysis date. ### GET /api/v1/newsroom/get-article Fetch a news article using its unique identifier (ID). IDs are returned in the 'Get Recent Briefs' route. **Path**: `/api/v1/newsroom/get-article/` **Example**: `https://guavy.com/api/v1/newsroom/get-article/a11c5fcb-c3b8-4b6d-9454-ea6df6d85e4f` **Parameters**: - `article_id` (string) [Required]: The unique identifier of the article to retrieve. **Response Fields**: - `article_id` (string): The unique identifier of the article. - `body` (string): The text body of the article. This may contain HTML tags. - `clout` (integer): A score, between 0 and 100, of the publisher's audience, credibility, and trust. - `date` (string): Date of publication. - `fud_fomo_score` (integer): Intensity of emotional bias in the article's language. Scores range from 0 (neutral/factual) to 10 (pure manipulation with almost no factual content). - `fud_fomo_bias` (string): Direction of emotional bias: 'neutral' (balanced/factual), 'fud' (fear, uncertainty, doubt), or 'fomo' (fear of missing out, hype). - `impacted_coins` (array[object]): Directional price outlooks for coins mentioned in the article. Each entry includes the following keys: - `asset` (string): Ticker symbol of the referenced coin (e.g., BTC, ETH). - `confidence` (integer): A confidence score from 0 (low) to 10 (high). - `direction` (string): Predicted direction: bullish, bearish, or neutral. - `timeframe` (string): Duration of the outlook, either short, long, or short to long. - `sentiment` (integer): A sentiment score for the article between -5 (very negative) and +5 (very positive). - `speculation_score` (integer): Quantifies how much an article relies on opinion, prediction, or unverified claims versus confirmed, factual reporting. Scores range from 0 (entirely factual, verified information) to 10 (pure speculation with no factual grounding). - `symbols` (array[string]): The list of symbols mentioned in the article. - `timestamp` (integer): UNIX timestamp (in milliseconds) of publication. - `title` (string): The title of the article. - `tone` (string): The tone of the article. ### GET /api/v1/newsroom/get-market-summary Get a daily analysis of global market trends and performance. **Path**: `/api/v1/newsroom/get-market-summary` **Example**: `https://guavy.com/api/v1/newsroom/get-market-summary` **Response Fields**: - `date` (string): The date for which the summary applies. - `summary` (string): An AI-generated summary of current market conditions. This may contain HTML tags. - `timestamp` (integer): The UNIX timestamp (in milliseconds) of the date the summary was generated. ## Sentiment ### GET /api/v1/sentiment/get-sentiment-history Retrieve sentiment time series data for an instrument over a specified number of days. **Path**: `/api/v1/sentiment/get-sentiment-history/?limit=` **Example**: `https://guavy.com/api/v1/sentiment/get-sentiment-history/btc?limit=2` **Parameters**: - `symbol` (string) [Required]: The symbol of the instrument to fetch sentiment data for. - `limit` (integer): The maximum number of days of time series data to return. Defaults to 100. **Response Fields**: - `sentiment` (array[object]): Array of sentiment data objects, with the following keys: - `date` (string): The date for which the sentiment data applies. - `negative` (integer): The count of negative sentiment mentions for the day. - `neutral` (integer): The count of neutral sentiment mentions for the day. - `positive` (integer): The count of positive sentiment mentions for the day. - `symbol` (string): The symbol of the instrument. - `timestamp` (integer): The UNIX timestamp (in milliseconds) date for which the sentiment data applies. - `total` (integer): The total count of sentiment mentions for the day. ## Trades ### GET /api/v1/trades/get-trend-history This endpoint returns timeseries trend data for a given instrument. **Path**: `/api/v1/trades/get-trend-history//` **Example**: `https://guavy.com/api/v1/trades/get-trend-history/btc/4` **Parameters**: - `symbol` (string) [Required]: The symbol of the instrument to fetch trend history for. - `limit` (integer) [Required]: The maximum number of days of time series trend data to return. **Response Fields**: - `trends` (array[object]): Array of trend history objects, with the following keys: - `date` (string): Human-readable date string formatted from the timestamp. - `price` (integer): The price of the cryptocurrency at the start of the trend. - `strength` (string): The strength of the trend e.g. Moderate, Solid, Strong, or Weak - `timestamp` (integer): UNIX timestamp (in milliseconds) representing when this data was collected. - `trend` (string): The trend of the cryptocurrency action e.g. Up, Down, or Neutral. ### GET /api/v1/trades/get-recent-buys This endpoint returns recent buys made by the Guavy trade simulator. **Path**: `/api/v1/trades/get-recent-buys?limit=&skip=0&strategy=` **Example**: `https://guavy.com/api/v1/trades/get-recent-buys?limit=4&skip=0&strategy=Any` **Parameters**: - `limit` (integer): Specifies the maximum number of instruments to return (default is 10). - `skip` (integer): Specifies the number of results to skip (default is 0). - `strategy` (string): Specifies a risk profile to filter scorecards for. Either 'aggressive' or 'conservative'. Default is 'Any'. **Response Fields**: - `trades` (array[object]): Array of buying trade history objects, with the following keys: - `action` (string): The trade action taken (Buy). - `days_in_trade` (integer): The number of days the instrument is in trade. - `highest_price` (float): The highest price during the trade. - `last_price` (float): The most recent price recorded during the trade. - `lowest_price` (float): The lowest price during the trade. - `profit` (float): The profit of the trade. - `profit_percent` (float): The profit percentage of the trade. - `start_date` (string): The start date of the trade. - `start_price` (float): The price of the instrument at the start date. - `strategy` (string): The risk profile used for the trade. Can be 'aggressive' or 'conservative'. - `symbol` (string): The symbol representing the instrument object. ### GET /api/v1/trades/get-recent-sells This endpoint returns recent sells made by the Guavy trade simulator. **Path**: `/api/v1/trades/get-recent-sells?limit=&skip=&strategy=` **Example**: `https://guavy.com/api/v1/trades/get-recent-sells?limit=2&skip=0&strategy=Any` **Parameters**: - `limit` (integer): Specifies the maximum number of instruments to return (default is 10). - `skip` (integer): Specifies the number of results to skip (default is 0). - `strategy` (string): Specifies a risk profile to filter scorecards for. Either 'aggressive' or 'conservative'. Default is 'Any'. **Response Fields**: - `trades` (array[object]): Array of selling trade history objects, with the following keys: - `action` (string): The trade action taken (Sell). - `entry_price` (float): The price of the instrument when the trade was entered. - `exit_price` (float): The price of the instrument at the sell date. - `exit_reason` (string): The reason for exiting the trade. - `highest_price` (float): The highest price during the trade. - `lowest_price` (float): The lowest price during the trade. - `profit` (float): The profit of the trade. - `profit_percent` (float): The profit percentage of the trade. - `sell_date` (string): The date of the sell and exiting of the trade. - `strategy` (string): The risk profile used for the trade. Can be 'aggressive' or 'conservative'. - `symbol` (string): The symbol representing the instrument object. ### GET /api/v1/trades/get-current-action This endpoint returns the current action taken by the Guavy trade simulator for a given instrument and trade strategy. **Path**: `/api/v1/trades/get-current-action//` **Example**: `https://guavy.com/api/v1/trades/get-current-action/btc/conservative` **Parameters**: - `symbol` (string) [Required]: The instrument to get the current action for. - `strategy` (string) [Required]: The risk profile to get the current action for, can be 'aggressive' or 'conservative'. **Response Fields**: - `action` (string): The current trade action, either Buy, Sell, Hold, or Stay. - `message` (string): The description explaining the associated trade action. - `symbol` (string): The symbol representing the instrument object. ### GET /api/v1/trades/get-recommendations Fetches instrument recommendations that match a given trade strategy, and meet a minimum performance score of the Guavy simulator. **Path**: `/api/v1/trades/get-recommendations` **Example**: `https://guavy.com/api/v1/trades/get-recommendations?limit=10&skip=0&min_score=3.5&strategy=aggressive` **Parameters**: - `limit` (integer): Specifies the maximum number of instruments to return (default is 10). - `skip` (integer): Specifies the number of results to skip (default is 0). - `min_score` (float): Specifies the minimum score threshold for recommendations (default is 3.5). - `strategy` (string): Specifies a risk profile to filter recommendations for. Either 'aggressive' or 'conservative'. Default is 'aggressive'. **Response Fields**: - `recommendations` (array[object]): Array of recommendation objects, with the following keys: - `score` (float): The Guavy simulator score (a value from 0 to 5, where 5 is the best), which indicates how well the instrument performs based on historical backtesting. - `strategy` (string): The risk profile used for the recommendation. Can be 'aggressive' or 'conservative'. - `symbol` (string): The symbol representing the instrument object. ### GET /api/v1/trades/get-backtest-history This endpoint returns an array of historical backtest trades made by the Guavy simulator for a given instrument and trade strategy. **Path**: `/api/v1/trades/get-backtest-history//?years=&limit=` **Example**: `https://guavy.com/api/v1/trades/get-backtest-history/BTC/conservative?years=3&limit=2` **Parameters**: - `symbol` (string) [Required]: The symbol of the instrument to perform a backtest analysis on. - `strategy` (string) [Required]: The risk profile to use for the backtest. Can be 'aggressive' or 'conservative'. - `years` (integer): Specifies the maximum number of years of historical data to include in the backtest (default is 2). - `limit` (integer): Specifies the maximum number of trades to return (default is 50). **Response Fields**: - `trades` (array[object]): Array of backtest history objects (trades made), with the following keys: - `days_in_trade` (integer): The number of days the instrument was in trade. - `entry_date` (string): The date the instrument was bought, and the trade was entered. - `entry_price` (float): The price of the instrument when the trade was entered. - `exit_date` (string): The date the instrument was sold, and the trade was exited. - `exit_price` (float): The price of the instrument when the trade was exited. - `exit_reason` (string): The reason for exiting the trade. - `highest_price` (float): The highest price of the instrument during the trade. - `lowest_price` (float): The lowest price of the instrument during the trade. - `profit` (float): The profit or loss value of the trade. - `profit_percent` (float): The profit or loss value of the trade as a percentage. ### GET /api/v1/trades/get-backtest-summary This endpoint provides a high-level performance overview of historical backtest trades made by the Guavy simulator for a given instrument and trade strategy. **Path**: `/api/v1/trades/get-backtest-summary//?years=` **Example**: `https://guavy.com/api/v1/trades/get-backtest-summary/ADA/conservative?years=3` **Parameters**: - `symbol` (string) [Required]: The symbol of the instrument to perform a backtest on. - `strategy` (string) [Required]: The risk profile to use for the backtest. Can be 'aggressive' or 'conservative'. - `years` (integer): Specifies the maximum number of years of historical data to include in the backtest (default is 2). **Response Fields**: - `annualized_return` (float): The expected annualized return based on total profit and backtest duration. - `average_loss` (float): The average loss per unprofitable trade. - `average_loss_percent` (float): The average loss per unprofitable trade, as a percentage. - `average_profit` (float): The average gain per profitable trade. - `average_profit_percent` (float): The average gain per profitable trade, as a percentage. - `average_trade_duration` (float): The average length of a trade, in days. - `backtest_duration` (integer): The length of historical data provided to the backtest, in days. - `buy_and_hold_profit_percent` (float): Profit gains, as a percentage, if the Guavy simulator had bought and held the instrument for the duration of the backtest. - `end_date` (string): The end date of the backtest simulation. - `final_value` (float): The final value of the investment after all simulated trades. - `initial_investment` (integer): The initial value invested in the instrument. - `peak_loss` (float): The greatest loss made by a singular trade. - `peak_profit` (float): The highest profit made by a singular trade. - `profit_percent` (float): The total profit made from the simulated trades, as a percentage. - `profitable_trade_percent` (float): The percentage of trades that made a profit. - `profitable_trades` (integer): The number of trades that made a profit. - `start_date` (string): The start date of the backtest simulation. - `total_profit` (float): The total profit made from the simulated trades. - `total_trades` (integer): The total number of trades made in the simulation. - `unprofitable_trades` (integer): The number of unprofitable trades made in the simulation.