Welcome to ❜embed!

You're about to unlock real-time AI superpowers for your Web3 app. With just a few lines of code, you'll be running world-class recommendation models—serving fun, fast, and hyper-personalized content to your users.

To get started with ❜embed:

Create an account
Copy your API key
Call a ❜embed API

1. Create an ❜embed account

Head to the ❜embed Console and sign up to get started.

2. Copy your API key

Once inside the Console, your API key is already generated. Click the "eye" icon to reveal it—or just copy it. You'll use this in your API calls.

3. Call an ❜embed API

Let's make your first call using the /for-you endpoint—our personalized feed API.

To get started, install the TypeScript SDK using your preferred package manager:

# Using Bun (recommended)
bun install @embed-ai/sdk

# Or using npm
npm install @embed-ai/sdk

# Or using yarn
yarn add @embed-ai/sdk

Now we can use it to get a client and call the Feed endpoint to get a For You Feed for our sample Farcaster user with FID 16085. We'll get 10 items for the feed (see top_k).

import { getClient } from "@embed-ai/sdk";

// using the API_KEY_EMBED environment variable
const key = process.env.API_KEY_EMBED!;

// get the embed sdk client with your API Key
const client = getClient(key);

// Get a For You feed for user with FID 16085, using template feed feed_390
// The SDK automatically handles errors and retries with exponential backoff
const feed = await client.feed.byUserId("16085", "feed_390", { top_k: 10 });

console.log(feed);

💡 Using Template Feeds

We're using feed_390, a publicly available template feed ("For You") that works with any valid API key.

✅ No setup required - use it immediately

✅ Works with any API key

✅ Perfect for testing and getting started

You can find other template feeds (feed_624, feed_625, etc.) in the SDK Quickstart guide, or create your own custom feed in the Embed Console.

Learn how to use the SDK here with the ❜embed SDK Quickstart guide.

In case you intend to not use the SDK you can call the API directly. To get types on returns and input options you may install embed-ai/types from NPM or use it to derive types for your language of choice like Python.

Minimum example

You just need:

Your API key (passed via the authorization header)
A feed_id (use feed_390 for the "For You" template feed, or create your own in the Console)
A user_id (typically the viewer's Farcaster fid) or a wallet_address

const options = {
  method: "POST",

  headers: {
    accept: "application/json",

    "content-type": "application/json",

    authorization: "Bearer <YOUR-API-KEY>",
  },

  body: JSON.stringify({
    feed_id: "feed_390",

    user_id: "3",
  }),
};

fetch("https://api.mbd.xyz/v2/farcaster/casts/feed/for-you", options)
  .then((res) => res.json())
  .then(console.log)
  .catch(console.error);

Quick test with curl:

curl --request POST \
  --url https://api.mbd.xyz/v2/farcaster/casts/feed/for-you \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'authorization: Bearer YOUR-API-KEY' \
  --data '{
    "feed_id": "feed_390",
    "user_id": "3"
  }'

Using wallet_address instead of user_id:

You can also use a wallet address to get personalized feeds:

const options = {
  method: "POST",
  headers: {
    accept: "application/json",
    "content-type": "application/json",
    authorization: "Bearer <YOUR-API-KEY>",
  },
  body: JSON.stringify({
    feed_id: "feed_390",
    wallet_address: "0x1234567890123456789012345678901234567890",
    return_metadata: true,
  }),
};

Sample response


{

  "status_code": 200,

  "body": [

    {

      "score": 0.001231,

      "source_feed": "main",

      "item_id": "0xc7525f91f7de1e27ed1b101cac98ea20182d2618"

    },

    ...

  ]

}

Response Fields Explained

• item_id: The cast hash. Use it with other ❜embed APIs or to link to the original cast
• score: Relevance score for this user (0-1 range). Higher scores indicate better matches
• source_feed: Indicates the origin of the item (main, promotions, warmup, etc.)
• popular_score: Popularity ranking score (when available)
• trending_score: Trending ranking score (when available)
• adjusted_score: Final combined score used for ranking (when available)

Rendering the feed

To display actual cast content, pass return_metadata: true in your request. This gives you everything needed to render posts in your UI. For hydration make sure you set the return_metadata property to true!

const options = {
  method: "POST",
  headers: {
    accept: "application/json",
    "content-type": "application/json",
    authorization: "Bearer <YOUR-API-KEY>",
  },
  body: JSON.stringify({
    feed_id: "feed_390",
    user_id: "3",
    return_metadata: true,
  }),
};

