Reference
Every endpoint, every tool, and what each one costs
32 registered MCP tools and 18 REST endpoints. What each one returns, what you would ask it for, and the credits it spends.
32
Registered MCP tools
18
REST endpoints
3
Open without a key
Credits
What a call costs
Each accepted request to a research tool uses one included call, across all 31 research tools. Taxonomy discovery is unmetered. Included calls are used first. When you use a purchased wallet, calls consume weighted credits based on the tool and requested result count; the table shows each tool's base wallet cost.
Free
5requests/day
31 metered research tools · flat rate
All 31 research tools, 5 calls a day, no card required. Taxonomy discovery is unmetered.
Perception
20requests/day
31 metered research tools · flat rate
All 31 research tools, 20 included requests a day, plus the Perception app. Taxonomy discovery is unmetered.
Intelligence
100requests/day
31 metered research tools · flat rate
All 31 research tools, and each accepted metered request uses one included call at any size. Taxonomy discovery is unmetered.
- Included MCP requests are used first. Purchased wallet calls use weighted credits, with cost affected by tool and result size.
- REST and MCP have separate daily pools. Spending one does not touch the other.
- 60 requests per minute across both surfaces.
- Full-text article calls draw on a separate 200/day pool as well as credits.
- Team plans run monthly pools instead of daily: 15,000 requests and 1,000 full-text, with metered overage.
REST
Every REST endpoint
Base URL https://api.perception.to. Every route also answers under a /v1 prefix. REST calls are a flat 1 credit and draw on their own pool.
| Endpoint | What it fetches | Credits |
|---|---|---|
/indexGETNo key | Perception Index score, status, 24h/7d change, confidence and decomposed drivers. Updated every 15 minutes.Open, no key. Add ?full=true with a Bearer token for divergences and returns by sentiment regime (1 credit). | Free |
/indicesGETNo key | Perception's five-index family: Perception Index, Bitcoin Discourse Dominance, Narrative Cost Basis, Cohort Conviction Gap and Perception Breadth.Current headline readings are open. Add ?full=true with a Bearer token for methodology receipts, component breakdowns and bounded history (1 credit). | Free |
/transparency-indexGETNo key | Earnings-call directness scores per company, with the verbatim quotes behind each score.Open, no key. | Free |
/transparency-index/leaderboardGETBearer | Companies ranked by directness score. | 1 |
/transparency-index/:tickerGETBearer | Full directness detail for one company, including scored quotes. | 1 |
/feedGETBearer | Mention search across thousands of sources with full-text search, date, outlet and sentiment filters.Also accepts x402 pay-per-call in USDC without a subscription, which is why an unkeyed request returns 402 rather than 401. | 1 |
/trendsGETBearer | AI-extracted narrative trends with signal strength and the mentions behind each cluster. | 1 |
/intelligenceGETBearer | Trend intelligence and category distribution. | 1 |
/sentiment-metricsGETBearer | Historical sentiment series, by day and by outlet. | 1 |
/fear-greed-indexGETBearer | Bitcoin Fear & Greed Index history. | 1 |
/channel-volumeGETBearer | Mention volume broken down by outlet and channel. | 1 |
/grouped-dataPOSTBearer | Entity recognition over a body of coverage: company mentions with counts and sentiment. | 1 |
/cohortsGETBearer | Sentiment split by the role of the speaker: execs, devs, analysts, investors, media and more. | 1 |
/evadometerGETBearer | Evade-o-Meter directness scoring across tracked companies. | 1 |
/evadometer/leaderboardGETBearer | Companies ranked by how directly management answers. | 1 |
/evadometer/:tickerGETBearer | Evade-o-Meter detail for one company. | 1 |
Account-scoped routes2 endpoints
| Endpoint | What it fetches | Credits |
|---|---|---|
/v1/spaces/:id/rowsGETBearer | Rows from a Space you own, in the same shape as its CSV export. Cursor-paginated, 50 per page by default.Returns 404 rather than 403 on a Space you do not own, so the API never confirms that someone else’s Space exists. | 1 |
/v1/brains/:idGETBearer | A Brain you own: the collected post history behind it. | 1 |
MCP
All 32 MCP tools
Connect Claude, ChatGPT or Cursor and these become callable directly. Every tier can use all 32 tools. Each accepted research request uses one included call; taxonomy discovery is unmetered. The Wallet credits column shows the base cost for purchased wallet usage; larger result sets can increase that cost.
Research15 tools
| Tool | What it fetches | Wallet credits |
|---|---|---|
perception_get_market | Bitcoin price, market cap, chain reference metrics and the Perception Index.“Price, block height and the Index, for a report dateline.” | 1 |
perception_guide | In-agent onboarding and workflow templates.“What can Perception do, and how should I use it?” | 1 |
perception_get_subject_taxonomy | Canonical subject labels and accepted aliases for precise query construction.“Which subject labels should I use for a custody research query?” | Free |
perception_daily_radar | Daily briefing: anomalies, sentiment shifts, emerging narratives.“What changed overnight?” | 2 |
perception_get_index | The five-index Perception portfolio with current readings, confidence, components and optional history.“Show me every Perception proprietary index and what each says now.” | 1 |
perception_search_mentions | Search thousands of sources with sentiment, outlet, language and region filters.“Every mention of Coinbase last week, negative only.” | 1 |
perception_get_trends | AI-extracted narrative trends with signal strength.“Which narratives are gaining signal strength right now?” | 2 |
perception_get_sentiment | Historical sentiment by day and by outlet.“How has sentiment toward stablecoins moved this quarter?” | 1 |
perception_get_categories | Trend category distribution.“Which categories dominate coverage this month?” | 1 |
perception_search_companies | Entity-recognition company search, more accurate than keyword matching.“Which companies keep coming up alongside custody?” | 2 |
perception_compare_entities | Two to five companies side by side: volume, sentiment, sources.“Compare Coinbase, Kraken and Gemini on volume and sentiment.” | 2 |
perception_narrative_momentum | Whether a topic is accelerating, steady or fading.“Is tokenization accelerating or fading?” | 1 |
perception_top_mentions | Top entities or topics by mention count for a date range or outlet.“Who was mentioned most at DAS NYC?” | 1 |
perception_cohort_sentiment | Sentiment split by speaker role: execs, devs, analysts, media.“Are developers more bearish than executives here?” | 1 |
perception_get_evadometer | Earnings-call directness scores.“Which management teams dodge the most questions?” | 1 |
Entity intelligence2 tools
| Tool | What it fetches | Wallet credits |
|---|---|---|
perception_get_entity_profile | Full entity picture: coverage, analyst view, trends, relationships, timeline.“Give me everything on Circle.” | 3 |
perception_media_radar | Outlet-specific coverage analysis.“How does Bloomberg cover this differently from CoinDesk?” | 1 |
Extended research15 tools
| Tool | What it fetches | Wallet credits |
|---|---|---|
perception_get_analyst_ratings | Analyst consensus, price targets and rating changes for covered tickers.“What is the analyst consensus on MSTR?” | 1 |
perception_search_regulatory | Regulatory filings, enforcement actions and policy documents by agency and jurisdiction.“What has the SEC published on custody this year?” | 1 |
perception_get_article | Full text of a single article.“Pull the full text of this piece.” | 3 |
perception_save_research | Save a research note with findings and topics (90-day retention).“Save this finding so I can come back to it.” | 1 |
perception_recall_research | Retrieve saved research notes by recency or topic.“What did I find on this last month?” | 1 |
perception_scenario_analysis | Test a hypothetical against historical analogues: sentiment arcs, narrative half-life.“If an ETF were rejected, how has coverage behaved before?” | 3 |
perception_get_insider_activity | SEC Form 4 insider trades with cluster alerts.“Are insiders at this company buying or selling?” | 1 |
perception_get_earnings_intelligence | Earnings-call analysis: management tone, directness, notable quotes.“How direct was management on the last call?” | 1 |
perception_get_intelligence_digest | Cross-signal briefing fusing analyst actions, sentiment, earnings and regulatory moves.“One briefing across every signal today.” | 3 |
perception_search_voices | Search earnings transcripts, conferences, and podcasts for keywords, with snippets and timestamped occurrences.“What have speakers said about stablecoins in podcasts and earnings calls?” | 1 |
perception_get_brains_corpus | Bulk corpus access for a tracked voice or entity.“Everything this executive has posted.” | 2 |
perception_get_divergences | Where narrative and capital disagree.“Where does the narrative disagree with the money?” | 1 |
perception_get_capital_exposure | 13F holdings, treasury positions and beneficial ownership for an entity.“Who holds this stock, and how has that changed?” | 1 |
perception_get_hiring | Open roles and hiring posture for a company from its public ATS board.“Is Kraken hiring right now, and for what?” | 1 |
perception_hiring_leaderboard | Companies ranked by open roles across the tracked universe, by sector and function.“Which crypto companies are hiring the most right now?” | 1 |
Schema
What a mention looks like
Every mention returned by /v1/feed and the search tools has this shape, whether it started as an article, a post, a podcast transcript or a filing.
| Field | Type | Description |
|---|---|---|
Title | string | Article headline, or @handle for tweets |
Content | string | Full article text or tweet body |
Date | string (ISO 8601) | Publication timestamp, UTC |
URL | string | Source URL |
Outlet | string | Source name (e.g. Bloomberg, X, CoinDesk) |
Sentiment | string | Positive, Neutral, or Negative |
Outlet_Category | string | Crypto Media, Financial Media, Social Media, Regulatory, Podcast, GitHub |
author_name | string | null | Author name (media articles only) |
image_url | string | null | Article thumbnail or OG image |
Agent discovery
Agents can find the API, the MCP server and these docs without a human in the loop. If you are not writing an agent, you can skip this.
| perception.to/llms.txt | Plain-language site guide for language models |
| perception.to/.well-known/mcp.json | MCP server descriptor: tools, auth, transport |
| perception.to/.well-known/agent.json | Agent card with capabilities and endpoints |
| perception.to/.well-known/api-catalog | RFC 9727 API catalog |
| perception.to/.well-known/oauth-authorization-server | OAuth 2.1 discovery for MCP clients |
| perception.to/.well-known/agent-skills/index.json | Installable agent skills |
robots.txt Content-Signal: search=yes, ai-input=yes, ai-train=no. Live agents welcome; training on the archive is not.
Get a key and start calling
Start free, add prepaid MCP credits, or choose a bundle with included daily capacity.