btgsolutions-dataservices-python-client 4.5.1__tar.gz → 4.7.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. {btgsolutions_dataservices_python_client-4.5.1/btgsolutions_dataservices_python_client.egg-info → btgsolutions_dataservices_python_client-4.7.0}/PKG-INFO +21 -15
  2. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/README.md +132 -113
  3. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/__init__.py +1 -1
  4. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/rest/__init__.py +1 -0
  5. btgsolutions_dataservices_python_client-4.7.0/btgsolutions_dataservices/rest/algohunter.py +73 -0
  6. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/rest/bulk_data.py +46 -2
  7. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0/btgsolutions_dataservices_python_client.egg-info}/PKG-INFO +22 -16
  8. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices_python_client.egg-info/SOURCES.txt +1 -0
  9. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/LICENSE +0 -0
  10. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/MANIFEST.in +0 -0
  11. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/config.py +0 -0
  12. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/exceptions.py +0 -0
  13. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/rest/alternative_data_catalog.py +0 -0
  14. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/rest/alternative_data_companies.py +0 -0
  15. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/rest/alternative_data_funds.py +0 -0
  16. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/rest/alternative_data_macro_markets.py +0 -0
  17. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/rest/alternative_data_metadata.py +0 -0
  18. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/rest/alternative_data_ownership.py +0 -0
  19. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/rest/alternative_data_people.py +0 -0
  20. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/rest/authenticator.py +0 -0
  21. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/rest/book_scope.py +0 -0
  22. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/rest/broker_analytics.py +0 -0
  23. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/rest/broker_reference.py +0 -0
  24. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/rest/company_data.py +0 -0
  25. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/rest/corporate_events.py +0 -0
  26. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/rest/dataservices_catalog.py +0 -0
  27. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/rest/hfn.py +0 -0
  28. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/rest/historical_candles.py +0 -0
  29. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/rest/historical_candles_crypto.py +0 -0
  30. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/rest/intraday_candles.py +0 -0
  31. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/rest/intraday_tick_data.py +0 -0
  32. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/rest/public_sources.py +0 -0
  33. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/rest/quotes.py +0 -0
  34. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/rest/reference_data.py +0 -0
  35. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/rest/stock_loan.py +0 -0
  36. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/rest/ticker_last_event.py +0 -0
  37. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/rest/ticker_last_event_polling.py +0 -0
  38. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/websocket/__init__.py +0 -0
  39. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/websocket/broker_analytics.py +0 -0
  40. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/websocket/hfn_websocket_client.py +0 -0
  41. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/websocket/market_data_feed.py +0 -0
  42. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/websocket/market_data_websocket_client.py +0 -0
  43. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices/websocket/websocket_default_functions.py +0 -0
  44. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices_python_client.egg-info/dependency_links.txt +0 -0
  45. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices_python_client.egg-info/requires.txt +0 -0
  46. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/btgsolutions_dataservices_python_client.egg-info/top_level.txt +0 -0
  47. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/pyproject.toml +0 -0
  48. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/requirements.txt +0 -0
  49. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/setup.cfg +0 -0
  50. {btgsolutions_dataservices_python_client-4.5.1 → btgsolutions_dataservices_python_client-4.7.0}/setup.py +0 -0
@@ -1,25 +1,12 @@
1
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.1
2
2
  Name: btgsolutions_dataservices_python_client
3
- Version: 4.5.1
3
+ Version: 4.7.0
4
4
  Summary: Python package containing several classes and data for extracting and manipulating market and trading data.
5
5
  Home-page: https://github.com/BTG-Pactual-Solutions/btgsolutions-dataservices-python-client
6
6
  Author: BTG Solutions Data Services powered by BTG Pactual Solutions
7
7
  Requires-Python: >=3.9,<3.15
8
8
  Description-Content-Type: text/markdown
9
9
  License-File: LICENSE
10
- Requires-Dist: pandas>=2.2.2
11
- Requires-Dist: websocket-client>=1.8.0
12
- Requires-Dist: PyJWT>=2.8.0
13
- Requires-Dist: requests>=2.32.3
14
- Requires-Dist: pyarrow>=17.0.0
15
- Dynamic: author
16
- Dynamic: description
17
- Dynamic: description-content-type
18
- Dynamic: home-page
19
- Dynamic: license-file
20
- Dynamic: requires-dist
21
- Dynamic: requires-python
22
- Dynamic: summary
23
10
 
