For Agents
Pull ticker research briefs, investor beliefs, and research sources with a BeliefState API key, or buy individual research tools such as company facts, insider trades, and case comparisons per call with x402 payments.
Use for: I need a research brief on a stock ticker before a meeting, Find all investor beliefs recorded for NVDA, Check whether BeliefState covers a given ticker, List all paid research tools and what each one costs
Not supported: Does not handle trade execution, brokerage accounts, portfolio management, or real-time price streaming. Use for ticker research, investor beliefs, and pay-per-call company data only.
The BeliefState Intelligence API returns stock research for a ticker: a research brief, recorded investor beliefs with their evidence, a directory of research sources, and the list of tickers with coverage. A second family of paid research tools, priced per call in USDC and settled through x402 payments, adds company facts, insider transactions, institutional holdings, options and short activity, macroeconomic context, and investment case comparisons. Each paid tool has a free contract endpoint that returns its input and output schemas, and a free price list covers every paid operation with its exact price.
Install Jentic One Beta
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the BeliefState Intelligence API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fbeliefstate.ai%2Fbeliefstate" | shStep 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fbeliefstate.ai%2Fbeliefstate" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
What an agent can do with BeliefState Intelligence API.
Review a stock thesis for a ticker with the research brief from /v1/brief, including its conditional future case
Find recorded investor beliefs for a ticker or person_id and inspect the full record and evidence via /v1/beliefs
Look up research sources by name, domain, or source_id through /v1/sources
Check which tickers have research coverage with the open /v1/tickers lookup
Read the free paid-research price list at /v1/research for exact per-tool prices and schemas before paying
Buy insider transactions, institutional holdings, options activity, or company facts for a ticker as individual x402 research calls
Compare two investment cases by belief_id and compare_to_belief_id with the get_comparison research tool
Patterns agents use BeliefState Intelligence API for, with concrete tasks.
★ Agent-driven stock research through Jentic
A research agent connected through Jentic searches by intent, gets the BeliefState brief operation with its input schema, and calls it with a ticker to get a thesis review and conditional future case. It can then pull recorded investor beliefs for the same ticker and the sources behind them, so the answer it writes back cites a recorded record instead of a guess.
Call GET /v1/brief with ticker 'AAPL' and detail set, then call GET /v1/beliefs with ticker 'AAPL' to list the recorded investor beliefs behind the brief
Pay-per-call company data with x402
Without opening an account, an agent can read the free price list at /v1/research to see each research tool's price, read the tool's contract endpoint for its schemas, and then buy one call such as company facts or insider transactions for a ticker. The x402 quote is returned first, so the agent reads the exact price before it signs the PAYMENT-SIGNATURE header.
Call GET /v1/research to read prices, call GET /v1/research/get_insider_trades for the schema, then POST /v1/research/get_insider_trades with ticker 'MSFT' and a signed PAYMENT-SIGNATURE header
Investment case comparison
An analyst agent compares two recorded investment cases by passing belief_id and compare_to_belief_id to the get_comparison research tool, with an optional comparison_focus. Paired with get_risks and get_catalysts for each case, the agent can summarise where two theses on the same company agree and where they split.
POST /v1/research/get_comparison with belief_id 'b_123' and compare_to_belief_id 'b_456', then POST /v1/research/get_risks with belief_id 'b_123' to list the risks of the first case
Research change monitoring
A monitoring agent polls the get_changes research tool for a ticker or person_id with changed_since and a checkpoint, so it only sees new or revised research records since its last run. It can then fetch the updated brief for any ticker whose research moved and post a summary to the developer.
POST /v1/research/get_changes with ticker 'TSLA', changed_since '2026-11-01', and the stored checkpoint, then call GET /v1/brief for 'TSLA' if any change is returned
48 endpoints — the beliefstate intelligence api returns stock research for a ticker: a research brief, recorded investor beliefs with their evidence, a directory of research sources, and the list of tickers with coverage.
METHOD
PATH
DESCRIPTION
/v1/brief
Review a stock thesis for a ticker
/v1/beliefs
Find investor beliefs or inspect a full record
/v1/sources
Find research sources
/v1/tickers
Find tickers with available research
/v1/research
List paid research operations and prices
/v1/research/get_company_facts
Buy company facts for a ticker
/v1/research/get_comparison
Compare two investment cases
/v1/status
Check API access and credit balance
/v1/brief
Review a stock thesis for a ticker
/v1/beliefs
Find investor beliefs or inspect a full record
/v1/sources
Find research sources
/v1/tickers
Find tickers with available research
/v1/research
List paid research operations and prices
/v1/research/get_company_facts
Buy company facts for a ticker
/v1/research/get_comparison
Compare two investment cases
/v1/status
Check API access and credit balance
This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.
Base layer of spec validity and structural soundness.
Aggregated quality score from linter diagnostics, weighted by severity.
Percentage of `$ref` references that resolve successfully.
Checks whether the API description parses successfully and conforms to its declared specification (e.g., OpenAPI).
Structural correctness score based on schema issues using logarithmic dampening.
Clarity, completeness, and ingestion readiness for developers and tooling.
How richly the API is illustrated with examples.
Percentage of examples that conform to their schemas.
Percentage of operations with complete response definitions (success, client error, server error).
Health of API ingestion, bundling, and resolution within Jentic pipelines.
Semantic breadth, depth, and agent comprehension for AI systems.
Coverage of descriptions across API elements.
Coverage of RFC 9457 Problem Details for error responses.
Coverage, uniqueness, and casing consistency of operationIds for AI inference.
Coverage of summaries across operations/tags/info.
Functional utility, complexity comfort, and AI orchestration readiness.
Agent comfort level based on API operational and structural complexity.
Trust, risk posture, and security compliance.
Average quality of security schemes based on authentication method strength (weakest link for OAuth2).
Findability, semantic richness, and reasoning readiness.
Clarity and depth of descriptions across API elements.
Score it yourself
Every API in the directory is allowlisted, so you can re-score it with no key required.
npx @jentic/api-scorecard-cli score <openapi-url>What agents get from Jentic-routed access to this vendor.
Setup
Wiring BeliefState by hand means handling two credential paths: a bearer API key for the account routes and x402 payment signatures for the paid research tools, plus reading each tool's contract before calling it. Through Jentic you install once, import the BeliefState Intelligence API from the API Directory, store the key once, and your agent calls it.
Permission scoping
BeliefState passes the ticker as a query or body field on almost every operation, so rules bound which operations your agent may call, not which ticker. Limit it to the operations it needs, such as the brief and beliefs reads, and the paid /v1/research purchases are not included unless you add them.
Credential isolation
Your BeliefState API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
Intent-based discovery
Agents search Jentic by intent such as 'research brief for a ticker' or 'insider transactions for a company', and Jentic returns the matching BeliefState operation with its input schema so the agent calls the right endpoint without browsing the reference docs.
Alternatives and complements available in the Jentic catalogue.
Specific to using BeliefState Intelligence API through Jentic.
What authentication does the BeliefState Intelligence API use?
Per its OpenAPI spec, the account-based routes such as /v1/brief, /v1/beliefs, /v1/sources, and /v1/status take a BeliefState API key as a bearer token in the Authorization header. The paid research tools under /v1/research use x402 instead: a payment authorization sent in the PAYMENT-SIGNATURE header, with no account needed. Some endpoints need no credential at all, including /v1/tickers, the /v1/research price list, and each tool's schema contract. Through Jentic the bearer key is stored encrypted by your own Jentic One instance and injected at call time.
Can I get insider trades and institutional holdings with the BeliefState Intelligence API?
Yes, as paid x402 research tools. POST /v1/research/get_insider_trades and POST /v1/research/get_institutional_holdings each require a ticker and accept filters such as owner_name or manager_cik, date_from, date_to, and limit. Read the matching GET contract endpoint first for the full input and output schema.
How much do the BeliefState paid research tools cost?
The spec states that data calls cost 0.02 USDC on Base, model comparison costs 0.50, and model-assisted search costs 1.50. The free GET /v1/research endpoint lists the exact current price of every paid tool, and each call returns a quote you can read before paying.
What are the rate limits for the BeliefState Intelligence API?
The OpenAPI spec does not specify rate limits. GET /v1/status reports your access, credit balance, and usage metering, and https://beliefstate.ai/agents is the vendor's starting point for current limits.
Is there a BeliefState MCP server?
You don't need an MCP server to give your agent the BeliefState Intelligence API. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent calls it. Operations are found by intent when needed, so no extra tool definitions sit in your agent's context.
How do I pull a ticker research brief through Jentic?
Install Jentic One, add the BeliefState Intelligence API from the directory, and store your BeliefState API key. Your agent then searches for 'research brief for a stock ticker', gets the GET /v1/brief operation with its schema, and calls it with a ticker. To run it on your own infrastructure, install Jentic One from its GitHub repo.
Can I limit what my agent is allowed to do with the BeliefState Intelligence API?
Yes. Write a rule that allows only GET /v1/brief, GET /v1/beliefs, and GET /v1/tickers, so the agent can research tickers and read beliefs with your key but cannot reach the paid /v1/research tools, and every call it makes is logged.
GET STARTED