Perception REST API

Build on real-time narrative intelligence. Access sentiment, trends, entities, and market data for Bitcoin and digital assets via simple REST endpoints.

Endpoints

Authentication

All endpoints require an API key passed as a Bearer token: Authorization: Bearer pcp_...

Free tier: 5 requests/day. Paid plans start at $149/mo with 100 requests/day.

Use Cases

Related

Skip to content
BASE URLapi.perception.to

Digital asset intelligence, via API

1,000+ curated sources. Sentiment in under 3 minutes. Narrative trend clustering. Entity recognition. One REST API.

1,000+
Sources
<3 min
Tweet Latency
12
Endpoints
99.9%
Uptime
Get Your Free API Key

Four primitives, infinite applications

Every endpoint is designed for production use. Low latency, structured responses, consistent schemas.

Influencer & Social Tracking

Real-time narrative tracking for 100+ Key Opinion Leaders. Get sentiment leaderboards and individual narrative impact profiles.

Regulatory Temperature

Track "Legal Heat" by slicing data from official regulatory bodies and legal journals. Distinguish hard signal from social media noise.

Intelligence Fusion

Synthesized multi-signal briefs. We cross-reference analyst actions, sentiment surges, and regulatory filings into clinical intelligence.

Competitive Benchmarking

Compare "Share of Voice" and "Sentiment Authority" across competitors. Essential for Corporate Communications and Investor Relations.

Why our API vs the OpenAI or Anthropic API

Those APIs give you a model. Ours gives you a curated, structured, multi-year digital asset dataset. Different primitives, different jobs.

OpenAI / Anthropic API

Build it yourself

  • —You source, scrape, and clean the content
  • —You pay per token to score every article
  • —You build entity extraction, dedup, storage
  • —You wait five years for a real historical corpus
# Do it yourself with OpenAI / Anthropic
import openai, requests

# Step 1: Build your own scraper.
# Handle rate limits, user agents, paywalls, redirect chains.
articles = scrape_crypto_news_sites()

# Step 2: Pay per token to score every article.
sentiments = []
for article in articles:
    resp = openai.chat.completions.create(
        model="gpt-4o",
        messages=[{
            "role": "user",
            "content": f"Score sentiment: {article.content}"
        }]
    )
    sentiments.append(parse(resp))

# Step 3: Build your own entity extraction, dedup,
# confidence gating, aggregation, and storage layer.
# Keep this running for five years to build a corpus.
Perception API

Query the dataset directly

  • —1,000+ curated digital asset sources, always on
  • —Sentiment, entities, outlet bias already computed
  • —Five years of enriched history, queryable by date
  • —One request. Structured response. No pipeline to maintain.
# Same result with the Perception API
import requests

r = requests.get(
    "https://api.perception.to/feed",
    headers={"Authorization": "Bearer pcp_..."},
    params={
        "keyword": "bitcoin mining",
        "startDate": "2026-04-09",
        "endDate": "2026-04-16",
    },
).json()

# Every article is already curated, scored,
# entity-tagged, outlet-classified.
for a in r["data"]:
    print(a["Sentiment"], a["Outlet"], a["Title"])

# Five years of history available by changing
# the date range. That's the difference.

The model isn't the bottleneck. The corpus is. OpenAI and Anthropic give you the best language models on the planet. They don't give you a curated digital asset dataset because that isn't their business. Read the full argument →

Built for teams that move on narrative

Whether you're publishing stories, building models, or powering AI agents , Perception provides the intelligence layer.

Media & Publishers
Newsrooms, content teams

Enrich editorial workflows with real-time sentiment data. Surface emerging narratives for story leads. Track how your outlet's coverage compares to competitors.

/feed/trends/sentiment-metrics
Research & Analytics
Hedge funds, research desks

Backtest narrative-driven trading signals. Quantify media sentiment around earnings, regulation, and macro events. Entity-level coverage analysis for due diligence.

/grouped-data/fear-greed-index/trends
Developers & Builders
Dashboards, bots, agents

Build sentiment-aware applications. Power AI agents with real-time market context. Integrate narrative intelligence into existing data pipelines.

/feed/fear-greed-index/channel-volume

How it works

Get started in under a minute. Free tier includes 25 requests per day, no credit card required.

01

Create a free account

Sign up at app.perception.to. Email verification required, takes 30 seconds.

Sign up free
02

Generate your API key

Go to Settings > Integrations and click "Generate Key." Your key starts with pcp_ and works for both the REST API and MCP connections.

Go to Settings
03

Start querying

Base URL is api.perception.to. All responses are JSON. Free tier gives you 25 requests per day across all 7 endpoints.

Example Requests

