# Perception: agent reference Perception provides narrative intelligence for the digital asset industry over MCP and REST. Use the live MCP schema for parameter names, types, and required fields. ## Canonical URLs - Documentation: https://perception.to/docs - MCP reference: https://perception.to/docs/mcp - REST reference: https://perception.to/docs/rest - MCP descriptor: https://perception.to/.well-known/mcp.json - MCP endpoint: `https://mcp.perception.to/mcp` ## Access and billing Commercial model: `2026-09-05-flat-included-v2`. - Registered catalog: 32 tools across every access mode. - Commercial catalog: 31 metered research tools. `perception_get_subject_taxonomy` is an unmetered discovery helper. - Free: all 31 metered research tools, 5 calls/day. Each metered request accepted for execution uses one daily call regardless of tool weight or requested result volume. - Metered MCP: all 31 metered research tools through a prepaid wallet. Packs are 10 credits for $19, 25 for $39, and 60 for $79. No subscription is required. - Perception: all 31 metered research tools, 20 included requests/day. - Intelligence: all 31 metered research tools, 100 included requests/day. - Bundle settlement: included capacity is consumed before the prepaid wallet. - Metered signup: https://app.perception.to/auth/sign-up?source=pricing-metered&plan=metered Each accepted metered request uses one included call on every tier, regardless of tool weight or requested result count. Taxonomy discovery is unmetered. Prepaid MCP calls consume weighted credits after a successful result. Failed prepaid calls release the reservation. ## Connection - Transport: Streamable HTTP - Authentication: OAuth 2.1 or Bearer token - Discovery: initialize the MCP client, list the live tools, then call the selected tool with its returned input schema. ## Replay protection - Automatic retries: exact redelivery reuses the original funding outcome for the same authenticated user, JSON-RPC id, and canonical request body during the retry window. - Explicit retries: send one unique 8 to 128 character `Idempotency-Key` or `X-Request-Id` per new call. Reuse it only for the exact same JSON-RPC body. - Static connector headers are unsuitable for per-call idempotency keys. ## Tool directory | Tool | Access tier | Use | | --- | --- | --- | | `perception_get_market` | free | Bitcoin price, market cap, chain reference metrics and the Perception Index. | | `perception_guide` | free | In-agent onboarding and workflow templates. | | `perception_get_subject_taxonomy` | free | Canonical subject labels and accepted aliases for precise query construction. | | `perception_daily_radar` | free | Daily briefing: anomalies, sentiment shifts, emerging narratives. | | `perception_get_index` | free | The five-index Perception portfolio with current readings, confidence, components and optional history. | | `perception_search_mentions` | free | Search thousands of sources with sentiment, outlet, language and region filters. | | `perception_get_trends` | free | AI-extracted narrative trends with signal strength. | | `perception_get_sentiment` | free | Historical sentiment by day and by outlet. | | `perception_get_categories` | free | Trend category distribution. | | `perception_search_companies` | free | Entity-recognition company search, more accurate than keyword matching. | | `perception_compare_entities` | free | Two to five companies side by side: volume, sentiment, sources. | | `perception_narrative_momentum` | free | Whether a topic is accelerating, steady or fading. | | `perception_top_mentions` | free | Top entities or topics by mention count for a date range or outlet. | | `perception_cohort_sentiment` | free | Sentiment split by speaker role: execs, devs, analysts, media. | | `perception_get_evadometer` | free | Earnings-call directness scores. | | `perception_get_entity_profile` | perception | Full entity picture: coverage, analyst view, trends, relationships, timeline. | | `perception_media_radar` | perception | Outlet-specific coverage analysis. | | `perception_get_analyst_ratings` | intelligence | Analyst consensus, price targets and rating changes for covered tickers. | | `perception_search_regulatory` | intelligence | Regulatory filings, enforcement actions and policy documents by agency and jurisdiction. | | `perception_get_article` | intelligence | Full text of a single article. | | `perception_save_research` | intelligence | Save a research note with findings and topics (90-day retention). | | `perception_recall_research` | intelligence | Retrieve saved research notes by recency or topic. | | `perception_scenario_analysis` | intelligence | Test a hypothetical against historical analogues: sentiment arcs, narrative half-life. | | `perception_get_insider_activity` | intelligence | SEC Form 4 insider trades with cluster alerts. | | `perception_get_earnings_intelligence` | intelligence | Earnings-call analysis: management tone, directness, notable quotes. | | `perception_get_intelligence_digest` | intelligence | Cross-signal briefing fusing analyst actions, sentiment, earnings and regulatory moves. | | `perception_search_voices` | intelligence | Search earnings transcripts, conferences, and podcasts for keywords, with snippets and timestamped occurrences. | | `perception_get_brains_corpus` | intelligence | Bulk corpus access for a tracked voice or entity. | | `perception_get_divergences` | intelligence | Where narrative and capital disagree. | | `perception_get_capital_exposure` | intelligence | 13F holdings, treasury positions and beneficial ownership for an entity. | | `perception_get_hiring` | intelligence | Open roles and hiring posture for a company from its public ATS board. | | `perception_hiring_leaderboard` | intelligence | Companies ranked by open roles across the tracked universe, by sector and function. | ## x402 full-text feed x402 is a separate payment path for the full-text REST feed. MCP tools use the OAuth/Bearer endpoint. - Endpoint: `GET https://api.perception.to/feed` - Protocol: x402 v1 over HTTP 402 - Settlement: $0.05 in USDC on Base mainnet - Network: `base` - USDC contract: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` - Payment recipient: `0xA89dac7b70e04c880974b02758Bd8fde14280013` Lightning L402 access is unavailable while invoice creation is repaired. ## Operating guidance 1. Call `perception_guide` when you need workflow suggestions. 2. Start broad with radar for an overview, then use the research tools for the question at hand. 3. Treat tool responses as the evidence for research output. 4. Cite Perception and link the returned source URLs when publishing findings. 5. The published descriptor and live MCP schema supersede this file if a discrepancy appears. ## Golden Agent Workflows - **Reputation Manager** (`reputation-manager`, v1.0.0): Tracks harmful coverage, competitor wins, narrative spread, and the attention level that needs a response. About 4 calls per run. - **Partnership Scout** (`partnership-scout`, v1.0.0): Finds companies showing a current partnership signal and turns repeated coverage into one qualified opportunity. About 5 calls per run. - **Weekly Executive Brief** (`weekly-executive-brief`, v1.0.0): Delivers a fixed-format weekly briefing with market, company, risk, regulatory, and evidence sections. About 7 calls per run. - Setup: https://app.perception.to/app/agent-workflows - Runtime: Perception REST API for scheduled runs. MCP remains available for research and build-time exploration. - Activation: one delivered run with a future run scheduled within seven days. - MCP catalog: 32 registered tools, 31 metered research tools, and one unmetered taxonomy helper.