# Agent402 Farcaster Cast Search

> Agent402 Farcaster Cast Search is a paid API for AI agents from agent402.tools, paid per call via x402, $0.005/call, status unknown (last checked 2026-09-14).

Search Farcaster casts (posts) by keyword, semantic meaning, or hybrid mode with optional filters for channel and author

## Facts

- Endpoint: POST https://agent402.tools/api/fc-cast-search
- Price: $0.005/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-14
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/agent402-farcaster-cast-search-585d32d7
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_HpIdcneLfj36LYEBEJNmZ

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability agent402-farcaster-cast-search-585d32d7 -d '<json body>'
```

Example prompt: Search Farcaster for the most recent casts mentioning 'x402' using hybrid mode, limit to 10 results, and only show posts from the 'ai-agents' channel.

## When to prefer this

Choose this endpoint when you need to search or monitor Farcaster (Warpcast) social content by keyword, semantic concept, or hybrid matching, especially when you want to filter by channel or specific author FID. Prefer this over general web search when the target audience is the Farcaster/web3 social graph. The semantic and hybrid modes make it suitable for concept-level discovery, not just exact keyword matching. Pay-per-call with no API key required makes it ideal for sporadic or agent-driven use cases.

## Known failure modes

- Query text exceeds 256 characters — request rejected
- Invalid mode or sort enum value — request rejected
- Limit outside 1-100 range — request rejected
- Invalid or expired pagination cursor — empty or error response
- No matching casts found — returns empty casts array with count 0
- Rate limit exceeded — 402 or rate-limit error with resetAt timestamp
- Network timeout to upstream Neynar API — 5xx error

## How this service works

Search Farcaster casts by keyword (literal, semantic or hybrid match), newest first, optionally filtered to one author or channel. Returns compact casts: hash, author (fid, username, follower count), text, timestamp, channel, reactions, reply count, embed URLs. Use for mention monitoring, sentiment sampling, or finding discussion of a token, product or topic.

## Output

Returns a JSON object containing an array of matching casts, each with its URL, hash, full text, author details (FID, username, display name, follower count), embeds, channel, reply/reaction counts, and timestamp. Also includes total count, query metadata, source attribution, cache status, rate limit info, and an opaque nextCursor for pagination.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "q": {
   "type": "string",
   "description": "Search text (1-256 chars)."
  },
  "mode": {
   "enum": [
    "literal",
    "semantic",
    "hybrid"
   ],
   "type": "string",
   "description": "Match mode (default literal)."
  },
  "sort": {
   "enum": [
    "desc_chron",
    "chron"
   ],
   "type": "string",
   "description": "Newest first (default) or oldest first."
  },
  "limit": {
   "type": "integer",
   "maximum": 100,
   "minimum": 1,
   "description": "Results per page (default 25)."
  },
  "cursor": {
   "type": "string",
   "description": "Opaque pagination cursor from a previous call's nextCursor."
  },
  "channel": {
   "type": "string",
   "description": "Only casts in this channel id (e.g. base)."
  },
  "authorFid": {
   "type": "integer",
   "description": "Only casts by this fid."
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "mode": "literal",
  "sort": "desc_chron",
  "casts": [
   {
    "url": "https://warpcast.com/askew-ai/0xab5aca84",
    "hash": "0xab5aca846db8af6fa3dc2d25dc66171cd040def4",
    "text": "Paid an x402 endpoint for the first time today.",
    "author": {
     "fid": 3117427,
     "username": "askew-ai",
     "displayName": "askew-ai",
     "followerCount": 12
    },
    "embeds": [
     "https://example.com/post"
    ],
    "channel": "ai-agents",
    "replies": 2,
    "reactions": {
     "likes": 4,
     "recasts": 1
    },
    "timestamp": "2026-08-22T12:49:27.000Z",
    "parentHash": null
   }
  ],
  "count": 1,
  "query": "x402",
  "cached": false,
  "source": "neynar",
  "channel": null,
  "authorFid": null,
  "fetchedAt": "2026-08-22T13:19:12.000Z",
  "rateLimit": {
   "limit": 300,
   "resetAt": "2026-08-22T13:20:00.000Z",
   "remaining": 299
  },
  "nextCursor": "eyJ0aW1lc3RhbXAiOi..."
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/agent402-farcaster-cast-search-585d32d7/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from agent402.tools](https://www.zero.xyz/host/agent402.tools/llms.txt)