24
11
  # BTG Solutions - Data Services
25
12
 
@@ -351,6 +338,15 @@ bulk_data.get_data(ticker='DI1F18', date='2017-01-02', data_type='trades')
351
338
  # bulk_data.get_data(ticker='PETR4', date='2025-05-07', data_type='instrument-status')
352
339
  ```
353
340
 
341
+ ##### Get Data With Billing Headers
342
+
343
+ ```python
344
+ import btgsolutions_dataservices as btg
345
+ bulk_data = btg.BulkData(api_key='YOUR_API_KEY')
346
+ df, billing_headers = bulk_data.get_data(ticker='PETR4', date='2025-06-20', data_type='trades', return_billing_headers=True)
347
+ # billing_headers = bulk_data.get_data(ticker='PETR4', date='2025-06-20', data_type='trades', dry_run=True)
348
+ ```
349
+
354
350
  ##### Security List
355
351
 
356
352
  ```python
@@ -755,3 +751,13 @@ ref = btg.ReferenceData(api_key='YOUR_API_KEY')
755
751
  ref.ticker_reference(tickers=['VALE3','PETR4'])
756
752
  ```
757
753
 
754
+ #### Algo Hunter
755
+
756
+ ```python
757
+ import btgsolutions_dataservices as btg
758
+ algohunter = AlgoHunter(api_key='YOUR_API_KEY')
759
+ algohunter.get_thermometer()
760
+ algohunter.get_recently_detected(ticker='PETR4')
761
+ ```
762
+
763
+
@@ -328,6 +328,15 @@ bulk_data.get_data(ticker='DI1F18', date='2017-01-02', data_type='trades')
328
328
  # bulk_data.get_data(ticker='PETR4', date='2025-05-07', data_type='instrument-status')
329
329
  ```
330
330
 
331
+ ##### Get Data With Billing Headers
332
+
333
+ ```python
334
+ import btgsolutions_dataservices as btg
335
+ bulk_data = btg.BulkData(api_key='YOUR_API_KEY')
336
+ df, billing_headers = bulk_data.get_data(ticker='PETR4', date='2025-06-20', data_type='trades', return_billing_headers=True)
337
+ # billing_headers = bulk_data.get_data(ticker='PETR4', date='2025-06-20', data_type='trades', dry_run=True)
338
+ ```
339
+
331
340
  ##### Security List
332
341
 
333
342
  ```python
@@ -494,71 +503,71 @@ company_data.interims(ticker='PETR4')
494
503
 
495
504
  ```python
496
505
  import btgsolutions_dataservices as btg
