# QuantJourney Agents

> Machine-payable, evidence-backed financial research service for agents.

Bounded queries: public_and_caller_data
Generic A2A task delegation: preview_disabled
A2A version: 1.0

## Anonymous public MCP

Connect an MCP client to https://agents.quantjourney.cloud/mcp using Streamable HTTP. No OAuth token,
API key or wallet is required for these 34 reviewed read-only tools:
- get_company_snapshot
- get_company_snapshots
- compare_companies
- get_earnings_preview
- get_earnings_recap
- resolve_sec_company
- get_latest_sec_filing
- get_sec_company_facts
- get_security_history
- screen_securities
- get_sec_filing_delta
- get_insider_activity
- get_short_interest_state
- get_security_technicals
- get_market_regime
- get_treasury_yield_curve
- get_overnight_rates
- normalize_portfolio
- simulate_trade
- get_portfolio_exposure
- get_portfolio_volatility
- get_portfolio_var_cvar
- get_portfolio_drawdown
- get_portfolio_benchmark_risk
- get_portfolio_factor_exposure
- get_portfolio_liquidity
- get_portfolio_events
- get_portfolio_signals
- run_portfolio_scenario
- get_portfolio_position_risk
- get_portfolio_performance
- get_portfolio_correlations
- optimize_portfolio
- simulate_portfolio

Read these MCP resources once per session to plan calls, interpret units and understand access:
- qj://finance/manifest
- qj://finance/caller-market-data
- qj://finance/metric-dictionary
- qj://finance/coverage-and-freshness
- qj://finance/scenarios
- qj://finance/limits-and-access

The manifest lists both the anonymous MCP tools and all 35 canonical
REST/A2A products with their independent authentication, prices and payment protocols. The MCP
projection is a zero-price preview channel and does not change REST/A2A OAuth or x402 policy. It
uses the same QueryDefinition registry, QueryService, Redis cache, rate limits and capacity
controls as the HTTP bounded-query routes; it is not a second data backend.

## Required discovery order

1. GET https://agents.quantjourney.cloud/.well-known/agent-card.json
2. Select one of the 35 live skills in the Agent Card or /openapi.json.
3. GET https://agents.quantjourney.cloud/.well-known/oauth-protected-resource
4. POST https://agents.quantjourney.cloud/oauth/register with scope=agents:query and a unique Idempotency-Key;
   retain the returned secret.
5. POST https://agents.quantjourney.cloud/oauth/token with grant_type=client_credentials and scope=agents:query.
6. POST https://agents.quantjourney.cloud/v1/query/company-snapshot-lite for the free, rate-limited ticker snapshot.
7. POST https://agents.quantjourney.cloud/v1/query/earnings-recap with OAuth and satisfy its advertised
   Base mainnet x402 payment before the successful retry.
8. POST https://agents.quantjourney.cloud/v1/query/congress-gov-signals for the free, rate-limited ticker query.

Pricing and public telemetry:
- https://agents.quantjourney.cloud/v1/pricing
- https://agents.quantjourney.cloud/.well-known/x402 (compatibility manifest; runtime HTTP 402 is authoritative)
- https://agents.quantjourney.cloud/.well-known/agent-registration.json (experimental ERC-8004 Draft identity)
- https://agents.quantjourney.cloud/v1/telemetry/public
- https://agents.quantjourney.cloud/v1/queries/public (recent query type, state and time only)
- https://agents.quantjourney.cloud/v1/releases/current (current allowlisted release projection)
- https://agents.quantjourney.cloud/agents/ (browser projection)
- https://agents.quantjourney.cloud/queries/ (browser query trace)
- https://agents.quantjourney.cloud/changelog/ (public release history)

