# Farcaster API
> A live window into Farcaster, the decentralised social network, as an API via the public Warpcast feed. Look a user up by username or FID for their profile (followers, following, bio); pull a user's recent casts (posts) with their likes, recasts and replies; browse the channels people post in, ranked by followers, or filter them; or open a single channel. The on-chain social graph delivered as clean JSON for social, web3 and dashboard apps. Live data, no key. Distinct from Mastodon, Bluesky and other social platforms — this is Farcaster.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/farcaster-api/..."
```

## Pricing
- **Free** (Free) — 500 calls/Mo, 5 req/s
- **Starter** ($10/Mo) — 13,500 calls/Mo, 15 req/s
- **Pro** ($23/Mo) — 64,000 calls/Mo, 30 req/s
- **Business** ($50/Mo) — 320,000 calls/Mo, 50 req/s

## Endpoints

### Users

#### `GET /v1/followers` — A user's followers, each with their profile

**Parameters:**
- `username` (query, optional, string) — Farcaster username Example: `dwr.eth`
- `fid` (query, optional, string) — Numeric FID Example: `3`
- `limit` (query, optional, string) — Max followers (1-100) Example: `25`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/farcaster-api/v1/followers?username=dwr.eth&fid=3&limit=25"
```

**Response:**
```json
{
    "data": {
        "fid": 3,
        "count": 25,
        "source": "Farcaster",
        "followers": [
            {
                "bio": "Brandon ⚡\nBuilding DreamNet — a living onchain AI organism 🧬🌐\nNeural lattice • Agents • Nodes • Evolution\nBase-aligned, chaos-friendly, creator-powered 🔥🐉",
                "fid": 1477142,
                "active": false,
                "pfp_url": "https://imagedelivery.net/BXluQx4ige9GuW0Ia56BHw/dc02c711-9086-4577-c151-eda7b9b02c00/original",
                "username": "ghostmintops",
                "followers": 679,
                "following": 1112,
                "power_badge": false,
                "profile_url": "https://warpcast.com/ghostmintops",
                "display_name": "ghostmintops"
            },
            {
                "bio": "private property some have no respect for other people's property",
                "fid": 1357302,
                "active": false,
                "pfp_url": "https://imagedelivery.net/BXluQx4ige9GuW0Ia56BHw/5a2717bd-8a5e-4596-12ba-67e920d4f600/original",
                "username": "ethergirl646",
                "followers": 36,
                "following": 64,
                "power_badge": false,
                "profile_url": "https://warpcast.com/ethergirl646",
                "display_name": "ethergirl646 Gail Cole"
            },
            {
                "bio": "Doctor❤️🌼",
                "fid": 1117360,
                "active": f
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/user` — A user's profile by username or fid

**Parameters:**
- `username` (query, optional, string) — Farcaster username Example: `dwr.eth`
- `fid` (query, optional, string) — Numeric FID (alternative to username) Example: `3`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/farcaster-api/v1/user?username=dwr.eth&fid=3"
```

**Response:**
```json
{
    "data": {
        "user": {
            "bio": "Interested in technology and other stuff.",
            "fid": 3,
            "active": false,
            "pfp_url": "https://imagedelivery.net/BXluQx4ige9GuW0Ia56BHw/bc698287-5adc-4cc5-a503-de16963ed900/original",
            "username": "dwr",
            "followers": 345106,
            "following": 77,
            "power_badge": false,
            "profile_url": "https://warpcast.com/dwr",
            "display_name": "Dan Romero"
        }
    },
    "meta": {
        "timestamp": "2026-06-09T03:03:08.119Z",
        "request_id": "03a205c5-d54f-4828-b5a4-49feef7024d2"
    },
    "status": "ok",
    "message": "User retrieved successfully",
    "success": true
}
```

### Casts

#### `GET /v1/cast` — One cast in full with its reply thread

**Parameters:**
- `hash` (query, required, string) — Cast hash (0x…, from /v1/casts) Example: `0x5e462315f1d12a2f8a579656c1455c5793964fac`
- `limit` (query, optional, string) — Max replies (1-50) Example: `20`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/farcaster-api/v1/cast?hash=0x5e462315f1d12a2f8a579656c1455c5793964fac&limit=20"
```

**Response:**
```json
{
    "data": {
        "url": "https://warpcast.com/dwr/0x5e462315",
        "hash": "0x5e462315f1d12a2f8a579656c1455c5793964fac",
        "text": null,
        "likes": 170,
        "author": "dwr",
        "source": "Farcaster",
        "channel": null,
        "recasts": 19,
        "replies": 15,
        "timestamp": "2026-06-02T00:23:37.000Z",
        "reply_thread": [
            {
                "url": "https://warpcast.com/thibauld/0x5ce69846",
                "hash": "0x5ce69846208f82bee3cf596fa1fc7c36f9876132",
                "text": "Paris? Versailles?",
                "likes": 3,
                "author": "thibauld",
                "channel": null,
                "recasts": 0,
                "replies": 0,
                "timestamp": "2026-06-03T13:32:51.000Z"
            },
            {
                "url": "https://warpcast.com/sardius/0xfa21a436",
                "hash": "0xfa21a436e5f0d2f207cf1c59b18e155e081a5c64",
                "text": "damn son where’d you find this",
                "likes": 3,
                "author": "sardius",
                "channel": null,
                "recasts": 0,
                "replies": 0,
                "timestamp": "2026-06-02T00:30:08.000Z"
            },
            {
                "url": "https://warpcast.com/cbeav/0xe30bbf10",
                "hash": "0xe30bbf108cef2427d2c938157880dafacb28ed1c",
                "text": "don’t be too ashamed to rent the little boat",
                "likes": 0,
      
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/casts` — A user's recent casts