497
- company_data = btg.CompanyData(api_key='YOUR_API_KEY')
498
- company_data.all_financial_tables(ticker='PETR4')
499
- ```
500
-
501
- #### REST Technical Catalogs
502
-
503
- Technical endpoint descriptions for REST APIs are exported by the package so
504
- MCPs and other connectors can reuse the same source of truth instead of
505
- duplicating endpoint semantics locally.
506
-
507
- ```python
508
- from btgsolutions_dataservices.rest import (
509
- DATASERVICES_ENDPOINTS,
510
- DATASERVICES_ENDPOINT_RELATIONSHIPS,
511
- get_dataservices_tool_description,
512
- )
513
-
514
- print(get_dataservices_tool_description("get_quotes"))
515
- print(get_dataservices_tool_description("get_book_scope"))
516
- ```
517
-
518
- The Data Services catalog covers quotes, candles, intraday trades, last events,
519
- reference data, corporate events, company fundamental data, HFN news,
520
- stock-loan data, bulk market data, broker reference, broker analytics and
521
- book-scope endpoints. It documents parameters, endpoint relationships such as
522
- available-ticker discovery before market-data calls, broker-reference discovery
523
- before broker analytics, HFN filter discovery before news queries, corporate
524
- events before adjusted price analysis, and book-scope constraints for
525
- microstructure analysis.
526
-
527
- The REST catalogs also document cross-domain relationships between Public
528
- Sources and market-data services: company directory resolution feeds ticker
529
- reference, quotes, candles, stock-loan, broker analytics and book-scope tools;
530
- sector classification feeds peer-market comparisons; fund holdings feed
531
- underlying ticker market analysis; ownership/free-float feeds liquidity context;
532
- and disclosures, official notices, HFN news and corporate events feed event
533
- window analysis.
534
-
535
- #### Alternative Data - Metadata
536
-
537
- Technical endpoint descriptions for the public-sources alternative-data APIs are
538
- exported by the package so MCPs and other connectors can reuse the same source
539
- of truth:
540
-
541
- ```python
542
- from btgsolutions_dataservices.rest import (
543
- PUBLIC_SOURCES_ENDPOINTS,
544
- PUBLIC_SOURCES_ENDPOINT_RELATIONSHIPS,
545
- get_public_sources_tool_description,
546
- )
547
-
548
- print(get_public_sources_tool_description("get_company_board"))
549
- ```
550
-
551
- The catalog documents endpoint parameters, known data gaps, excluded endpoints,
552
- and relationships such as: company metadata resolving identifiers for governance
553
- and ownership calls; macro indicator metadata feeding macro observations; asset
554
- metadata feeding maximum-theoretical-margin calls; financial statement type
555
- metadata feeding statement queries; assemblies and ownership notices feeding
556
- notice summaries; and fund holdings/asset fund holders linking funds with
557
- company tickers.
558
-
559
- ```python
560
- import btgsolutions_dataservices as btg
561
- meta = btg.AlternativeDataMetadata(api_key='YOUR_API_KEY')
506
+ company_data = btg.CompanyData(api_key='YOUR_API_KEY')
507
+ company_data.all_financial_tables(ticker='PETR4')
508
+ ```
509
+
510
+ #### REST Technical Catalogs
511
+
512
+ Technical endpoint descriptions for REST APIs are exported by the package so
513
+ MCPs and other connectors can reuse the same source of truth instead of
514
+ duplicating endpoint semantics locally.
515
+
516
+ ```python
517
+ from btgsolutions_dataservices.rest import (
518
+ DATASERVICES_ENDPOINTS,
519
+ DATASERVICES_ENDPOINT_RELATIONSHIPS,
520
+ get_dataservices_tool_description,
521
+ )
522
+
523
+ print(get_dataservices_tool_description("get_quotes"))
524
+ print(get_dataservices_tool_description("get_book_scope"))
525
+ ```
526
+
527
+ The Data Services catalog covers quotes, candles, intraday trades, last events,
528
+ reference data, corporate events, company fundamental data, HFN news,
529
+ stock-loan data, bulk market data, broker reference, broker analytics and
530
+ book-scope endpoints. It documents parameters, endpoint relationships such as
531
+ available-ticker discovery before market-data calls, broker-reference discovery
532
+ before broker analytics, HFN filter discovery before news queries, corporate
533
+ events before adjusted price analysis, and book-scope constraints for
534
+ microstructure analysis.
535
+
536
+ The REST catalogs also document cross-domain relationships between Public
537
+ Sources and market-data services: company directory resolution feeds ticker
538
+ reference, quotes, candles, stock-loan, broker analytics and book-scope tools;
539
+ sector classification feeds peer-market comparisons; fund holdings feed
540
+ underlying ticker market analysis; ownership/free-float feeds liquidity context;
541
+ and disclosures, official notices, HFN news and corporate events feed event
542
+ window analysis.
543
+
544
+ #### Alternative Data - Metadata
545
+
546
+ Technical endpoint descriptions for the public-sources alternative-data APIs are
547
+ exported by the package so MCPs and other connectors can reuse the same source
548
+ of truth:
549
+
550
+ ```python
551
+ from btgsolutions_dataservices.rest import (
552
+ PUBLIC_SOURCES_ENDPOINTS,
553
+ PUBLIC_SOURCES_ENDPOINT_RELATIONSHIPS,
554
+ get_public_sources_tool_description,
555
+ )
556
+
557
+ print(get_public_sources_tool_description("get_company_board"))
558
+ ```
559
+
560
+ The catalog documents endpoint parameters, known data gaps, excluded endpoints,
561
+ and relationships such as: company metadata resolving identifiers for governance
562
+ and ownership calls; macro indicator metadata feeding macro observations; asset
563
+ metadata feeding maximum-theoretical-margin calls; financial statement type
564
+ metadata feeding statement queries; assemblies and ownership notices feeding
565
+ notice summaries; and fund holdings/asset fund holders linking funds with
566
+ company tickers.
567
+
568
+ ```python
569
+ import btgsolutions_dataservices as btg
570
+ meta = btg.AlternativeDataMetadata(api_key='YOUR_API_KEY')
562
571
  meta.get_company_directory(query='PETROBRAS', jurisdiction='BR')
