Metadata-Version: 2.4
Name: quantjourney-api
Version: 0.1.4
Summary: Official Python SDK for QuantJourney market data, research, and analytics APIs.
Author: QuantJourney
License-Expression: LicenseRef-Proprietary
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: quantjourney-common-sdk<0.2,>=0.1.1
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Provides-Extra: frames
Requires-Dist: pandas>=2.0.0; extra == "frames"

# quantjourney-api

Python SDK for the public/product `qj-api` contract.

Canonical package metadata:

| Field | Value |
| --- | --- |
| Repository | `_repo_qj_api_sdk` |
| Distribution | `quantjourney-api` |
| Python import | `qj.api` |
| Runtime client | `QJ` |
| Backend boundary | `qj-api` / `https://api.quantjourney.cloud` |
| Version | `0.1.4` |
| Git tag | `api-v0.1.4` |

`quantjourney-api` is the public product/API SDK. The `quantjourney` umbrella
package lives in `packages/quantjourney` and installs `quantjourney-api`.

```python
from qj.api import QJ, QuantJourneyAPI

qj = QJ.from_env()
health = qj.health()
capabilities = qj.capabilities()

# Provider connectors through qj-api
profile = qj.fmp.get_company_profile(symbol="NVDA")
gdp = qj.fred.get_series(series_id="GDP")
filings = qj.sec.get_recent_filings(limit=5)
trades = qj.massive.get_stock_trades(ticker="AAPL", limit=100)
legacy_quotes = qj.polygon.get_stock_quotes(ticker="AAPL", limit=100)
cpi = qj.tradingeconomics.get_historical_indicators(
    country="United States",
    indicator="Consumer Price Index CPI",
)
macro_revision = qj.dbnomics.get_series(
    provider_code="ECB",
    dataset_code="EXR",
    series_code="D.USD.EUR.SP00.A",
    revision="<commit-sha>",
)

# Research-source expansion (requires a backend with these routes deployed)
approvals = qj.openfda.get_drug_approvals(search='sponsor_name:"PFIZER"', limit=5)
attention = qj.apewisdom.get_mentions(filter="all-stocks")
pageviews = qj.wikimedia.get_pageviews(article="Apple_Inc.")
fear_greed = qj.alternative.get_fear_greed(limit=30)
dvol = qj.deribit.get_dvol(currency="BTC")
fees = qj.defillama.get_protocol_fees(protocol_slug="aave", data_type="dailyRevenue")
put_call = qj.cboe.get_put_call_ratios()
positioning = qj.cftc.get_net_positioning(symbol="VIX")
morpho_markets = qj.morpho.get_markets(chain_ids=[8453], limit=5)
bund_yield = qj.bundesbank.get_series()

# Provider-agnostic domain routes
routes = qj.domains.list()
prices = qj.domains.equity.pricing.get_historical_prices(symbol="NVDA")

# Product API surfaces
analytics = qj.analytics.registry()
ratios = qj.ratios.available(source="eod")
indicators = qj.technical.available()

# Compatibility aliases
qj2 = QuantJourneyAPI.from_env()
```

Local smoke from this checkout:

```bash
python scripts/qj_api_smoke.py --env .env
python scripts/endpoint_matrix.py --env .env
python scripts/endpoint_matrix.py --env .env --list
python scripts/endpoint_matrix.py --env .env --group connectors --allow-failures
python scripts/endpoint_matrix.py --env .env --group connector_examples --include-connector-examples --allow-failures
python scripts/connector_matrix.py --env .env
```

`scripts/connectors.json` stores one smoke example per connector. The endpoint
matrix verifies every connector route; `connector_matrix.py` runs the examples
and prints a compact result table.

The September research-source expansion adds `openfda`, `apewisdom`,
`wikimedia`, `alternative`, `quiver`, `ember`, `opensky`, `manifold`, `deribit`,
`mempool`, `blockscout` and `blockchain`, plus DefiLlama fee/revenue methods.
Calls use the normal QJ tenant/scopes and credentials. Configure upstream
Quiver and Ember keys in QJ Data Sources; do not send them as SDK method
parameters. Provider data remains in the response's `value` envelope.

Environment variables:

| Variable | Purpose |
| --- | --- |
| `QJ_API_URL` | qj-api base URL, default `https://api.quantjourney.cloud` |
| `QJ_API_TOKEN` | bearer token |
| `QJ_AUTH_URL` | qj-auth base URL for token exchange |
| `QJ_API_KEY` | `QJ_live_*` API key used to mint `QJ_API_TOKEN` |
| `QJ_API_CLIENT_ID` | service account client id for `client_credentials` |
| `QJ_API_CLIENT_SECRET` | `QJ_svc_*` service secret for `client_credentials` |
| `QJ_API_TENANT_ID` | optional tenant projection |
| `QJ_API_TEAM_ID` | optional team projection |

Install from PyPI:

```bash
pip install quantjourney-api==0.1.4
```

`quantjourney-common-sdk` is installed automatically as a dependency. Local
development can still use editable path installs for sibling checkouts.

The new surface keeps the smaller `qj.api` namespace, uses
`quantjourney-common-sdk` for
auth/transport, exposes dynamic qj-api connector clients, and keeps warehouse
data-plane concerns in `quantjourney-data`.

## Release history

This history covers `quantjourney-api` (`qj.api`). The older `quantjourney`
distribution has its own version history. Dates below are the original PyPI
publication dates; these notes were added retrospectively from the release tags.

<!-- Keep this section aligned with CHANGELOG.md; README is the PyPI description. -->

### 0.1.4 — 2026-09-08

- Added Morpho Blue lending-market data and official Deutsche Bundesbank time series.
- Added market-wide CBOE put/call ratios and derived CFTC net positioning.

### 0.1.3 — 2026-09-06

- Added named SDK connector clients for openFDA and Quiver, covering FDA records and political disclosures through QJ API.
- Added ApeWisdom, Wikimedia and Alternative.me clients for market attention, pageviews and crypto sentiment.
- Added Ember, OpenSky and Manifold clients for electricity data, aviation activity and prediction markets.
- Added Deribit, mempool.space, Blockscout and Blockchain.com clients for crypto volatility and on-chain data.
- Added connector smoke examples and forwarding tests; documented the new DefiLlama fee/revenue methods with an SDK example.
- Documented QJ tenant/scope requirements and Data Sources configuration: Quiver and Ember require provider keys, while openFDA supports an optional key.

### 0.1.2 — 2026-08-16

- Added named SDK clients and smoke examples for USAspending, SAM.gov and Congress.gov.
- Added named Massive and Polygon clients, with examples for stock trades and quotes.
- Added TradingEconomics access and a historical macro-indicator example using provider keys configured in QJ.
- Added forwarding regression coverage for the new clients and existing DBnomics series/revision routes; updated usage examples.

### 0.1.1 — 2026-07-11

- First PyPI release of the separate `quantjourney-api` distribution, using the `qj.api` namespace and `QJ` client.
- Included dynamic provider clients, domain discovery/calls and product API clients for analytics, Backtester, universe, ratios, technical indicators and insider data.
- Used `quantjourney-common-sdk` for shared authentication and HTTP transport, including bearer tokens, user API keys, service credentials and tenant/team context.
- Included connector and endpoint smoke scripts and configured GitHub Actions trusted publishing to PyPI.