Executable bounded queries (generated from the runtime query registry):
- POST /v1/query/company-snapshot-lite: Return a free, bounded factual ticker snapshot with price, selected metrics, freshness and explicit coverage gaps. Authentication=none; price=$0.00.
- POST /v1/query/earnings-preview: Prepare an evidence-backed earnings preview with consensus, revisions, dispersion, historical surprises, valuation context and explicit review questions. Authentication=oauth2_client_credentials; price=$0.00.
- POST /v1/query/earnings-recap: Reconcile the latest reported earnings with consensus, estimate changes, adjusted-close reactions, SPY-adjusted CAR and explicit thesis-review questions. Authentication=oauth2_client_credentials; price=$0.01.
- POST /v1/query/congress-gov-signals: Combine congressional disclosures and government-contract evidence with disclosure-lag warnings. Authentication=oauth2_client_credentials; price=$0.00.
- POST /v1/query/sec-company-identity: Resolve a ticker or company name to official SEC identity and exchange fields. Authentication=none; price=$0.00.
- POST /v1/query/sec-latest-filing: Return the latest official SEC submission for a ticker and bounded form type. Authentication=oauth2_client_credentials; price=$0.01.
- POST /v1/query/sec-company-facts-compact: Project selected current SEC XBRL facts into a small evidence envelope. Authentication=oauth2_client_credentials; price=$0.02.
- POST /v1/query/gleif-entity-lookup: Resolve an entity name or exact LEI against the official GLEIF index. Authentication=oauth2_client_credentials; price=$0.01.
- POST /v1/query/treasury-yield-curve-latest: Return one latest bounded U.S. Treasury par-yield curve observation. Authentication=oauth2_client_credentials; price=$0.01.
- POST /v1/query/overnight-rates-latest: Return the latest bounded SOFR, EFFR and related official reference-rate observations. Authentication=oauth2_client_credentials; price=$0.01.
- POST /v1/query/sec-filing-delta: Compare selected SEC XBRL facts between the latest two filings of one form type. Authentication=oauth2_client_credentials; price=$0.10.
- POST /v1/query/government-demand-packet: Combine bounded award rollups and materialized contract signals for one ticker. Authentication=oauth2_client_credentials; price=$0.25.
- POST /v1/query/security-history: Return bounded normalized daily adjusted-close history for one public-equity ticker, with dates, currency, source and freshness. It is not a live quote. Authentication=oauth2_client_credentials; price=$0.01.
- POST /v1/query/security-screen: Screen U.S. public companies or a named U.S. index using a small allowlist of precomputed financial metrics. ETFs and funds are excluded; arbitrary SQL is never accepted. Authentication=oauth2_client_credentials; price=$0.02.
- POST /v1/query/insider-activity: Return recent official SEC Form 4 filing metadata for one issuer. This version reports filing activity and accessions only; it does not claim parsed purchases, sales or ownership changes. Authentication=oauth2_client_credentials; price=$0.02.
- POST /v1/query/short-interest-state: Return bounded official FINRA consolidated short-interest observations and optional Nasdaq Trader Reg SHO threshold-list membership. Semi-monthly short interest is not daily short volume. Authentication=oauth2_client_credentials; price=$0.02.
- POST /v1/query/security-technicals: Return latest precomputed technical indicators from an explicit indicator-family allowlist. Use for structured technical state, not a trading signal or live quote. Authentication=oauth2_client_credentials; price=$0.01.
- POST /v1/query/market-regime: Return the latest compact market-risk context computed by QJ Analytics from governed Warehouse inputs. It is descriptive evidence, not a forecast or allocation instruction. Authentication=oauth2_client_credentials; price=$0.02.
- POST /v1/query/simulate-trade: Estimate before, after and delta portfolio volatility, effective number of bets and fractional risk contribution for one bounded hypothetical long-only trade. No order or portfolio state is created. Authentication=oauth2_client_credentials; price=$0.05.
- POST /v1/query/portfolio-normalize: Resolve up to 25 unique long-only tickers and return normalized weights, identity coverage and concentration without creating a stored portfolio. Authentication=none; price=$0.00.
- POST /v1/query/portfolio-exposure: Return compact sector, country, asset-class and supplied-currency exposure for an inline portfolio. Authentication=oauth2_client_credentials; price=$0.01.
- POST /v1/query/portfolio-volatility: Estimate bounded annualized volatility from authorized aligned daily prices or returns. Authentication=oauth2_client_credentials; price=$0.01.
- POST /v1/query/portfolio-var-cvar: Calculate bounded portfolio VaR and CVaR from authorized aligned daily prices or returns. Authentication=oauth2_client_credentials; price=$0.01.
- POST /v1/query/portfolio-drawdown: Calculate bounded portfolio and position drawdowns from authorized aligned daily prices or returns. Authentication=oauth2_client_credentials; price=$0.01.
- POST /v1/query/portfolio-benchmark-risk: Estimate portfolio beta, correlation and regression evidence versus one benchmark. Authentication=oauth2_client_credentials; price=$0.01.
- POST /v1/query/portfolio-factor-exposure: Estimate bounded CAPM, Fama-French 3 or Fama-French 5 factor exposure. Authentication=oauth2_client_credentials; price=$0.01.
- POST /v1/query/portfolio-liquidity: Estimate compact position liquidity using observed price-volume history. Authentication=oauth2_client_credentials; price=$0.01.
- POST /v1/query/portfolio-events: Return bounded upcoming-event exposure and event-risk summaries. Authentication=oauth2_client_credentials; price=$0.01.
- POST /v1/query/portfolio-signals: Return compact precomputed technical, congressional and government-contract signals for the largest supplied positions. Authentication=oauth2_client_credentials; price=$0.01.
- POST /v1/query/portfolio-scenario: Run one named or bounded custom QJ Risk scenario over an inline portfolio. Authentication=oauth2_client_credentials; price=$0.01.
- POST /v1/query/portfolio-position-risk: Return compact per-position volatility, beta, correlation and drawdown evidence. Authentication=oauth2_client_credentials; price=$0.01.
- POST /v1/query/portfolio-performance: Calculate whole-portfolio hypothetical constant-weight performance, Sharpe, Sortino and Calmar. Not account TWR/MWR. Authentication=oauth2_client_credentials; price=$0.01.
- POST /v1/query/portfolio-correlations: Calculate the full Pearson or Spearman matrix of aligned daily asset returns; constant-series correlations are null. Authentication=oauth2_client_credentials; price=$0.01.
- POST /v1/query/portfolio-optimization: Calculate stateless long-only fully-invested weights using min_variance, risk_parity or max_sharpe. Research only, no orders or persistence. Authentication=oauth2_client_credentials; price=$0.01.
- POST /v1/query/portfolio-simulation: Simulate a constant-weight portfolio with calibrated lognormal GBM or IID historical bootstrap. Seeded, bounded, not a forecast. Authentication=oauth2_client_credentials; price=$0.01.
Paid routes declare their exact per-resource x402 price; free routes declare no payment requirement.
Discovery and authentication are not charged.
x402 is the primary payment rail for Earnings Recap. No subscription is required.
ERC-8004 is an experimental discovery-only identity rail. Its registration file advertises
only QJ API MCP, publishes no self-authored reputation, and leaves supportedTrust empty.
Draft specification: https://eips.ethereum.org/EIPS/eip-8004