563
572
  meta.list_companies(query='PETROBRAS', jurisdiction='BR')
564
573
  meta.list_etfs(query='BOVA')
@@ -581,27 +590,27 @@ companies = btg.AlternativeDataCompanies(api_key='YOUR_API_KEY')
581
590
  companies.list_companies(query='PETROBRAS', jurisdiction='BR')
582
591
  companies.get_board(company_id='VALE3', body='board')
583
592
  companies.get_governance_summary(company_id='ITUB4')
584
- companies.get_governance_history(company_id='PETR4', start_date='2023-01-01', end_date='2024-12-31')
585
- companies.get_governance_documents(company_id='PETR4', start_date='2024-01-01', end_date='2024-12-31')
586
- companies.get_governance_compensation(company_id='VALE3', fiscal_year='2024')
587
- companies.get_governance_related_party(company_id='ITUB4')
588
- companies.get_governance_beneficial_ownership(company_id='AAPL') # UK PSC / US SEC proxy data; not BR listed-company ownership
589
- companies.get_corporate_registry(company_id='PETR4', direction='partners')
590
- companies.get_corporate_registry(company_id='PETR4', direction='investees')
591
- companies.get_insider_trades(company_id='AAPL', start_date='2024-01-01', end_date='2024-12-31')
592
- companies.get_board_changes(company_id='VALE3', event='elected')
593
+ companies.get_governance_history(company_id='PETR4', start_date='2023-01-01', end_date='2024-12-31')
594
+ companies.get_governance_documents(company_id='PETR4', start_date='2024-01-01', end_date='2024-12-31')
595
+ companies.get_governance_compensation(company_id='VALE3', fiscal_year='2024')
596
+ companies.get_governance_related_party(company_id='ITUB4')
597
+ companies.get_governance_beneficial_ownership(company_id='AAPL') # UK PSC / US SEC proxy data; not BR listed-company ownership
598
+ companies.get_corporate_registry(company_id='PETR4', direction='partners')
599
+ companies.get_corporate_registry(company_id='PETR4', direction='investees')
600
+ companies.get_insider_trades(company_id='AAPL', start_date='2024-01-01', end_date='2024-12-31')
601
+ companies.get_board_changes(company_id='VALE3', event='elected')
593
602
  companies.get_assemblies(company_id='PINE4')
594
- companies.get_financial_statements(company_id='PETR4', statement='income_statement', quarter='4T24')
595
- companies.get_financial_notes(company_id='VALE3', quarter='4T24')
596
- companies.get_disclosures(company_id='PETR4', document_type='repurchase')
597
- companies.get_disclosures(company_id='PETR4', document_type='insider')
598
- ```
599
-
600
- For Brazilian governance endpoints, current board and summary responses prefer
601
- the latest raw FRE filing when available. Returned governance summaries can
602
- include `latest_reference_date`, `latest_version`, `latest_document_id` and
603
- `structure_source`; alternate B3 tickers/units such as `BPAC11` can resolve to
604
- the underlying listed company when covered by the source metadata.
603
+ companies.get_financial_statements(company_id='PETR4', statement='income_statement', quarter='4T24')
604
+ companies.get_financial_notes(company_id='VALE3', quarter='4T24')
605
+ companies.get_disclosures(company_id='PETR4', document_type='repurchase')
606
+ companies.get_disclosures(company_id='PETR4', document_type='insider')
607
+ ```
608
+
609
+ For Brazilian governance endpoints, current board and summary responses prefer
610
+ the latest raw FRE filing when available. Returned governance summaries can
611
+ include `latest_reference_date`, `latest_version`, `latest_document_id` and
612
+ `structure_source`; alternate B3 tickers/units such as `BPAC11` can resolve to
613
+ the underlying listed company when covered by the source metadata.
605
614
 
