Build on the open social web. The DegenFeed API aggregates 9 decentralized and federated social networks into a single, ranked, real-time feed. All endpoints use the /v1/ prefix and require an API key.
All v1 API endpoints require authentication via an API key sent in the Authorization header:
Authorization: Bearer df_key_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxGenerate an API key from your profile settings. Each key can be limited to specific scopes:
| Scope | Permission | Endpoints |
|---|---|---|
| read:feed | Read feeds and search posts | Feed, search, discover, prices |
| write:posts | Publish and engage | Publish, engage (session required) |
| read:identity | Resolve identities | Identity resolution, profiles |
| write:tip | Send tips | Tip creation, invoices |
| read:analytics | Read analytics | Analytics endpoints |
Invalid or missing API keys return 401. Keys without sufficient scope return 403.
// 401 — Invalid key
{ "error": "Invalid or revoked API key" }
// 403 — Insufficient scope
{ "error": "Missing required scopes: write:tip" }API keys are rate-limited per key based on tier:
| Tier | Rate Limit | Window | Retry-After |
|---|---|---|---|
| Free | 1,000 req | 1 hour | Retry-After header (seconds) |
| Premium | 10,000 req | 1 hour | Retry-After header (seconds) |
When exceeded, the API returns a 429 response with a Retry-After header. The response body includes the tier, limit, and remaining retry time.
// 429 — Rate limit exceeded
{
"error": "Rate limit exceeded",
"retryAfterMs": 1800000,
"tier": "free",
"limit": 1000,
"window": "1h"
}/api/* routes are deprecated and will be removed on November 1, 2026. Migrate to /v1/* before then. Legacy routes include deprecation headers in responses.Base URL: https://degenfeed.xyz/v1/. All responses return JSON. Timestamps are in milliseconds since Unix epoch.
/v1/feed/homeAggregated and ranked feed from all protocols.read:feed/v1/feed/trendingTrending posts by engagement velocity.read:feed/v1/feed/newsCurated news feed from 353+ RSS sources.read:feed/v1/feed/streamServer-Sent Events real-time feed stream.read:feed/v1/feed/post/:postIdSingle post by canonical ID.read:feed/v1/feed/post/:postId/repliesThread/reply context for a post.read:feed/v1/feed/relatedRelated posts by niche overlap + time proximity.read:feed/v1/feed/:protocolPer-protocol feed: nostr, farcaster, lens, bluesky, mastodon, lemmy, reddit, rss.read:feed/v1/feed/category/:categoryFilter by niche category.read:feed/v1/feed/presetsAvailable feed presets.read:feed/v1/feed/homeprotocolsstringComma-separated: nostr,farcaster,lens,bluesky,mastodon,lemmy,reddit,rss (threads requires explicit opt-in; experimental)sortstringscored | hot | new | toplimitnumber1-200 posts per page (default 50)categorystringFilter: defi, ai, bitcoin, ethereum, solana, security, macrocursorstringPagination cursor timestampGET /v1/feed/home?protocols=nostr,farcaster&sort=hot&limit=10
{
"posts": [
{
"id": "nostr:note1...",
"protocol": "nostr",
"author": { "handle": "alice", "protocol": "nostr" },
"content": "Bitcoin is the future of money.",
"score": 89.4,
"engagement": { "likes": 42, "replies": 7, "reposts": 12 },
"timestamp": 1720000000000
}
],
"cursor": "1720000100000"
}/v1/feed/relatedidstringrequiredPost IDlimitnumberMax results (default 10)/v1/searchCross-protocol text search.read:feed/v1/search/identitySearch for identities across protocols.read:identity/v1/searchqstringrequiredSearch queryprotocolsstringComma-separated protocol filterlimitnumberMax results (default 25)GET /v1/search?q=bitcoin&protocols=nostr,farcaster&limit=10
{
"results": [
{ "id": "farcaster:0x...", "protocol": "farcaster", "content": "...", "author": { "handle": "bob" }, "score": 0.95 }
],
"total": 42
}/v1/identity/resolveResolve a handle across protocols.read:identity/v1/identity/profileCross-platform identity profile with linked accounts.read:identity/v1/identity/linkLink an identity from another protocol.read:identity/v1/identity/linkUnlink a previously linked identity.read:identity/v1/identity/resolvehandlestringrequiredHandle to resolve (e.g. vitalik.eth)GET /v1/identity/resolve?handle=vitalik.eth
{
"handle": "vitalik.eth",
"resolved": [
{ "protocol": "farcaster", "fid": 123, "username": "vitalik.eth" },
{ "protocol": "lens", "handle": "vitalik.lens" },
{ "protocol": "nostr", "npub": "npub1..." }
]
}/v1/identity/profilewalletstringWallet address for cross-protocol lookuphandlestringHandle to look up (legacy)/v1/tip/createSend a crypto tip (ETH, SOL, Lightning, Lens Collect).write:tip/v1/tip/resolveResolve available tipping methods for a post.write:tip/v1/tip/settingsGet tipping preferences for a user.read:feed/v1/tip/lightning/invoiceGenerate a Lightning invoice for a Nostr zap.write:tip/v1/tip/unified/statsCross-platform tip statistics.read:feed/v1/tip/unified/leaderboardTop tippers across all platforms.read:feed/v1/healthLegacy relay health status./v1/health/protocolsProtocol health — latency and uptime per provider./v1/statusAPI service status./v1/health{ "wss://relay.damus.io": "ok", "wss://nos.lol": "ok" }/v1/health/protocols{
"summary": { "up": 8, "degraded": 1, "down": 0, "total": 9 },
"protocols": [
{ "name": "nostr", "status": "up", "latencyMs": 120 },
{ "name": "farcaster", "status": "up", "latencyMs": 85 }
]
}/v1/communitiesList all communities across protocols.read:feed/v1/community/:nameGet community details by name.read:feed/v1/community/:name/feedGet community feed.read:feed/v1/communityCreate a new community (session required).read:feed/v1/community/:name/joinJoin a community (session required).read:feed/v1/content/*Resolve df:// content URIs to canonical posts.read:feed/v1/leaderboard/creatorsTop creators by engagement across protocols.read:feed/v1/leaderboard/tippersTop tippers by volume.read:feed/v1/leaderboard/trendingTrending authors right now.read:feed/v1/leaderboard/communitiesMost active communities.read:feed/v1/publishCross-post to connected protocols. Session required.write:posts/v1/engageLike, repost, reply, bookmark across protocols. Session required.write:posts/v1/analyticsAnalytics data.read:analytics/v1/notificationsUnified notification inbox.read:feed/v1/discoverDiscover trending content.read:feed/v1/discover/peopleWho to follow.read:feed/v1/pricesCrypto prices via CoinGecko./v1/embed/resolveFetch OpenGraph metadata for a URL.read:feed/v1/frame/resolveParse Farcaster Frame meta tags from a URL.read:feed/v1/frame/actionSubmit a Farcaster Frame button action.read:feed/v1/featuresFeature flags status./v1/pricesidsstringComma-separated coin IDs (e.g. bitcoin,ethereum,solana)GET /v1/prices?ids=bitcoin,ethereum
{ "bitcoin": { "usd": 60000 }, "ethereum": { "usd": 3400 } }# Get the trending feed
curl -H "Authorization: Bearer df_key_..." \
"https://degenfeed.xyz/v1/feed/home?sort=hot&limit=10"
# Search for Bitcoin posts
curl -H "Authorization: Bearer df_key_..." \
"https://degenfeed.xyz/v1/search?q=bitcoin&limit=5"
# Resolve an identity
curl -H "Authorization: Bearer df_key_..." \
"https://degenfeed.xyz/v1/identity/resolve?handle=vitalik.eth"
# Check protocol health (no auth required)
curl "https://degenfeed.xyz/v1/health/protocols"// Install: npm install @degenfeed/api-client
import { DegenFeedClient } from '@degenfeed/api-client';
const client = new DegenFeedClient({
apiKey: 'df_key_...',
});
// Get the trending feed
const feed = await client.feed.home({
protocols: ['nostr', 'farcaster'],
sort: 'hot',
limit: 20,
});
// Search
const results = await client.search.query('bitcoin');
// Resolve identity
const identity = await client.identity.resolve('vitalik.eth');
console.log(feed.posts, results.results, identity.resolved);// Or use fetch directly
const API_KEY = 'df_key_...';
const BASE = 'https://degenfeed.xyz/v1';
async function getFeed() {
const res = await fetch(`${BASE}/feed/home?sort=hot&limit=10`, {
headers: { Authorization: `Bearer ${API_KEY}` },
});
if (!res.ok) throw new Error(`API error: ${res.status}`);
return res.json();
}
async function searchIdentity(handle) {
const res = await fetch(`${BASE}/identity/resolve?handle=${handle}`, {
headers: { Authorization: `Bearer ${API_KEY}` },
});
return res.json();
}# Install: pip install degenfeed-client
from degenfeed import DegenFeedClient
client = DegenFeedClient(api_key="df_key_...")
# Get the trending feed
feed = client.feed.home(protocols=["nostr", "farcaster"], sort="hot", limit=20)
# Search
results = client.search.query("bitcoin")
# Resolve identity
identity = client.identity.resolve("vitalik.eth")
print(feed, results, identity)# Or use httpx directly
import httpx
API_KEY = "df_key_..."
BASE = "https://degenfeed.xyz/v1"
def get_feed():
res = httpx.get(
f"{BASE}/feed/home",
params={"sort": "hot", "limit": 10},
headers={"Authorization": f"Bearer {API_KEY}"},
)
res.raise_for_status()
return res.json()
def search_identity(handle: str):
res = httpx.get(
f"{BASE}/identity/resolve",
params={"handle": handle},
headers={"Authorization": f"Bearer {API_KEY}"},
)
return res.json()The legacy /api/* routes are deprecated. To migrate:
/api/ with /v1/ in all request pathsAuthorization: Bearer df_key_... header to all requestsDeprecation and Sunset response headers on legacy routes for the migration deadlineQuestions? Join our Developer Community. Report issues on Forgejo.