OAuth lifecycle:
- Rotate a client secret with POST https://agents.quantjourney.cloud/oauth/client/rotate-secret and a stable Idempotency-Key.
- Revoke an access token with POST https://agents.quantjourney.cloud/oauth/revoke.
- Deactivate a client with POST https://agents.quantjourney.cloud/oauth/client/deactivate.
- Inspect caller limits and aggregate usage at GET https://agents.quantjourney.cloud/v1/me.
- Durable task state exists at https://agents.quantjourney.cloud/v1/tasks.
  Admission returns 503 while execution is disabled.

## Tool policy

- Prefer QJ Data MCP: https://data.quantjourney.cloud/mcp
- Use QJ API MCP only when curated Data MCP coverage is absent: https://api.quantjourney.cloud/mcp
- Do not call private QJ services, databases, providers or SDKs directly.
- Treat stale, partial and research-grade evidence as explicit output metadata.

## Skills and lifecycle status

- [available] qj-company-snapshot-lite: Return a free, bounded factual ticker snapshot with price, selected metrics, freshness and explicit coverage gaps.
- [available] qj-earnings-preview: Prepare an evidence-backed earnings preview with consensus, revisions, dispersion, historical surprises, valuation context and explicit review questions.
- [available] qj-earnings-recap: Reconcile the latest reported earnings with consensus, estimate changes, adjusted-close reactions, SPY-adjusted CAR and explicit thesis-review questions.
- [available] qj-congress-gov-signals: Combine congressional disclosures and government-contract evidence with disclosure-lag warnings.
- [available] qj-sec-company-identity: Resolve a ticker or company name to official SEC identity and exchange fields.
- [available] qj-sec-latest-filing: Return the latest official SEC submission for a ticker and bounded form type.
- [available] qj-sec-company-facts-compact: Project selected current SEC XBRL facts into a small evidence envelope.
- [available] qj-gleif-entity-lookup: Resolve an entity name or exact LEI against the official GLEIF index.
- [available] qj-treasury-yield-curve-latest: Return one latest bounded U.S. Treasury par-yield curve observation.
- [available] qj-overnight-rates-latest: Return the latest bounded SOFR, EFFR and related official reference-rate observations.
- [available] qj-sec-filing-delta: Compare selected SEC XBRL facts between the latest two filings of one form type.
- [available] qj-government-demand-packet: Combine bounded award rollups and materialized contract signals for one ticker.
- [available] qj-security-history: Return bounded normalized daily adjusted-close history for one public-equity ticker, with dates, currency, source and freshness. It is not a live quote.
- [available] qj-security-screen: Screen U.S. public companies or a named U.S. index using a small allowlist of precomputed financial metrics. ETFs and funds are excluded; arbitrary SQL is never accepted.
- [available] qj-insider-activity: Return recent official SEC Form 4 filing metadata for one issuer. This version reports filing activity and accessions only; it does not claim parsed purchases, sales or ownership changes.
- [available] qj-short-interest-state: Return bounded official FINRA consolidated short-interest observations and optional Nasdaq Trader Reg SHO threshold-list membership. Semi-monthly short interest is not daily short volume.
- [available] qj-security-technicals: Return latest precomputed technical indicators from an explicit indicator-family allowlist. Use for structured technical state, not a trading signal or live quote.
- [available] qj-market-regime: Return the latest compact market-risk context computed by QJ Analytics from governed Warehouse inputs. It is descriptive evidence, not a forecast or allocation instruction.
- [available] qj-simulate-trade: Estimate before, after and delta portfolio volatility, effective number of bets and fractional risk contribution for one bounded hypothetical long-only trade. No order or portfolio state is created.
- [available] qj-portfolio-normalize: Resolve up to 25 unique long-only tickers and return normalized weights, identity coverage and concentration without creating a stored portfolio.
- [available] qj-portfolio-exposure: Return compact sector, country, asset-class and supplied-currency exposure for an inline portfolio.
- [available] qj-portfolio-volatility: Estimate bounded annualized volatility from authorized aligned daily prices or returns.
- [available] qj-portfolio-var-cvar: Calculate bounded portfolio VaR and CVaR from authorized aligned daily prices or returns.
- [available] qj-portfolio-drawdown: Calculate bounded portfolio and position drawdowns from authorized aligned daily prices or returns.
- [available] qj-portfolio-benchmark-risk: Estimate portfolio beta, correlation and regression evidence versus one benchmark.
- [available] qj-portfolio-factor-exposure: Estimate bounded CAPM, Fama-French 3 or Fama-French 5 factor exposure.
- [available] qj-portfolio-liquidity: Estimate compact position liquidity using observed price-volume history.
- [available] qj-portfolio-events: Return bounded upcoming-event exposure and event-risk summaries.
- [available] qj-portfolio-signals: Return compact precomputed technical, congressional and government-contract signals for the largest supplied positions.
- [available] qj-portfolio-scenario: Run one named or bounded custom QJ Risk scenario over an inline portfolio.
- [available] qj-portfolio-position-risk: Return compact per-position volatility, beta, correlation and drawdown evidence.
- [available] qj-portfolio-performance: Calculate whole-portfolio hypothetical constant-weight performance, Sharpe, Sortino and Calmar. Not account TWR/MWR.
- [available] qj-portfolio-correlations: Calculate the full Pearson or Spearman matrix of aligned daily asset returns; constant-series correlations are null.
- [available] qj-portfolio-optimization: Calculate stateless long-only fully-invested weights using min_variance, risk_parity or max_sharpe. Research only, no orders or persistence.
- [available] qj-portfolio-simulation: Simulate a constant-weight portfolio with calibrated lognormal GBM or IID historical bootstrap. Seeded, bounded, not a forecast.
- [preview] qj-equity-deep-dive: Build a full company research note grounded in QJ fundamentals, metrics, estimates, price history and lineage.
- [preview] qj-valuation-workbench: Create a bounded valuation analysis using QJ metrics, fundamentals, estimates and explicit scenario assumptions.
- [preview] qj-thesis-tracker: Audit or update a living thesis against new evidence, catalysts, invalidation conditions and review triggers.
- [preview] qj-portfolio-monitor: Review portfolio exposures, event risk, concentration and material evidence changes without taking execution actions.
- [preview] qj-institutional-flow: Analyze 13F, ownership and institutional positioning with filing-period and publication-lag controls.
- [preview] qj-macro-regime-brief: Create a dated macro regime brief using rates, commodities, benchmarks and scheduled macro events.
- [preview] qj-catalyst-calendar: Build a dated watchlist of earnings, dividends, macro, split and thesis-review catalysts with coverage status.
- [preview] qj-idea-generation: Generate research candidates from screens, ranks, government and congressional evidence without presenting them as recommendations.
- [preview] qj-risk-bias-review: Challenge an existing analysis for unsupported claims, confirmation bias, data gaps and portfolio risk.
- [preview] qj-portfolio-rebalance-planner: Prepare a non-executing rebalance proposal from drift, concentration, risk and benchmark evidence.
- [preview] qj-supply-chain-theme-research: Map thematic supply chains, chokepoints, beneficiaries and exposed baskets using profiles, contracts and metrics.

The Agent Card contains only the 35 available skills. The full catalog also
contains 11 preview skills so future product intent is visible without implying
that those skills can be invoked today.

## Output contract

Every substantial artifact separates facts, interpretation and open questions,
and includes coverage, tools used, as-of, freshness, product grade and lineage.
This service never places trades.