606
615
  #### Alternative Data - People
607
616
 
@@ -616,14 +625,14 @@ people.get_appointments(person_id='slug:Jean Paul Lemann', group_by='company')
616
625
 
617
626
  ```python
618
627
  import btgsolutions_dataservices as btg
619
- funds = btg.AlternativeDataFunds(api_key='YOUR_API_KEY')
620
- funds.list_etfs(query='BOVA')
621
- funds.get_holdings(fund_id='BOVA11', reference_date='2024-12-31')
622
- funds.get_exposures(fund_id='BOVA11', exposure_type='asset_class')
623
- funds.get_history(fund_id='BOVA11', start_date='2024-01-01', end_date='2024-12-31')
624
- funds.get_lookthrough(fund_id='BOVA11')
625
- # Manager aggregation requires an exact covered manager CNPJ/name, not ETF issuer slugs, ETF tickers or fund CNPJs.
626
- # funds.get_manager_aggregate_holdings(manager_id='...')
628
+ funds = btg.AlternativeDataFunds(api_key='YOUR_API_KEY')
629
+ funds.list_etfs(query='BOVA')
630
+ funds.get_holdings(fund_id='BOVA11', reference_date='2024-12-31')
631
+ funds.get_exposures(fund_id='BOVA11', exposure_type='asset_class')
632
+ funds.get_history(fund_id='BOVA11', start_date='2024-01-01', end_date='2024-12-31')
633
+ funds.get_lookthrough(fund_id='BOVA11')
634
+ # Manager aggregation requires an exact covered manager CNPJ/name, not ETF issuer slugs, ETF tickers or fund CNPJs.
635
+ # funds.get_manager_aggregate_holdings(manager_id='...')
627
636
  ```
628
637
 
629
638
  #### Alternative Data - Ownership
