# Farcaster User Lookup

> Farcaster User Lookup is a paid API for AI agents from meryol-agenticmarket-x402.hf.space, paid per call via x402, $0.002/call, status unknown (last checked 2026-09-15).

Resolves a Farcaster identity (username, FID, or 0x address) and returns full profile metadata including social graph counts and verified addresses.

## Facts

- Endpoint: GET https://meryol-agenticmarket-x402.hf.space/farcaster/:query
- Price: $0.002/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-15
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/meryol-agenticmarket-x402-hf-space-f0b68446
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_BKSGemYYMcNUw6k3quRlZ

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 meryol-agenticmarket-x402-hf-space-f0b68446
```

Example prompt: What's the Farcaster profile for username dwr — give me their FID, bio, follower count, and any verified wallet addresses.

## When to prefer this

Use this endpoint when you need to resolve any Farcaster identity — username, FID, or Ethereum address — into a full social profile with verified wallet links. Ideal for social-aware agents that need to bridge onchain wallet addresses to Farcaster social identity, or vice versa. Prefer this over ENS resolution when the social graph context (followers, bio, pfp) matters, not just address mapping.

## Known failure modes

- User not found: all fields return null and notes includes 'user_not_found' — happens when the username/FID/address doesn't exist on Farcaster
- Invalid query format: malformed 0x address or non-existent FID may return null profile
- Payment failure: x402 payment of $0.002 USDC not processed, request blocked
- Rate limiting: too many requests in quick succession may be throttled
- Network error: upstream Farcaster hub unavailable, returns error or empty response

## How this service works

Counterparty identity check via Farcaster: pass username (no @) or FID integer. Returns FID, username, display name, bio, pfp URL, follower / following counts, custody address, and verified 0x addresses. Identity primitive for social-aware agents.

## Output

Returns a JSON object with FID (integer), username, display name, bio, profile picture URL, follower count, following count, custody address, and an array of verified 0x Ethereum addresses. If the user is not found, counts and string fields are null and notes contains 'user_not_found'.

## Example request

```json
{
 "input": {
  "type": "http",
  "method": "GET",
  "pathParams": {
   "query": "dwr"
  }
 }
}
```

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET",
      "HEAD",
      "DELETE"
     ],
     "type": "string"
    },
    "pathParams": {
     "type": "object",
     "required": [
      "query"
     ],
     "properties": {
      "query": {
       "type": "string",
       "description": "username, fid, or 0x address"
      }
     }
    },
    "queryParams": {
     "type": "object",
     "properties": {}
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object",
     "required": [
      "fid",
      "username"
     ]
    }
   }
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/meryol-agenticmarket-x402-hf-space-f0b68446/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from meryol-agenticmarket-x402.hf.space](https://www.zero.xyz/host/meryol-agenticmarket-x402.hf.space/llms.txt)