canonical: https://jentic.com/apis/beliefstate.ai/beliefstate

# BeliefState Intelligence API

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.

## For AI 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.

## Scope

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.

## Capabilities

- 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

## Use cases

### 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/v1/brief` | Review a stock thesis for a ticker |
| GET | `/v1/beliefs` | Find investor beliefs or inspect a full record |
| GET | `/v1/sources` | Find research sources |
| GET | `/v1/tickers` | Find tickers with available research |
| GET | `/v1/research` | List paid research operations and prices |
| POST | `/v1/research/get_company_facts` | Buy company facts for a ticker |
| POST | `/v1/research/get_comparison` | Compare two investment cases |
| GET | `/v1/status` | Check API access and credit balance |

## Key resources

- **Brief** — Ticker research brief with a thesis review and conditional future case
- **Beliefs** — Recorded investor beliefs with full records and evidence
- **Sources** — Directory of research sources searchable by name, domain, or source ID
- **Tickers** — Tickers with available research coverage
- **Paid research tools** — x402-priced tools such as company facts, insider trades, institutional holdings, and case comparison

## AI readiness

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.

- **Score:** 43 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 73 / 100
  - Developer Experience & Jentic Compatibility: 63 / 100
  - AI-Readiness & Agent Experience: 20 / 100
  - Agent Usability: 94 / 100
  - Security: 55 / 100
  - AI Discoverability: 52 / 100
- **View full report:** https://jentic.com/apis/beliefstate.ai/beliefstate/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **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 handling:** 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.
- **Discovery method:** 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.

## Related APIs

- **Alpha Vantage API** — Stock prices, fundamentals, and technical indicators by ticker
- **Finnhub API** — Market data, company fundamentals, and insider transactions
- **Polygon API** — Tick-level stock, options, and aggregates market data
- **SEC API** — Search and stream SEC EDGAR filings

## FAQ

### 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.