@@ -640,16 +649,16 @@ ownership.get_notice_summary(url='https://www.rad.cvm.gov.br/ENETWEB/frmGerencia
640
649
  ownership.get_ownership_control_group(company_id='VALE3')
641
650
  ownership.get_ownership_free_float(company_id='PETR4')
642
651
  ownership.get_shareholder_holdings(shareholder_id='00.000.000/0001-91')
643
- ownership.get_institutional_holders(identifier='VALE3')
644
- ownership.get_fund_holders(identifier='PETR4', identifier_type='b3_ticker')
645
- ```
646
-
647
- For Brazilian ownership/free-float endpoints, current control and free-float
648
- responses use the latest FRE source document/version for the selected reference
649
- date when available. Repeated older source documents are deduplicated where
650
- possible, while distinct rows for the same holder across classes, roles or
651
- ownership categories are preserved. Zero free-float or independence percentages
652
- can be valid source values, not missing data.
652
+ ownership.get_institutional_holders(identifier='VALE3')
653
+ ownership.get_fund_holders(identifier='PETR4', identifier_type='b3_ticker')
654
+ ```
655
+
656
+ For Brazilian ownership/free-float endpoints, current control and free-float
657
+ responses use the latest FRE source document/version for the selected reference
658
+ date when available. Repeated older source documents are deduplicated where
659
+ possible, while distinct rows for the same holder across classes, roles or
660
+ ownership categories are preserved. Zero free-float or independence percentages
661
+ can be valid source values, not missing data.
653
662
 
654
663
  #### Alternative Data - Macro & Markets
655
664
 
@@ -657,16 +666,16 @@ can be valid source values, not missing data.
657
666
  import btgsolutions_dataservices as btg
658
667
  macro = btg.AlternativeDataMacroMarkets(api_key='YOUR_API_KEY')
659
668
  macro.get_macro_indicators(indicator='selic')
660
- macro.get_macro_indicators(indicator='ipca_contributions', start_date='2024-01', end_date='2024-12')
661
- macro.get_macro_indicators(indicator='gdp', type='yoy')
662
- macro.get_macro_indicators(indicator='comexstat', year='2024', state='SP')
663
- macro.get_macro_indicators(indicator='comexstat', aggregate='states', start_date='2024-01', end_date='2024-12')
664
- macro.get_macro_indicators(indicator='comexstat', aggregate='timeline', group_by='country', state='SP')
665
- macro.get_macro_indicators(indicator='rreo', year='2024', period='6')
666
- macro.get_maximum_theoretical_margin(asset='PETR4', report_date='2024-12-31')
667
- macro.get_dpmfi(start_date='2024-01', end_date='2024-12', status='dados_oficiais')
668
- macro.get_dpmfi(snapshot_date='2026-06-24', limit=10) # reproducible scoped snapshot
669
- macro.get_dpmfi_composition(bond_type='IPCA')
669
+ macro.get_macro_indicators(indicator='ipca_contributions', start_date='2024-01', end_date='2024-12')
670
+ macro.get_macro_indicators(indicator='gdp', type='yoy')
671
+ macro.get_macro_indicators(indicator='comexstat', year='2024', state='SP')
672
+ macro.get_macro_indicators(indicator='comexstat', aggregate='states', start_date='2024-01', end_date='2024-12')
673
+ macro.get_macro_indicators(indicator='comexstat', aggregate='timeline', group_by='country', state='SP')
674
+ macro.get_macro_indicators(indicator='rreo', year='2024', period='6')
675
+ macro.get_maximum_theoretical_margin(asset='PETR4', report_date='2024-12-31')
676
+ macro.get_dpmfi(start_date='2024-01', end_date='2024-12', status='dados_oficiais')
677
+ macro.get_dpmfi(snapshot_date='2026-06-24', limit=10) # reproducible scoped snapshot
678
+ macro.get_dpmfi_composition(bond_type='IPCA')
670
679
  ```
671
680
 
672
681
  `AlternativeDataMacroMarkets` exposes the public-sources market-data endpoint for B3 maximum theoretical margin. The direct market-data `investor-categories` endpoint is intentionally not exposed in this package.
@@ -732,3 +741,13 @@ ref = btg.ReferenceData(api_key='YOUR_API_KEY')
732
741
  ref.ticker_reference(tickers=['VALE3','PETR4'])
733
742
  ```
734
743
 
744
+ #### Algo Hunter
745
+
746
+ ```python
747
+ import btgsolutions_dataservices as btg
748
+ algohunter = AlgoHunter(api_key='YOUR_API_KEY')
749
+ algohunter.get_thermometer()
750
+ algohunter.get_recently_detected(ticker='PETR4')
751
+ ```
752
+
753
+
@@ -1,4 +1,4 @@
1
- __version__ = "4.5.1"
1
+ __version__ = "4.7.0"
2
2
 
3
3
  from .websocket import *
4
4
  from .rest import *
@@ -16,6 +16,7 @@ from .ticker_last_event_polling import TickerLastEventPolling
16
16
  from .broker_reference import BrokerReference
17
17
  from .book_scope import BookScope
18
18
  from .broker_analytics import BrokerAnalytics
19
+ from .algohunter import AlgoHunter
19
20
  from .alternative_data_metadata import AlternativeDataMetadata
20
21
  from .alternative_data_companies import AlternativeDataCompanies
21
22
  from .alternative_data_people import AlternativeDataPeople
@@ -0,0 +1,73 @@
1
+ from typing import List
2
+ from ..exceptions import BadResponse
3
+ import requests
4
+ from ..config import url_api_v1
5
+ from .authenticator import Authenticator
6
+
7
+
8
+ class AlgoHunter:
9
+ """
10
+ This class provides access to the AlgoHunter analytics endpoints.
11
+
12
+ * Main use case:
13
+
14
+ >>> from btgsolutions_dataservices import AlgoHunter
15
+ >>> algohunter = AlgoHunter(api_key='YOUR_API_KEY')
16
+ >>> algohunter.get_thermometer()
17
+ >>> algohunter.get_recently_detected(ticker='PETR4')
18
+
19
+ Parameters
20
+ ----------------
21
+ api_key: str
22
+ User identification key.
23
+ Field is required.
24
+ """
25
+
26
+ _BASE_PATH = f"{url_api_v1}/marketdata/analytics/algohunter"
27
+
28
+ def __init__(self, api_key: str):
29
+ self.api_key = api_key
30
+ self.__authenticator = Authenticator(self.api_key)
31
+
32
+ def get_thermometer(self) -> List[dict]:
33
+ """
34
+ Returns thermometer values for assets with algorithmic activity
35
+ detected in the last 5 minutes.
36
+ """
37
+ url = f"{self._BASE_PATH}/thermometer"
38
+ headers = {"authorization": f"Bearer {self.__authenticator.token}"}
39
+ response = requests.get(url, headers=headers, timeout=30)
40
+
41
+ if response.status_code != 200:
42
+ self._raise_error(response)
43
+
44
+ return response.json()
45
+
46
+ def get_recently_detected(self, ticker: str) -> dict:
47
+ """
48
+ Returns algorithms likely running in the last few minutes
49
+ for a given ticker, grouped by side (buyer/seller) and broker.
50
+
51
+ Parameters
52
+ ----------
53
+ ticker : str
54
+ Ticker symbol. Required.
55
+
56
+ """
57
+ url = f"{self._BASE_PATH}/recently-detected"
58
+ headers = {"authorization": f"Bearer {self.__authenticator.token}"}
59
+ response = requests.get(url, params={"ticker": ticker}, headers=headers, timeout=30)
60
+
61
+ if response.status_code != 200:
62
+ self._raise_error(response)
63
+
64
+ return response.json()
65
+
66
+ @staticmethod
67
+ def _raise_error(response):
68
+ try:
69
+ error_body = response.json()
70
+ detail = error_body.get("detail", error_body.get("error", response.text))
71
+ except Exception:
72
+ detail = response.text
73
+ raise BadResponse(f"Error {response.status_code}: {detail}")
@@ -1,5 +1,5 @@
1
1
  import os
2
- from typing import Optional
2
+ from typing import Dict, Optional
3
3
  from ..exceptions import BadResponse
4
4
  import requests
5
5
  from ..config import url_api_v1, url_apis, url_apis_v3
@@ -9,6 +9,31 @@ import pandas as pd
9
9
  from io import BytesIO
10
10
  import pyarrow.parquet as pq
11
11
 
12
+ BILLING_HEADER_NAMES = (
13
+ "X-Dry-Run",
14
+ "X-Billable",
15
+ "X-Requested-Rows",
16
+ "X-Billing-Period",
17
+ "X-Charge-Type",
18
+ "X-Contract-Type",
19
+ "X-Price-Per-Million-Ticks-BRL",
20
+ "X-Billing-Amount-BRL",
21
+ "X-Current-Month-Billing-Amount-BRL",
22
+ "X-Monthly-Billing-Limit-BRL",
23
+ "X-Remaining-Monthly-Billing-Amount-BRL",
24
+ "X-Would-Exceed-Limit",
25
+ "X-License-Active-Before-Access",
26
+ "X-Leased-Until",
27
+ )
28
+
29
+
30
+ def extract_billing_headers(headers) -> Dict[str, str]:
31
+ return {
32
+ header_name: headers.get(header_name)
33
+ for header_name in BILLING_HEADER_NAMES
34
+ if headers.get(header_name) is not None
35
+ }
36
+
12
37
  def download_compressed_file(url, headers):
13
38
 
14
39
  with requests.get(url, headers=headers, stream=True) as response:
@@ -164,7 +189,9 @@ class BulkData:
164
189
  ticker:str,
165
190
  date:str,
166
191
  data_type:str='trades',
167
- raw_data:bool=False
192
+ raw_data:bool=False,
193
+ return_billing_headers:bool=False,
194
+ dry_run:bool=False,
168
195
  ):
