--- description: Guavy API alwaysApply: true applyTo: "**" downloadedFrom: https://guavy.com/llms.txt version: 1.0.0 --- # Guavy API Guavy provides a comprehensive API for scored market sentiment, news, and trade signals across every market Guavy covers. ## Getting Started To use the API, you need an API key. You can sign up for one at [Sign up](https://guavy.com/auth/signup). Authentication is done via the `Authorization` header: `Authorization: Bearer YOUR_API_KEY` ## Token Budget & Response Headers Every metered response reports your balance in headers, so you never have to guess: `x-tokens-cost` (what this call cost), `x-tokens-limit` / `x-tokens-remaining` (monthly), and `x-tokens-limit-today` / `x-tokens-remaining-today` (daily). The `remaining` values are net of any credit applied to the same request. A `401` budget refusal carries them too, with `x-tokens-cost` at `0` because nothing was charged. ## Errors Standard HTTP status codes: `400` malformed request (e.g. a `strategy` outside `aggressive`/`conservative` — the response names the offending value), `401` missing/invalid key or exhausted budget (a budget refusal adds `error_code` `DAILY_TOKEN_LIMIT` or `MONTHLY_TOKEN_LIMIT`, `limit_type`, `resets_at` (when the limit lifts, UTC; null when it cannot be stated) and `upgrade_url`, so it can be told apart from a bad key without reading the message), `402` market not in your plan (not returned today, because every launched market is on every plan's Sandbox floor), `404` unknown resource, `429` rate limited (retry after the `Retry-After` header), `503` a data source we depend on is temporarily unavailable — the trade-simulator upstream, or the datastore behind the news, sentiment and trend endpoints (retry after `Retry-After`). Over REST we don't bill you for our failures: tokens charged for a `5xx`, or for a `404` that lands after we've already charged, are credited back — less a 1-token floor. MCP has no credit path: a tool call that fails after it was charged keeps its charge. ## Limits `limit` is bounded per route: paginated endpoints (list-symbols, recent-buys, recent-sells, recommendations) cap at 1000 results per call — page further with `skip`; unpaginated series (trend-history, backtest-history) cap at 5000, set above the real series length so nothing reachable is truncated. `years` on backtests caps at 10. ## API Versions & Markets There are two REST surfaces, and picking the wrong one is the most common integration error: - **`/api/v1/...`** — **crypto only**, and frozen. Every route below under a bare `/api/v1` path resolves its symbol against crypto, whatever you ask for. v1 takes **no** `market` parameter: a `?market=` query string is silently ignored, so `/api/v1/instruments/scorecard/Gold?market=commodities` is a crypto lookup for "Gold" and 404s. - **`/api/v2/{market}/...`** — the per-market surface. **`{market}` is a path segment, not a query parameter.** Valid values: `crypto`, `forex`, `commodities`, `stocks`. `/api/v2/crypto/...` serves every v1 route, so crypto's v2 is a full superset of v1 — new integrations should use v2 for every market including crypto. Non-crypto markets serve the subset documented under "REST — per-market (v2)" at the end of this file; the trade-simulator routes, `get-market-summary`, `get-instrument-analysis`, `search-instruments` and `get-detail` are crypto-only and appear only under `/api/v1` and `/api/v2/crypto`. The `market` argument described under "AI Agent Integration (MCP)" below is an **MCP tool argument**. Its REST equivalent is the `{market}` path segment — there is no REST route anywhere in this API that accepts `market` as a query parameter. ## AI Agent Integration (MCP) Guavy provides a native MCP (Model Context Protocol) server, compatible with Claude Desktop, Claude Code, Cursor, VS Code, Grok, and Gemini CLI. **MCP Endpoint:** `https://guavy.com/mcp` (streamable HTTP: `POST` JSON-RPC to it; `GET` opens the legacy SSE stream) **Legacy SSE Message Endpoint:** `https://guavy.com/mcp/messages?sessionId=` (POST) **Authentication:** Bearer token in `Authorization` header (same API key) ### Usage Note MCP calls cost **1-20 tokens** per tool, by route tier, against your daily/monthly allowance. All plans, including Sandbox, can reach every live market on both REST and MCP. ### Available MCP Tools - `get_market_summary` — Daily AI-generated global market analysis - `get_recommendations` — Trade recommendations by strategy (aggressive/conservative) - `get_recent_buys` — Recent buy signals across all coins - `get_recent_sells` — Recent sell signals across all coins - `get_current_action` — Current action (Buy/Sell/Hold/Stay) for a coin + strategy - `get_trend_history` — Price trend time-series with strength indicators - `get_sentiment_history` — Sentiment time-series (positive/negative/neutral counts) - `get_recent_briefs` — Recent news briefs with sentiment + FUD/FOMO scores - `search_briefs` — Search an instrument's news headlines from the past 24 hours for one word or exact phrase - `get_instrument_analysis` — AI-generated qualitative analysis for a coin - `search_instruments` — Search coins by name or symbol - `list_symbols` — List the instrument symbols covered in a market - `get_article` — Fetch a full news article by ID - `get_price_history` — Daily historical price data (price, volume, timestamp) for an instrument - `get_indicators` — Technical indicators (SMA, EMA, RSI, MACD, Bollinger Bands, Stochastic, ATR, VWAP, OBV, Fibonacci, ADX, and ROC) for an instrument - `get_backtest_summary` — Backtested performance summary (returns, win rate, drawdown) by coin and strategy - `get_backtest_history` — The individual simulated trades behind a backtest summary - `get_scorecard` — Multi-factor scorecard: overall action, score, trend, and the simulated trading record - `get_detail` — A coin's identifying metadata (name, symbol, logo). Crypto only - `get_current_trend` — Current trend state (direction, strength, moving averages, duration). Forex, commodities and stocks; crypto uses `get_trend_history` - `get_trend_segments` — Completed trend episodes, newest first. A few dozen per symbol, NOT a daily series. Forex, commodities and stocks ### Markets The data tools accept an optional `market` parameter; omit it for crypto. Every live market is included on every plan's Sandbox floor, and per-market Quant and Pro plans raise that market's token budget. Market-aware tools: `list_symbols`, `get_scorecard`, `get_price_history`, `get_indicators`, `get_recent_briefs`, `search_briefs`, `get_article`, `get_sentiment_history`, `get_current_trend`, `get_trend_segments`. All other tools (the trade-simulator signals and backtests, `get_market_summary`, `get_instrument_analysis`, `search_instruments`, `get_detail`) are crypto-only. `get_current_trend` and `get_trend_segments` are the inverse: they read Mongo-native trend collections that crypto does not have, so crypto returns an error on both. ### Claude Desktop Config ```json { "mcpServers": { "guavy": { "url": "https://guavy.com/mcp?key=YOUR_API_KEY" } } } ``` No dependencies — Claude Desktop connects directly. If your version doesn't support `url`, use the Node.js fallback: ```json { "mcpServers": { "guavy": { "command": "npx", "args": ["-y", "mcp-remote", "https://guavy.com/mcp?key=YOUR_API_KEY"] } } } ``` Install Node.js: Mac `brew install node` · Windows `winget install OpenJS.NodeJS` · Linux `sudo apt install nodejs npm` ## OpenAPI / GPT Actions - **OpenAPI spec:** `https://guavy.com/openapi.json` - **ChatGPT plugin manifest:** `https://guavy.com/.well-known/ai-plugin.json` Import the manifest URL into the ChatGPT Custom GPT editor to add Guavy tools to your GPT. ## Claude Skills Download the Claude Skills package for a pre-configured Guavy skill: `https://guavy.com/claude-skill.md` ## REST — crypto (v1) Crypto only, and frozen. These paths ignore a `market` query parameter. For any other market, and for new crypto integrations, use the `/api/v2/{market}` routes at the end of this file. ## 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=0` **Parameters**: - `skip` (integer): Number of symbols to skip for pagination. Defaults to 0. Symbols are returned in storage order, which is stable between pages. - `limit` (integer): Maximum number of symbols to return. Defaults to 10, maximum 1000. To list every symbol, page with skip until a page comes back short. **Response Fields**: - `symbols` (array[string]): An array of instrument symbols. ### GET /api/v1/instruments/scorecard Retrieve the multi-factor scorecard for an instrument: the overall action and score, the strategy behind the call, and the simulated trading record supporting it. **Path**: `/api/v1/instruments/scorecard/` **Example**: `https://guavy.com/api/v1/instruments/scorecard/btc` **Parameters**: - `symbol` (string) [Required]: The symbol of the instrument to fetch the scorecard for. **Response Fields**: - `symbol` (string): The instrument symbol. - `name` (string): The instrument's display name. - `icon` (string): URL to the instrument's icon image. An empty string where the market carries no icon metadata. - `action` (string): The current call: Buy, Sell, Hold, or Stay. - `strategy` (string): The strategy the action was derived from (aggressive or conservative). - `in_trade` (boolean): Whether the simulated position is currently open. - `score` (number): Overall multi-factor score. - `percentage_profit` (number): Profit of the simulated strategy, as a percentage. - `buy_and_hold_percentage` (number): Profit of simply buying and holding over the same period, for comparison. - `total_trades` (integer): Number of simulated trades behind the figures above. Null where none has run. - `trend` (string): Current trend direction (Up, Down, or Neutral). Null where unknown. - `trend_duration` (integer): How many days the current trend has run. Null where unknown. ### 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, newest first. Defaults to 10, maximum 1000. **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` (number): A score, between 0 and 100, of the publisher's audience, credibility, and trust. - `date` (string): Date of publication. - `fud_fomo_score` (number): 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): The scoring model's confidence in this directional call, from 1 (low) to 10 (high). - `direction` (string): Predicted direction: bullish, bearish, or neutral. - `timeframe` (string): Horizon of the predicted move: short (hours to days) or long (weeks to months). - `sentiment` (integer): A sentiment score for the article between -5 (very negative) and +5 (very positive). - `speculation_score` (number): 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/search-briefs Search the headlines of an instrument's news briefs from the past 24 hours for a word or phrase. Results are newest first. **Path**: `/api/v1/newsroom/search-briefs/?keywords=&limit=` **Example**: `https://guavy.com/api/v1/newsroom/search-briefs/BTC?keywords=etf&limit=5` **Parameters**: - `symbol` (string) [Required]: Symbol to search briefs for (e.g. BTC, ETH). - `keywords` (string): Text to find in brief headlines, matched case-insensitively as one exact phrase: "rate cut" matches only headlines containing "rate cut", not ones with the two words apart. Defaults to empty (every brief from the past 24 hours). - `limit` (integer): The maximum number of briefs to return. Defaults to 20, maximum 1000. **Response Fields**: - `briefs` (array[object]): The array of matching news brief objects. Same structure as get-recent-briefs. ### 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): UNIX timestamp (in SECONDS) of the analysis date. Note: this endpoint and get-market-summary return seconds; the briefs, sentiment and price-history endpoints return milliseconds. ### 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/a997322a-4df0-4e80-8b0f-5e74be2be871` **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` (number): A score, between 0 and 100, of the publisher's audience, credibility, and trust. - `date` (string): Date of publication. - `fud_fomo_score` (number): 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): The scoring model's confidence in this directional call, from 1 (low) to 10 (high). - `direction` (string): Predicted direction: bullish, bearish, or neutral. - `timeframe` (string): Horizon of the predicted move: short (hours to days) or long (weeks to months). - `sentiment` (integer): A sentiment score for the article between -5 (very negative) and +5 (very positive). - `speculation_score` (number): 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): UNIX timestamp (in SECONDS) of the date the summary was generated. Note: this endpoint and get-instrument-analysis return seconds; the briefs, sentiment and price-history endpoints return milliseconds. ## 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, newest first. Defaults to 100, maximum 1000. **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. ## Technical Analysis ### GET /api/v1/technical-analysis/get-price-history Retrieve daily historical price data for a given cryptocurrency symbol. Returns an array of daily price quotes with price, volume, and timestamp in milliseconds, oldest first. With no query parameters the FULL stored history is returned; `limit` returns only the most recent N points, and `from`/`to` are inclusive bounds in unix milliseconds (the range is applied first, then `limit` caps within it). Narrowing the request costs fewer tokens than the full series. **Path**: `/api/v1/technical-analysis/get-price-history/?limit=&from=&to=` **Example**: `https://guavy.com/api/v1/technical-analysis/get-price-history/BTC?limit=3` **Parameters**: - `symbol` (string) [Required]: The symbol of the instrument to fetch price history for (e.g. BTC, ETH). - `limit` (integer): Return only the most recent N daily points, maximum 3650. Omit it for the full series. - `from` (integer): Earliest point to include, as a unix timestamp in milliseconds (inclusive). - `to` (integer): Latest point to include, as a unix timestamp in milliseconds (inclusive). **Response Fields**: - `price_history` (array[object]): Array of daily price quote objects. - `price` (float): The closing price for the day. - `volume` (float): The 24-hour trading volume. - `timestamp` (integer): Unix timestamp in milliseconds. - `date` (string): Human-readable date (e.g. "Mar 25, 2024"). ### GET /api/v1/technical-analysis/get-indicators Compute key technical indicators from historical daily closing prices for a given symbol. Returns SMA, EMA, RSI, MACD, Bollinger Bands, Stochastic Oscillator, ATR, VWAP, OBV, Fibonacci Retracement, ADX, and ROC. SMA, Bollinger Bands, ATR, VWAP, OBV and Fibonacci are computed over the last `period` days; EMA uses `period` as its span over the full history; RSI (14), MACD, Stochastic (14), ADX (14) and ROC (12) use their standard lengths over the full history. No stored history carries daily highs and lows, so ATR, Stochastic and ADX are computed from closing prices. **Path**: `/api/v1/technical-analysis/get-indicators/?period=` **Example**: `https://guavy.com/api/v1/technical-analysis/get-indicators/BTC?period=30` **Parameters**: - `symbol` (string) [Required]: The symbol of the instrument to analyze (e.g. BTC, ETH). - `period` (integer): Number of days in the analysis window. Defaults to 30, minimum 2, maximum 365; a value outside that range is clamped, and the response's period field shows the value used. **Response Fields**: - `indicators` (object): Map of technical indicator values. - `sma` (float): Simple Moving Average over the period. - `ema` (float): Exponential Moving Average over the period. - `rsi` (float): Relative Strength Index (0-100). >70 overbought, <30 oversold. - `macd` (object): MACD with macd_line, signal_line, and histogram. - `bollinger_bands` (object): Upper, middle, and lower Bollinger Bands. - `stochastic_oscillator` (object): Stochastic %K and %D values. - `atr` (float): Average True Range, a volatility indicator. - `vwap` (float): Volume Weighted Average Price. - `obv` (float): On-Balance Volume. - `fibonacci_retracement` (object): Fibonacci levels (23.6%, 38.2%, 50%, 61.8%) with high and low. - `adx` (float): Average Directional Index (0-100). >25 strong trend, <20 weak/ranging. - `roc` (float): Rate of Change, the percentage price change over N periods. - `symbol` (string): The analyzed symbol. - `period` (integer): The number of days analyzed. ## 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, maximum 5000 (more than the full series). **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` (float): 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=&strategy=` **Example**: `https://guavy.com/api/v1/trades/get-recent-buys?limit=4&skip=0&strategy=conservative` **Parameters**: - `limit` (integer): Specifies the maximum number of trades to return (default is 10, maximum 1000). - `skip` (integer): Specifies the number of buys to skip (default is 0). Consecutive pages never overlap: page until one comes back shorter than limit. - `strategy` (string): Specifies a risk profile to filter trades for. Either 'aggressive' or 'conservative'. Default is 'conservative'. Any other value, including a different capitalization, is treated as 'conservative' rather than rejected. **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=conservative` **Parameters**: - `limit` (integer): Specifies the maximum number of trades to return (default is 10, maximum 1000). - `skip` (integer): Specifies the number of sells to skip (default is 0). Consecutive pages never overlap: page until one comes back shorter than limit. - `strategy` (string): Specifies a risk profile to filter trades for. Either 'aggressive' or 'conservative'. Default is 'conservative'. Any other value, including a different capitalization, is treated as 'conservative' rather than rejected. **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?limit=&skip=&min_score=&strategy=` **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, maximum 1000). - `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'. Any other value, including a different capitalization, is treated as 'aggressive' rather than rejected. **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, maximum is 10; larger values are treated as 10). - `limit` (integer): Specifies the maximum number of trades to return (default is 50, maximum is 5000; larger values are treated as 5000). This endpoint is not paginated, so raise the limit to get the full history in one request. **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, maximum is 10; larger values are treated as 10). **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. ## REST — per-market (v2) Substitute a market for `{market}` in the paths below: `crypto`, `forex`, `commodities`, `stocks`. The response shape is identical across markets, and a route is served for all of them unless its own description says otherwise (the trend routes read collections crypto does not have, and 404 there). Examples are shown against `forex`. `/api/v2/crypto` additionally serves every `/api/v1` route listed above (the trade simulator, `get-market-summary`, `get-instrument-analysis`, `search-instruments`, `get-detail`), which the other markets have no source for. ## Instruments (v2) ### GET /api/v2/{market}/instruments/list-symbols List symbols for all available instruments with optional pagination. **Path**: `/api/v2/{market}/instruments/list-symbols?limit=&skip=` **Example** (forex): `https://guavy.com/api/v2/forex/instruments/list-symbols?limit=4&skip=0` **Parameters**: - `skip` (integer): Number of symbols to skip for pagination. Defaults to 0. Symbols are returned in storage order, which is stable between pages. - `limit` (integer): Maximum number of symbols to return. Defaults to 10, maximum 1000. To list every symbol, page with skip until a page comes back short. **Response Fields**: - `symbols` (array[string]): An array of instrument symbols. ### GET /api/v2/{market}/instruments/scorecard Retrieve the multi-factor scorecard for an instrument: the overall action and score, the strategy behind the call, and the simulated trading record supporting it. **Path**: `/api/v2/{market}/instruments/scorecard/` **Example** (forex): `https://guavy.com/api/v2/forex/instruments/scorecard/EUR` **Parameters**: - `symbol` (string) [Required]: The symbol of the instrument to fetch the scorecard for. **Response Fields**: - `symbol` (string): The instrument symbol. - `name` (string): The instrument's display name. - `icon` (string): URL to the instrument's icon image. An empty string where the market carries no icon metadata. - `action` (string): The current call: Buy, Sell, Hold, or Stay. - `strategy` (string): The strategy the action was derived from (aggressive or conservative). - `in_trade` (boolean): Whether the simulated position is currently open. - `score` (number): Overall multi-factor score. - `percentage_profit` (number): Profit of the simulated strategy, as a percentage. - `buy_and_hold_percentage` (number): Profit of simply buying and holding over the same period, for comparison. - `total_trades` (integer): Number of simulated trades behind the figures above. Null where none has run. - `trend` (string): Current trend direction (Up, Down, or Neutral). Null where unknown. - `trend_duration` (integer): How many days the current trend has run. Null where unknown. ## Newsroom (v2) ### GET /api/v2/{market}/newsroom/get-recent-briefs Fetch news briefs for a specific instrument using its symbol. **Path**: `/api/v2/{market}/newsroom/get-recent-briefs/?limit=` **Example** (forex): `https://guavy.com/api/v2/forex/newsroom/get-recent-briefs/EUR?limit=2` **Parameters**: - `symbol` (string) [Required]: The symbol to fetch news for. - `limit` (integer): The maximum number of news briefs to return, newest first. Defaults to 10, maximum 1000. **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` (number): A score, between 0 and 100, of the publisher's audience, credibility, and trust. - `date` (string): Date of publication. - `fud_fomo_score` (number): 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 instruments mentioned in the article. Each entry includes the following keys: - `asset` (string): Ticker symbol of the referenced instrument (e.g., EUR, GBP). - `confidence` (integer): The scoring model's confidence in this directional call, from 1 (low) to 10 (high). - `direction` (string): Predicted direction: bullish, bearish, or neutral. - `timeframe` (string): Horizon of the predicted move: short (hours to days) or long (weeks to months). - `sentiment` (integer): A sentiment score for the article between -5 (very negative) and +5 (very positive). - `speculation_score` (number): 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/v2/{market}/newsroom/search-briefs Search the headlines of an instrument's news briefs from the past 24 hours for a word or phrase. Results are newest first. **Path**: `/api/v2/{market}/newsroom/search-briefs/?keywords=&limit=` **Example** (forex): `https://guavy.com/api/v2/forex/newsroom/search-briefs/EUR?keywords=rate&limit=5` **Parameters**: - `symbol` (string) [Required]: Symbol to search briefs for (e.g. EUR, GBP). - `keywords` (string): Text to find in brief headlines, matched case-insensitively as one exact phrase: "rate cut" matches only headlines containing "rate cut", not ones with the two words apart. Defaults to empty (every brief from the past 24 hours). - `limit` (integer): The maximum number of briefs to return. Defaults to 20, maximum 1000. **Response Fields**: - `briefs` (array[object]): The array of matching news brief objects. Same structure as get-recent-briefs. ### GET /api/v2/{market}/newsroom/get-article Fetch a news article using its unique identifier (ID). IDs are returned in the 'Get Recent Briefs' route. **Path**: `/api/v2/{market}/newsroom/get-article/` **Example** (forex): `https://guavy.com/api/v2/forex/newsroom/get-article/68d11afe-46d5-4d22-9090-e3f4f82d0f5a` **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` (number): A score, between 0 and 100, of the publisher's audience, credibility, and trust. - `date` (string): Date of publication. - `fud_fomo_score` (number): 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 instruments mentioned in the article. Each entry includes the following keys: - `asset` (string): Ticker symbol of the referenced instrument (e.g., EUR, GBP). - `confidence` (integer): The scoring model's confidence in this directional call, from 1 (low) to 10 (high). - `direction` (string): Predicted direction: bullish, bearish, or neutral. - `timeframe` (string): Horizon of the predicted move: short (hours to days) or long (weeks to months). - `sentiment` (integer): A sentiment score for the article between -5 (very negative) and +5 (very positive). - `speculation_score` (number): 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. ## Sentiment (v2) ### GET /api/v2/{market}/sentiment/get-sentiment-history Retrieve sentiment time series data for an instrument over a specified number of days. **Path**: `/api/v2/{market}/sentiment/get-sentiment-history/?limit=` **Example** (forex): `https://guavy.com/api/v2/forex/sentiment/get-sentiment-history/EUR?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, newest first. Defaults to 100, maximum 1000. **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. ## Technical Analysis (v2) ### GET /api/v2/{market}/technical-analysis/get-price-history Retrieve daily historical price data for a given instrument symbol. Returns an array of daily price quotes with price, volume, and timestamp in milliseconds, oldest first. With no query parameters the FULL stored history is returned; `limit` returns only the most recent N points, and `from`/`to` are inclusive bounds in unix milliseconds (the range is applied first, then `limit` caps within it). Narrowing the request costs fewer tokens than the full series. **Path**: `/api/v2/{market}/technical-analysis/get-price-history/?limit=&from=&to=` **Example** (forex): `https://guavy.com/api/v2/forex/technical-analysis/get-price-history/EUR?limit=3` **Parameters**: - `symbol` (string) [Required]: The symbol of the instrument to fetch price history for (e.g. EUR, GBP). - `limit` (integer): Return only the most recent N daily points, maximum 3650. Omit it for the full series. - `from` (integer): Earliest point to include, as a unix timestamp in milliseconds (inclusive). - `to` (integer): Latest point to include, as a unix timestamp in milliseconds (inclusive). **Response Fields**: - `price_history` (array[object]): Array of daily price quote objects. - `price` (float): The closing price for the day. - `volume` (float): The 24-hour trading volume. - `timestamp` (integer): Unix timestamp in milliseconds. - `date` (string): Human-readable date (e.g. "Mar 25, 2024"). ### GET /api/v2/{market}/technical-analysis/get-indicators Compute key technical indicators from historical daily closing prices for a given symbol. Returns SMA, EMA, RSI, MACD, Bollinger Bands, Stochastic Oscillator, ATR, VWAP, OBV, Fibonacci Retracement, ADX, and ROC. SMA, Bollinger Bands, ATR, VWAP, OBV and Fibonacci are computed over the last `period` days; EMA uses `period` as its span over the full history; RSI (14), MACD, Stochastic (14), ADX (14) and ROC (12) use their standard lengths over the full history. No stored history carries daily highs and lows, so ATR, Stochastic and ADX are computed from closing prices. **Path**: `/api/v2/{market}/technical-analysis/get-indicators/?period=` **Example** (forex): `https://guavy.com/api/v2/forex/technical-analysis/get-indicators/EUR?period=30` **Parameters**: - `symbol` (string) [Required]: The symbol of the instrument to analyze (e.g. EUR, GBP). - `period` (integer): Number of days in the analysis window. Defaults to 30, minimum 2, maximum 365; a value outside that range is clamped, and the response's period field shows the value used. **Response Fields**: - `indicators` (object): Map of technical indicator values. - `sma` (float): Simple Moving Average over the period. - `ema` (float): Exponential Moving Average over the period. - `rsi` (float): Relative Strength Index (0-100). >70 overbought, <30 oversold. - `macd` (object): MACD with macd_line, signal_line, and histogram. - `bollinger_bands` (object): Upper, middle, and lower Bollinger Bands. - `stochastic_oscillator` (object): Stochastic %K and %D values. - `atr` (float): Average True Range, a volatility indicator. - `vwap` (float): Volume Weighted Average Price. - `obv` (float): On-Balance Volume. - `fibonacci_retracement` (object): Fibonacci levels (23.6%, 38.2%, 50%, 61.8%) with high and low. - `adx` (float): Average Directional Index (0-100). >25 strong trend, <20 weak/ranging. - `roc` (float): Rate of Change, the percentage price change over N periods. - `symbol` (string): The analyzed symbol. - `period` (integer): The number of days analyzed. ## Trades (v2) ### GET /api/v2/{market}/trades/get-current-trend Retrieve the current trend state for an instrument: direction, signal strength, the three moving averages, peak gain and loss, and how many days the trend has run. Not available for crypto, whose trend data is computed by the trade simulator instead — use get-trend-history there. **Path**: `/api/v2/{market}/trades/get-current-trend/` **Example** (forex): `https://guavy.com/api/v2/forex/trades/get-current-trend/EUR` **Parameters**: - `symbol` (string) [Required]: The symbol of the instrument to fetch the current trend for. **Response Fields**: - `current_trend` (object): The live trend state, with the following keys: - `trend` (string): Trend direction as stored, lowercase (for example "up" or "down"). - `signal_strength` (number): Raw signal strength as stored. The scale is not comparable across markets, so threshold it per market rather than assuming fixed bands. - `trend_duration_days` (integer): How many days the trend has run. - `started_at` (integer): When this trend episode started, a unix epoch in milliseconds. Each segment begins where the previous ended, and trend_duration_days is how long it ran. - `started_on` (string): The same instant as an ISO-8601 date. - `close` (number): Closing price at that point. - `short_term_average` (number): Short-term moving average. - `mid_term_average` (number): Mid-term moving average. - `long_term_average` (number): Long-term moving average. - `peak_gain` (number): Largest gain within the trend. - `peak_loss` (number): Largest loss within the trend. - `max_price` (number): Highest price within the trend. - `min_price` (number): Lowest price within the trend. - `max_price_day` (object): The highest-closing day: close, timestamp (ms), date, and trend. - `min_price_day` (object): The lowest-closing day: close, timestamp (ms), date, and trend. - `last_updated` (integer): When this market's trend data was last recomputed, as a unix timestamp in milliseconds. Returned once per response. ### GET /api/v2/{market}/trades/get-trend-segments Retrieve trend episodes for an instrument, newest first, each covering the period it ran. The newest segment is the trend still running, the same one get-current-trend returns, so count it once if you combine the two. This is not a daily time series — instruments carry a few dozen segments rather than thousands of points, which is why it is named apart from get-trend-history. Not available for crypto. **Path**: `/api/v2/{market}/trades/get-trend-segments/?limit=` **Example** (forex): `https://guavy.com/api/v2/forex/trades/get-trend-segments/EUR?limit=2` **Parameters**: - `symbol` (string) [Required]: The symbol of the instrument to fetch trend segments for. - `limit` (integer): The maximum number of segments to return, newest first. Defaults to 50, clamped to 1..500. **Response Fields**: - `trend_segments` (array[object]): Trend episodes, newest first (the first is the trend still running), each with the following keys: - `trend` (string): Trend direction as stored, lowercase (for example "up" or "down"). - `signal_strength` (number): Raw signal strength as stored. The scale is not comparable across markets, so threshold it per market rather than assuming fixed bands. - `trend_duration_days` (integer): How many days the trend has run. - `started_at` (integer): When this trend episode started, a unix epoch in milliseconds. Each segment begins where the previous ended, and trend_duration_days is how long it ran. - `started_on` (string): The same instant as an ISO-8601 date. - `close` (number): Closing price at that point. - `short_term_average` (number): Short-term moving average. - `mid_term_average` (number): Mid-term moving average. - `long_term_average` (number): Long-term moving average. - `peak_gain` (number): Largest gain within the trend. - `peak_loss` (number): Largest loss within the trend. - `max_price` (number): Highest price within the trend. - `min_price` (number): Lowest price within the trend. - `max_price_day` (object): The highest-closing day: close, timestamp (ms), date, and trend. - `min_price_day` (object): The lowest-closing day: close, timestamp (ms), date, and trend. - `last_updated` (integer): When this market's trend data was last recomputed, as a unix timestamp in milliseconds. Returned once per response.