# Search for Bitcoin ETF articles
curl "https://api.perception.to/feed?keyword=bitcoin+etf\
  &startDate=2026-03-08&endDate=2026-03-15&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get the Fear & Greed Index
curl "https://api.perception.to/fear-greed-index\
  ?startDate=2026-03-01&endDate=2026-03-15" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Entity recognition (POST)
curl -X POST "https://api.perception.to/grouped-data" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"startDate":"2026-03-01","endDate":"2026-03-15","groupBy":"companies"}'

API Reference

All endpoints are available at https://api.perception.to. Click any endpoint to expand full documentation.

Article Search

Search and filter across 1,000+ curated sources. Returns articles with sentiment classification, outlet metadata, and pagination.

Narrative Trends

AI-extracted trend clusters showing what the market is talking about. Trends are generated by analyzing content across all 1,000+ sources and grouping related narratives.

Sentiment Analytics

Historical sentiment data and the proprietary Perception Fear & Greed Index. Unlike price-derived indices, ours is based on the tone of actual market discussion.

Entity Recognition

NLP-powered company and entity mention tracking. Uses entity recognition rather than keyword matching, distinguishes company names from common words with high accuracy.

Commercial Intelligence

High-value narrative intelligence endpoints for institutional and enterprise users.

Article Schema

Every article in the Perception database follows this schema. Field names use PascalCase for legacy compatibility.

FieldTypeDescription
TitlestringArticle headline, or @handle for tweets
ContentstringFull article text or tweet body
Datestring (ISO 8601)Publication timestamp, UTC
URLstringSource URL
OutletstringSource name (e.g. Bloomberg, X, CoinDesk)
SentimentstringPositive, Neutral, or Negative
Outlet_CategorystringCrypto Media, Financial Media, Social Media, Regulatory, Podcast, GitHub
author_namestring | nullAuthor name (media articles only)
image_urlstring | nullArticle thumbnail or OG image

Authentication

Authenticate requests with a Bearer token in the Authorization header. API keys start with pcp_ and are generated from your dashboard.

Request Header

Authorization: Bearer pcp_a1b2c3d4e5f6...

Key Types

Personal Key
Generated at Settings → Integrations. One active key per account. Rate limits based on your subscription tier. Same key works for both the REST API and MCP connections.
Team Key
For organizations. Up to 5 keys with pooled monthly quotas. Managed at Settings → MCP Team. Per-key usage monitoring included.

Security

  • —Your key is shown once at creation. Store it securely — we only store a SHA-256 hash.
  • —Never expose your key in client-side code. Use server-to-server calls.
  • —Revoked keys stop working within 60 seconds. There is a 24-hour cooldown before generating a new key.
  • —Email verification is required before key generation.

Simple, transparent pricing

Start free. Same API key works for both REST API and MCP connections. Upgrade when you need more.

Free

$0
No credit card required
  • 25 requests / day
  • All 12 endpoints
  • Same key for MCP
  • Email verification only
Get API Key

Perception

$149/mo
For individuals
  • 50 requests / day
  • All 12 endpoints
  • Full-text article access
  • MCP for Claude, ChatGPT, Gemini
Subscribe

Intelligence

Popular
Custom
For power users
  • 100 requests / day
  • All 12 endpoints
  • Full-text article access
  • Priority support
Subscribe

MCP Team

Custom
For teams
  • 15,000 requests / month pooled
  • 5 API keys with per-key monitoring
  • Full-text article access
  • Team dashboard
Subscribe

Need higher volume, custom SLAs, or dedicated support? Book a call to discuss Enterprise pricing. All plans include MCP access for Claude, ChatGPT, and Gemini.

Pagination

The /feed endpoint supports cursor-based pagination via the page parameter.

Each response includes a pagination object with total, page, pageSize, totalPages, and hasNextPage. Increment page until hasNextPage is false.

Default page size is 50. Maximum is 100. Each paginated request counts as one API call against your rate limit.

Source Coverage

1,000+ continuously monitored sources across six categories. New sources added weekly.

Financial Media

50+

Bloomberg, Reuters, WSJ, CNBC, Forbes, Barron's, FT

Crypto Media

80+

CoinDesk, Cointelegraph, The Block, Decrypt, Bitcoin Magazine

Social Media

220+

Curated X/Twitter accounts, Reddit, LinkedIn, Stacker News

Regulatory

15+

SEC, CFTC, BIS, ECB, Federal Reserve, FCA, OCC

Podcasts & Video

40+

What Bitcoin Did, Bankless, Unchained, conference talks

Developer

20+

GitHub repos, protocol blogs, developer forums

Ready to integrate?

Free tier. No credit card. Start building in under a minute.

Get Your Free API KeyEmail Us

Questions? Email hello@perception.to

View pricing