169
196
  """
170
197
  This method provides tick-by-tick market data (trades, book events, book snapshots) for a given ticker and date.
@@ -184,11 +211,24 @@ class BulkData:
184
211
  raw_data: bool
185
212
  If false, returns data in a dataframe. If true, returns raw data.
186
213
  Field is not required. Default: False.
214
+ return_billing_headers: bool
215
+ If true, returns billing headers with the data.
216
+ Field is not required. Default: False.
217
+ dry_run: bool
218
+ If true, checks billing quota without downloading data and returns billing headers.
219
+ Field is not required. Default: False.
187
220
  """
188
221
 
189
222
  url = f"{url_apis}/marketdata/bulkdata/{data_type}?ticker={ticker}&date={date}"
223
+ if dry_run:
224
+ url = f"{url}&dry_run=true"
190
225
 
191
226
  response = requests.request("GET", url, headers=self.headers)
227
+ billing_headers = extract_billing_headers(response.headers)
228
+
229
+ if response.status_code == 204 and dry_run:
230
+ return billing_headers
231
+
192
232
  if response.status_code == 200:
193
233
 
194
234
  try:
@@ -198,6 +238,8 @@ class BulkData:
198
238
  parquet_file = pq.ParquetFile(parquet_buffer)
199
239
  df = parquet_file.read().to_pandas()
