# Agent402 Farcaster User Search

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

Search Farcaster users by name or username fragment, returning profile details including FID, bio, follower counts, and primary Ethereum address

## Facts

- Endpoint: POST https://agent402.tools/api/fc-user-search
- Price: $0.003/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-15
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/agent402-farcaster-user-search-5ea03868
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_XylaXa_w2KvqGgYgdp1m-

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-user-search-5ea03868 -d '<json body>'
```

Example prompt: Search Farcaster for users matching 'vitalik', return up to 5 results with their FID, follower count, and Ethereum address.

## When to prefer this

Use this endpoint when you need to find Farcaster user profiles by name or username fragment, especially when you also need the user's linked Ethereum address or FID for downstream on-chain operations. Prefer this over generic social search when working within the Farcaster/web3 ecosystem, and when you want pay-per-call access without API key setup.

## Known failure modes

- Empty query or query exceeding 100 characters returns validation error
- Limit outside 1–10 range returns validation error
- Invalid or expired pagination cursor returns error or empty result
- No matching users found returns empty users array with count 0
- Rate limit exceeded returns 429 with resetAt timestamp
- Upstream Neynar API unavailability causes 5xx error

## How this service works

Search Farcaster users by name or username fragment. Returns up to 10 compact profiles: fid, username, display name, bio, follower and following counts, Neynar quality score, primary verified Ethereum address. Use to resolve a person or brand to a fid before fc-user-casts, or to find who to follow on a topic.

## Output

Returns a list of matching Farcaster user profiles (up to the requested limit), each containing FID, username, display name, bio, profile picture URL, Warpcast profile URL, follower count, following count, primary Ethereum address, power badge status, and a relevance score. Also includes pagination cursor for fetching more results, total count, cache status, data source, fetch timestamp, and rate limit details.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "q": {
   "type": "string",
   "description": "Name or username fragment (1-100 chars)."
  },
  "limit": {
   "type": "integer",
   "maximum": 10,
   "minimum": 1,
   "description": "Results per page (default 5)."
  },
  "cursor": {
   "type": "string",
   "description": "Opaque pagination cursor from a previous call's nextCursor."
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "count": 1,
  "query": "example",
  "users": [
   {
    "bio": "Example profile used only to show the response shape.",
    "fid": 3,
    "url": "https://warpcast.com/dwr",
    "score": 0.99,
    "pfpUrl": "https://imagedelivery.net/.../original",
    "username": "example-user",
    "powerBadge": false,
    "displayName": "Example User",
    "followerCount": 630338,
    "followingCount": 77,
    "primaryEthAddress": "0x6ce09ed5526de4afe4a981ad86d17b2f5c92fea5"
   }
  ],
  "cached": false,
  "source": "neynar",
  "fetchedAt": "2026-08-22T13:19:12.000Z",
  "rateLimit": {
   "limit": 300,
   "resetAt": "2026-08-22T13:20:00.000Z",
   "remaining": 299
  },
  "nextCursor": null
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/agent402-farcaster-user-search-5ea03868/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)