API Keys (Optional)

deso-ag works without any keys — Lens, Nostr, and Bluesky trending all function keyless. For full functionality, these environment variables unlock additional networks:

Variable	Unlocks	How to Get
`NEYNAR_API_KEY`	Farcaster search + trending	Free at neynar.com
`BLUESKY_IDENTIFIER`	Bluesky search	Your handle (e.g. user.bsky.social)
`BLUESKY_APP_PASSWORD`	Bluesky search	bsky.app/settings/app-passwords

Without a key, that network is silently skipped. Everything else works normally.

Check which networks are available before running commands:

echo "Neynar: ${NEYNAR_API_KEY:+set}"
echo "Bluesky ID: ${BLUESKY_IDENTIFIER:+set}"
echo "Bluesky PW: ${BLUESKY_APP_PASSWORD:+set}"

Inform the user which networks will be included based on available keys.

Core Workflows

1. Search for Content

Use search to find posts about a topic. Always use --format compact for agent consumption.

# Basic search across all available networks
deso-ag search "ethereum" --format compact --limit 20

# Multi-word AND search (all terms must match)
deso-ag search "AI crypto" --format compact --limit 15

# Network-specific search
deso-ag search "NFT" --sources farcaster --format compact

# Channel-specific (Farcaster only)
deso-ag search --channel dev --sources farcaster --format compact

# Sort by recency for latest discussions
deso-ag search "base chain" --sort recent --format compact --limit 10

2. Get Trending Content

Use trending to see what's popular right now.

# Trending across all networks
deso-ag trending --format compact --limit 20

# Trending on specific networks
deso-ag trending --sources farcaster,lens --format compact

# Trending over the past week
deso-ag trending --timeframe week --format compact

3. Extract Discussion Terms

Use terms to discover the most-discussed topics, weighted by engagement.

# Top 3 terms per platform, last 24h
deso-ag terms --format json

# Top 5 terms from Farcaster this week
deso-ag terms --top 5 --sources farcaster --timeframe week --format json

# Terms across specific networks
deso-ag terms --top 5 --sources farcaster,nostr --format json

4. Browse Farcaster Channels

deso-ag channels --limit 20

Output Handling

Always use --format compact for search and trending commands. The compact format returns a single JSON object optimized for agent analysis:

{
  "meta": {
    "query": "...",
    "totalPosts": 42,
    "sources": [{"name": "farcaster", "count": 15}, ...],
    "timeframe": "24h",
    "fetchedAt": "2025-01-01T00:00:00.000Z"
  },
  "posts": [
    {
      "id": "...",
      "source": "farcaster",
      "author": "username",
      "content": "full untruncated content...",
      "timestamp": "2025-01-01T00:00:00.000Z",
      "url": "https://...",
      "score": 523,
      "engagement": {"likes": 400, "reposts": 50, "replies": 23},
      "tags": []
    }
  ]
}

The score field is pre-computed: likes + reposts×2 + replies. Use it for ranking.

For terms, use --format json which returns structured term frequency data.

Analysis Guidelines

After gathering data, synthesize findings into insights. Never just dump raw JSON to the user.

Summarize the landscape: How many posts found, across which networks, what timeframe
Highlight top content: Surface the highest-engagement posts with author, source, and brief summary
Identify themes: Group related posts and extract common threads
Provide engagement context: What content resonates most and why
Link to originals: Include post URLs so the user can engage directly

Only compare activity across networks if the user specifically asks for a cross-network comparison.

Example Analysis Output

Pulled 42 posts about "AI agents" from Farcaster (15), Lens (12), and Nostr (15) over the last 24h.

**The dominant conversation** is around autonomous agents that can transact onchain
without human approval. @dwr's post (score: 523) kicked this off by demoing an agent
that autonomously allocated funds across DeFi protocols based on real-time yield data.
The replies are split — builders are excited about composability (agents calling other
agents via onchain messages), while others are raising concerns about liability when
an agent makes a bad trade. @jessepollak responded pointing to Base's account
abstraction work as a potential guardrail layer.

**A second thread** is forming around agent-to-agent communication standards. Several
posts reference a draft spec for a messaging protocol between onchain agents. @stani
on Lens (score: 312) argued that without a shared standard, we'll end up with walled
agent ecosystems that can't interoperate — drawing a parallel to early social media
APIs. There's skepticism in the replies about whether standardization is premature
given how fast the space is moving.

**Smaller but notable:** 3-4 posts on Nostr are discussing privacy-preserving agents
that use zk proofs to verify actions without revealing the agent's strategy or
holdings. Early stage but worth watching.

**Key voices to follow on this topic:**
- @dwr (Farcaster) — actively building and demoing agent infra
- @jessepollak (Farcaster) — connecting this to Base ecosystem work
- @stani (Lens) — framing the standards/interop conversation

**Source posts:**
- [dwr's agent demo](https://...) — score: 523
- [stani on agent standards](https://...) — score: 312
- [jessepollak on account abstraction](https://...) — score: 287

Quick Command Reference

Command	Purpose	Default Sort	Default Format
`search [query]`	Find posts about a topic	relevance	markdown
`trending`	Popular content right now	engagement	summary
`terms`	Top discussion terms	—	—
`channels`	Browse Farcaster channels	—	—

Common Options

Option	Short	Values	Default
`--sources`	`-s`	farcaster,lens,nostr,bluesky	all
`--timeframe`	`-t`	24h, 48h, week	24h
`--format`	`-f`	json, markdown, summary, compact	varies
`--limit`	`-l`	any positive integer	25
`--sort`	`-o`	engagement, recent, relevance	varies
`--channel`	`-c`	channel ID (Farcaster only)	none
`--top`	`-n`	any positive integer (terms only)	3

For the full command reference with output schemas and library usage, see references/command-reference.md.

Error Handling

If deso-ag is not found, install it: npm install -g deso-ag
If no results return for a network, that network's API key is likely missing — inform the user
Nostr can be slow or inconsistent — retry once if it times out
If you hit rate limit errors, let the user know and suggest they run their own infrastructure for heavy usage

deso-research

deso-research

Prerequisites

Check Installation