200
240
 
241
+ if return_billing_headers:
242
+ return df, billing_headers
201
243
  return df
202
244
 
203
245
  else:
@@ -207,6 +249,8 @@ class BulkData:
207
249
  # Write the content to a file
208
250
  with open(filename, 'wb') as file:
209
251
  file.write(response.content)
252
+ if return_billing_headers:
253
+ return billing_headers
210
254
  return None
211
255
 
212
256
  except Exception as e:
@@ -1,25 +1,12 @@
1
- Metadata-Version: 2.4
2
- Name: btgsolutions_dataservices_python_client
3
- Version: 4.5.1
1
+ Metadata-Version: 2.1
2
+ Name: btgsolutions-dataservices-python-client
3
+ Version: 4.7.0
4
4
  Summary: Python package containing several classes and data for extracting and manipulating market and trading data.
5
5
  Home-page: https://github.com/BTG-Pactual-Solutions/btgsolutions-dataservices-python-client
6
6
  Author: BTG Solutions Data Services powered by BTG Pactual Solutions
7
7
  Requires-Python: >=3.9,<3.15
8
8
  Description-Content-Type: text/markdown
9
9
  License-File: LICENSE
10
- Requires-Dist: pandas>=2.2.2
11
- Requires-Dist: websocket-client>=1.8.0
12
- Requires-Dist: PyJWT>=2.8.0
13
- Requires-Dist: requests>=2.32.3
14
- Requires-Dist: pyarrow>=17.0.0
15
- Dynamic: author
16
- Dynamic: description
17
- Dynamic: description-content-type
18
- Dynamic: home-page
19
- Dynamic: license-file
20
- Dynamic: requires-dist
21
- Dynamic: requires-python
22
- Dynamic: summary
23
10
 
24
11
  # BTG Solutions - Data Services
25
12
 
@@ -351,6 +338,15 @@ bulk_data.get_data(ticker='DI1F18', date='2017-01-02', data_type='trades')
351
338
  # bulk_data.get_data(ticker='PETR4', date='2025-05-07', data_type='instrument-status')
352
339
  ```
353
340
 
341
+ ##### Get Data With Billing Headers
342
+
343
+ ```python
344
+ import btgsolutions_dataservices as btg
345
+ bulk_data = btg.BulkData(api_key='YOUR_API_KEY')
346
+ df, billing_headers = bulk_data.get_data(ticker='PETR4', date='2025-06-20', data_type='trades', return_billing_headers=True)
347
+ # billing_headers = bulk_data.get_data(ticker='PETR4', date='2025-06-20', data_type='trades', dry_run=True)
348
+ ```
349
+
354
350
  ##### Security List
355
351
 
356
352
  ```python
@@ -755,3 +751,13 @@ ref = btg.ReferenceData(api_key='YOUR_API_KEY')
755
751
  ref.ticker_reference(tickers=['VALE3','PETR4'])
756
752
  ```
757
753
 
754
+ #### Algo Hunter
755
+
756
+ ```python
757
+ import btgsolutions_dataservices as btg
758
+ algohunter = AlgoHunter(api_key='YOUR_API_KEY')
759
+ algohunter.get_thermometer()
760
+ algohunter.get_recently_detected(ticker='PETR4')
761
+ ```
762
+
763
+
@@ -8,6 +8,7 @@ btgsolutions_dataservices/__init__.py
8
8
  btgsolutions_dataservices/config.py
9
9
  btgsolutions_dataservices/exceptions.py
10
10
  btgsolutions_dataservices/rest/__init__.py
11
+ btgsolutions_dataservices/rest/algohunter.py
11
12
  btgsolutions_dataservices/rest/alternative_data_catalog.py
12
13
  btgsolutions_dataservices/rest/alternative_data_companies.py
13
14
  btgsolutions_dataservices/rest/alternative_data_funds.py