**Parameters:**
- `username` (query, optional, string) — Farcaster username Example: `dwr.eth`
- `fid` (query, optional, string) — Numeric FID Example: `3`
- `limit` (query, optional, string) — Max casts (1-50) Example: `10`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/farcaster-api/v1/casts?username=dwr.eth&fid=3&limit=10"
```

**Response:**
```json
{
    "data": {
        "fid": 3,
        "casts": [
            {
                "url": "https://warpcast.com/dwr/0x5e462315",
                "hash": "0x5e462315f1d12a2f8a579656c1455c5793964fac",
                "text": null,
                "likes": 176,
                "author": "dwr",
                "channel": null,
                "recasts": 15,
                "replies": 15,
                "timestamp": "2026-06-02T00:23:37.000Z"
            },
            {
                "url": "https://warpcast.com/dwr/0xd91e39f1",
                "hash": "0xd91e39f1f09babe39ae5755eb876d54d20bc0cef",
                "text": null,
                "likes": 248,
                "author": "dwr",
                "channel": null,
                "recasts": 23,
                "replies": 20,
                "timestamp": "2026-05-15T23:20:40.000Z"
            },
            {
                "url": "https://warpcast.com/dwr/0xd04b5fa7",
                "hash": "0xd04b5fa7b7e345b91aa950b98ff130ab75f1a2be",
                "text": null,
                "likes": 171,
                "author": "dwr",
                "channel": null,
                "recasts": 10,
                "replies": 11,
                "timestamp": "2026-05-14T01:54:04.000Z"
            },
            {
                "url": "https://warpcast.com/dwr/0xcec60a65",
                "hash": "0xcec60a658b4e0329256820dcbd416440fa9bde13",
                "text": null,
                "likes": 282,
                "author": 
…(truncated, see openapi.json for full schema)
```

### Channels

#### `GET /v1/channel` — A single channel by id

**Parameters:**
- `channelId` (query, required, string) — Channel id Example: `farcaster`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/farcaster-api/v1/channel?channelId=farcaster"
```

**Response:**
```json
{
    "data": {
        "channel": {
            "id": "farcaster",
            "url": "https://warpcast.com/~/channel/farcaster",
            "name": "Farcaster",
            "lead_fid": 1,
            "followers": 445481,
            "image_url": "https://imagedelivery.net/BXluQx4ige9GuW0Ia56BHw/51ffff68-b05c-4465-37a3-38e0c9a21300/original",
            "description": "Discussions about Farcaster on Farcaster (meta!)"
        }
    },
    "meta": {
        "timestamp": "2026-06-09T03:03:09.272Z",
        "request_id": "dca6be47-1b6f-45ca-9b7c-edaa8f4ac9f9"
    },
    "status": "ok",
    "message": "Channel retrieved successfully",
    "success": true
}
```

#### `GET /v1/channels` — Channel directory ranked by followers

**Parameters:**
- `q` (query, optional, string) — Filter by name/id Example: `crypto`
- `limit` (query, optional, string) — Max results (1-100) Example: `25`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/farcaster-api/v1/channels?q=crypto&limit=25"
```

**Response:**
```json
{
    "data": {
        "count": 25,
        "query": null,
        "total": 16432,
        "channels": [
            {
                "id": "base",
                "url": "https://warpcast.com/~/channel/base",
                "name": "Base",
                "lead_fid": 12142,
                "followers": 480977,
                "image_url": "https://warpcast.com/~/channel-images/base.png",
                "description": "Bringing the world onchain — a community of builders on Base"
            },
            {
                "id": "farcaster",
                "url": "https://warpcast.com/~/channel/farcaster",
                "name": "Farcaster",
                "lead_fid": 1,
                "followers": 445481,
                "image_url": "https://imagedelivery.net/BXluQx4ige9GuW0Ia56BHw/51ffff68-b05c-4465-37a3-38e0c9a21300/original",
                "description": "Discussions about Farcaster on Farcaster (meta!)"
            },
            {
                "id": "memes",
                "url": "https://warpcast.com/~/channel/memes",
                "name": "Memes",
                "lead_fid": 576,
                "followers": 441637,
                "image_url": "https://imagedelivery.net/BXluQx4ige9GuW0Ia56BHw/b67f1620-f2c7-458a-7f8b-d2c1742d7300/original",
                "description": "Funny memes, wholesome memes, and everything in-between. Subscribe to earn."
            },
            {
                "id": "ethereum",
                "url": "https://warpcas
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Service metadata

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/farcaster-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "source": "Warpcast public API (live)",
        "service": "farcaster-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/user": "Profile by username (username=dwr.eth) or fid=.",
            "GET /v1/casts": "A user's recent casts (username= or fid=, limit).",
            "GET /v1/channel": "Single channel by id (channelId=farcaster).",
            "GET /v1/channels": "Channel directory ranked by followers (q= filter, limit)."
        },
        "description": "Live data from Farcaster, the decentralised social network, via the public Warpcast API: user profiles (by username or FID) with followers/following/bio, a user's recent casts with likes/recasts/replies, the channel directory ranked by followers, and single-channel lookup. Live, no key. Distinct from Mastodon, Bluesky and other social platforms.",
        "channels_indexed": 16432
    },
    "meta": {
        "timestamp": "2026-06-09T03:03:11.643Z",
        "request_id": "3b0c29af-d13f-4187-a35e-4f38c59d5555"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/farcaster-api
OpenAPI spec: https://www.oanor.com/api/farcaster-api/openapi.json