fetch("https://api.mbd.xyz/v2/farcaster/casts/feed/for-you", options)
  .then((res) => res.json())
  .then(console.log)
  .catch(console.error);

There are easy guides and ready made components available to get you a feed! Learn more in the guide on how to Render a Feed in a Farcaster Mini App using React

Sample with metadata


{

  "status_code": 200,

  "body": [

    {

      "score": 0.001231,

      "source_feed": "main",

      "item_id": "0xc7525f91f7de1e27ed1b101cac98ea20182d2618",

      "metadata": {

        "text": "ok i think i just stopped posting here...",

        "embed_items": [

          "https://imagedelivery.net/BXluQx4ige9GuW0Ia56BHw/e349139c-6d16-42c6-4f51-b0479d310d00/original"

        ],

        "timestamp": 1730748361,

        "author": {

          "user_id": 662851,

          "username": "littlesilver",

          "display_name": "Bartholomew Littlesilver",

          "pfp_url": "https://imagedelivery.net/BXluQx4ige9GuW0Ia56BHw/cf8cd550-4b72-4ce3-d262-5d99a0040900/original"

        },

        "ai_labels": {

          "topics": ["diaries_daily_life"],

          "sentiment": ["neutral"],

          "emotion": ["joy"]

        }

      }

    }

  ]

}

Common Issues

"feed_id or filters is required" error

Make sure you're including feed_id: "feed_390" in your request body. Template feeds like feed_390 are publicly available and work with any valid API key.

401 Unauthorized

Check that your API key is correct
Ensure you're using Bearer prefix in the authorization header: Bearer YOUR-API-KEY
Verify your API key hasn't been revoked in the Console

404 Not Found

Double-check the endpoint URL: https://api.mbd.xyz/v2/farcaster/casts/feed/for-you
Ensure you're using POST method, not GET

Empty or no results

Try a different user_id - some users may have limited interaction history
Verify the feed_id exists (template feeds like feed_390 should always work)
Check that return_metadata: true is set if you're expecting metadata

Rate Limiting

The SDK automatically handles retries with exponential backoff. For direct API calls, implement retry logic or use the SDK for built-in error handling.

Other Data Sources

❜embed supports feeds from multiple data sources beyond Farcaster:

Zora Coins

Get personalized recommendations for Zora coins (NFTs on Zora). Create a feed configuration with candidate_source: "zora-coins" in the Embed Console, then use the same endpoint structure:

const options = {
  method: "POST",
  headers: {
    accept: "application/json",
    "content-type": "application/json",
    authorization: "Bearer <YOUR-API-KEY>",
  },
  body: JSON.stringify({
    feed_id: "your_zora_feed_id", // Create a feed with candidate_source: "zora-coins"
    user_id: "3",
    return_metadata: true,
  }),
};

fetch("https://api.mbd.xyz/v2/farcaster/casts/feed/for-you", options)
  .then((res) => res.json())
  .then(console.log);

Template feed: feed_624 is a ready-to-use Zora feed you can try.

📝 Coming Soon: Full Zora feed documentation with examples for filtering by market metrics, publication types, and more.

Polymarket Markets

Get personalized prediction market recommendations from Polymarket. Uses a dedicated endpoint with wallet-based personalization:

const options = {
  method: "POST",
  headers: {
    accept: "application/json",
    "content-type": "application/json",
    authorization: "Bearer <YOUR-API-KEY>",
  },
  body: JSON.stringify({
    user_id: "0x1234567890123456789012345678901234567890", // Wallet address required
    top_k: 25,
    return_metadata: true,
    filters: {
      scoring: "hrnn_v0", // Personalized reranking
      candidate_filters: {
        limit: 500,
        include: [
          {
            filter: "term",
            field: "active",
            value: true,
          },
        ],
      },
    },
  }),
};

fetch("https://polymarket-api.getembed.ai/for-you", options)
  .then((res) => res.json())
  .then(console.log);

📝 Coming Soon: Complete Polymarket API documentation with examples for filtering by volume, liquidity, AI labels, and market dates.

What's Next?

Now that you've made your first API call, here are some next steps:

Customize Your Feed: Create your own feed configuration in the Embed Console to customize content, filters, and ranking
Explore Template Feeds: Try other template feeds like:
- feed_624 - Zora Feed (Zora coins)
- feed_625 - Short Form Video
- feed_626 - Miniapps
- See all templates in the SDK Quickstart
Build Your UI: Follow the guide on Rendering a Feed in a Farcaster Mini App using React
Learn More: Explore our guides on:

That's it!

You've just created your first personalized feed with ❜embed—and you can render it however you like.