{"openapi":"3.1.0","info":{"title":"HG Brasil Finance (BYOK) API","version":"0.1.0","description":"HG Brasil Finance (BYOK) lets an AI assistant read your own HG Brasil Finance data through the HG Brasil Finance API with a key you supply (HG Brasil API key). Read-only: 9 tools (get_market_overview, get_quotations, get_interest_rates, list_tickers, get_asset_price, get_ibovespa_top_gainers, get_ibovespa_top_losers, get_dividends, get_price_history). The BYOK key travels with each request, is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-hgbrasil-finance.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-hgbrasil-finance/docs"},"termsOfService":"https://connectorbay.com/byok-hgbrasil-finance/terms"},"servers":[{"url":"https://byok-hgbrasil-finance.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-hgbrasil-finance/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_market_overview":{"post":{"operationId":"get_market_overview","summary":"Get a Brazilian market snapshot in one answer: exchange rates against the real, stock index levels, Bitcoin prices on se","description":"Get a Brazilian market snapshot in one answer: exchange rates against the real, stock index levels, Bitcoin prices on several exchanges and the CDI and Selic rates. Use for \"What are the dollar rate, the Ibovespa and the Selic rate in Brazil today\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"array_limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Cut arrays in the answer to this many items (1 to 50).","title":"Array Limit"}},"title":"get_market_overviewArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_quotations":{"post":{"operationId":"get_quotations","summary":"Get only the currency rates against the real, the stock index levels and the Bitcoin prices (no interest rates). Use for","description":"Get only the currency rates against the real, the stock index levels and the Bitcoin prices (no interest rates). Use for \"What is the euro worth in reais right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_quotationsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_interest_rates":{"post":{"operationId":"get_interest_rates","summary":"Get the Brazilian CDI and Selic interest rates with the daily factor. Use for \"What are the current CDI and Selic rates\"","description":"Get the Brazilian CDI and Selic interest rates with the daily factor. Use for \"What are the current CDI and Selic rates\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_interest_ratesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_tickers":{"post":{"operationId":"list_tickers","summary":"List the ticker symbols the stock endpoints accept (stocks, real estate funds, BDRs, currencies, indices, crypto), optio","description":"List the ticker symbols the stock endpoints accept (stocks, real estate funds, BDRs, currencies, indices, crypto), optionally one asset type. Use for \"Which tickers can I query on HG Brasil Finance\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"only":{"anyOf":[{"enum":["stock","fii","fiagro","bdr","fip","fund"],"type":"string"},{"type":"null"}],"default":null,"description":"Only this asset type: stock, fii, fiagro, bdr, fip or fund.","title":"Only"}},"title":"list_tickersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_asset_price":{"post":{"operationId":"get_asset_price","summary":"Get price, daily change, volume, market cap, sector and dividend yield for assets by symbol (ticker symbols such as PETR","description":"Get price, daily change, volume, market cap, sector and dividend yield for assets by symbol (ticker symbols such as PETR4, HGLG11, USDBRL or BVSP; list_tickers shows the supported ones). Needs the Member Premium plan or higher; several symbols at once need Professional or Enterprise. Data can be delayed 15 to 60 minutes. Use for \"What is the price of PETR4 and the dollar rate in reais\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"symbol":{"description":"One symbol, or several separated by commas on Professional plans: ticker symbols such as PETR4, HGLG11, USDBRL or BVSP; list_tickers shows the supported ones.","maxLength":120,"title":"Symbol","type":"string"}},"required":["symbol"],"title":"get_asset_priceArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_ibovespa_top_gainers":{"post":{"operationId":"get_ibovespa_top_gainers","summary":"List the Ibovespa stocks with the biggest daily gains, with price, change and volume. Needs the Professional plan or hig","description":"List the Ibovespa stocks with the biggest daily gains, with price, change and volume. Needs the Professional plan or higher. Use for \"Which Ibovespa stocks are rising the most today\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"symbol":{"const":"get-high","description":"Fixed keyword that selects the biggest gainers.","title":"Symbol","type":"string"}},"required":["symbol"],"title":"get_ibovespa_top_gainersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_ibovespa_top_losers":{"post":{"operationId":"get_ibovespa_top_losers","summary":"List the Ibovespa stocks with the biggest daily losses, with price, change and volume. Needs the Professional plan or hi","description":"List the Ibovespa stocks with the biggest daily losses, with price, change and volume. Needs the Professional plan or higher. Use for \"Which Ibovespa stocks are falling the most today\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"symbol":{"const":"get-low","description":"Fixed keyword that selects the biggest losers.","title":"Symbol","type":"string"}},"required":["symbol"],"title":"get_ibovespa_top_losersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_dividends":{"post":{"operationId":"get_dividends","summary":"Get the dividend and yield payment history of stocks, real estate funds and BDRs by symbol: type, amount, approval date,","description":"Get the dividend and yield payment history of stocks, real estate funds and BDRs by symbol: type, amount, approval date, last trading date and payment date. Needs the Professional plan or higher. Use for \"When did ALUP4 last pay a dividend and how much\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"symbol":{"description":"One symbol or several separated by commas, for example ALUP4,VISC11.","maxLength":120,"title":"Symbol","type":"string"}},"required":["symbol"],"title":"get_dividendsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_price_history":{"post":{"operationId":"get_price_history","summary":"Get open, high, low, close and volume candles for assets, currencies and indices. Choose one date filter: days_ago, date","description":"Get open, high, low, close and volume candles for assets, currencies and indices. Choose one date filter: days_ago, date, or start_date with end_date. Needs a plan with historical finance data; the allowed range and symbol count depend on the plan. Use for \"Show hourly candles for Ibovespa and the dollar over the last 3 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"symbols":{"description":"One or more symbols separated by commas, for example BVSP,USDBRL,HGLG11 (limit depends on the plan).","maxLength":120,"title":"Symbols","type":"string"},"days_ago":{"anyOf":[{"maximum":3650,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Number of days back; 0 means today. Use only one of days_ago, date or start_date and end_date.","title":"Days Ago"},"date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"A single day (YYYY-MM-DD).","title":"Date"},"start_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"First day of a range (YYYY-MM-DD); use with end_date.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Last day of a range (YYYY-MM-DD).","title":"End Date"},"sample_by":{"anyOf":[{"enum":["1m","5m","15m","30m","1h","2h","1d","1M"],"type":"string"},{"type":"null"}],"default":null,"description":"Candle size: 1m, 5m, 15m, 30m, 1h, 2h, 1d or 1M (older data may not offer small sizes).","title":"Sample By"}},"required":["symbols"],"title":"get_price_historyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}