Authentication

All embed APIs require authentication using API keys. This guide covers authentication methods for each API service.

Getting Your API Key

Get your API key from the embed Console. Your console API key starts with mbd- and works across all embed services.

Studio API

Base URL: https://api.mbd.xyz/v3/studio

The Studio API is the recommended way to build custom feed pipelines. It provides composable building-block services — Search, Features, Scoring, Ranking, and Stories — with full control over every stage.

Authentication Method

Include your console API key in the Authorization header using the Bearer scheme:

Authorization: Bearer mbd-{your-api-key}

The same console API key works across all Studio endpoints.

Endpoints

Service	Endpoint	Description
Search	`POST /search/filter_and_sort`	Structured search with filters and sorting
Search	`POST /search/boost`	Relevance-tuned search with boost filters
Search	`POST /search/semantic`	Embedding-based similarity search
Search	`GET /search/frequent_values/{index}/{field}`	Discover available field values
Features	`POST /features/v1`	Enrich items with ML-computed features
Scoring	`POST /scoring/ranking_model/{model}`	Rerank items using trained ML models
Ranking	`POST /ranking/feed`	Sort, diversify, and limit the final feed
Stories	`POST /stories/generate`	Generate personalized narrative content

Example

Search for trending Polymarket prediction markets:

curl -X POST "https://api.mbd.xyz/v3/studio/search/filter_and_sort" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "index": "polymarket-items",
    "size": 25,
    "sort_by": { "field": "volume_24hr", "order": "desc" },
    "include": [
      { "filter": "term", "field": "active", "value": true },
      { "filter": "numeric", "field": "liquidity_num", "operator": ">=", "value": 10000 }
    ]
  }'

Enrich results with personalization features for a wallet:

curl -X POST "https://api.mbd.xyz/v3/studio/features/v1" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user": {
      "index": "polymarket-wallets",
      "id": "0xf68a281980f8c13828e84e147e3822381d6e5b1b"
    },
    "items": [
      { "index": "polymarket-items", "id": "1289113" }
    ]
  }'

Code Examples

JavaScript/Node.js:

const MBD_BASE = "https://api.mbd.xyz/v3/studio";
const API_KEY = process.env.MBD_API_KEY; // your mbd- key

const response = await fetch(`${MBD_BASE}/search/filter_and_sort`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    index: "polymarket-items",
    size: 25,
    sort_by: { field: "volume_24hr", order: "desc" },
    include: [
      { filter: "term", field: "active", value: true },
      { filter: "numeric", field: "liquidity_num", operator: ">=", value: 10000 },
    ],
  }),
});

const data = await response.json();
console.log(data.result.hits);

Python:

import requests
import os

MBD_BASE = "https://api.mbd.xyz/v3/studio"
API_KEY = os.environ["MBD_API_KEY"]  # your mbd- key

response = requests.post(
    f"{MBD_BASE}/search/filter_and_sort",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "index": "polymarket-items",
        "size": 25,
        "sort_by": {"field": "volume_24hr", "order": "desc"},
        "include": [
            {"filter": "term", "field": "active", "value": True},
            {"filter": "numeric", "field": "liquidity_num", "operator": ">=", "value": 10000},
        ],
    },
)

data = response.json()
print(data["result"]["hits"])

Deploy API

Base URL: https://api.mbd.xyz/v3/studio/deploy

The Deploy API manages feed algorithms, configs, and production serving. It uses the same Bearer authentication as the Studio API.

Authentication Method

Authorization: Bearer mbd-{your-api-key}

Endpoints

Service	Endpoint	Description
Algo Builder	`POST /algo/compose`	Generate algorithm from natural language
Algo Builder	`POST /algo/validate`	Validate algorithm syntax and security
Algo Runner	`POST /run/algo`	Test algorithm in sandbox
Algorithms	`POST /deploy/algos`	Create algorithm
Algorithms	`GET /deploy/algos`	List algorithms
Configs	`POST /deploy/configs`	Create config
Configs	`GET /deploy/configs`	List configs
Serve	`POST /deploy/serve`	Serve feed by config ID
Serve	`GET /deploy/serve/page`	Paginate feed results
Serve	`GET /deploy/serve/new_items`	Get items since last serve
Serve	`POST /deploy/preview`	Preview config without saving
Cache	`POST /deploy/cache/clear`	Clear cached algorithm results

Example

Serve a deployed feed config:

curl -X POST "https://api.mbd.xyz/v3/studio/deploy/serve" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "config_id": 104,
    "inputs": {
      "farcasterFid": "16085",
      "polymarketWallet": "0xf68a281980f8c13828e84e147e3822381d6e5b1b"
    }
  }'

Alpha API

Base URL: https://api.mbd.xyz/v3/alpha

The Alpha API provides smart money signals, trader leaderboards, and notification delivery. It uses the same Bearer authentication as the Studio and Deploy APIs.

Authentication Method

Authorization: Bearer mbd-{your-api-key}

Endpoints

Service	Endpoint	Description
Signals	`GET /signals`	Get signal history with filtering and pagination
Signals	`GET /signals/performance`	Get signal performance metrics
Notifications	`GET /notifications`	Poll for new smart money notifications
Notifications	`DELETE /notifications`	Reset daily notification budget
Leaderboard	`GET /leaderboard`	Get ranked smart money wallets
Leaderboard	`GET /trader`	Get single trader profile
Config	`GET /config`	Get customer notification configuration
Config	`PUT /config`	Update notification configuration

Example

Get recent smart money notifications:

curl "https://api.mbd.xyz/v3/alpha/notifications?since=2026-03-30T00:00:00Z&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Responses

All APIs return standard HTTP status codes for authentication errors:

401 Unauthorized

Returned when:

The API key is missing
The API key is invalid or expired
The authentication format is incorrect

Example Response:

{
  "error": "AuthenticationError",
  "message": "Invalid or expired API key. Please check your credentials at console.mbd.xyz",
  "details": null
}

Common Issues

Missing Authorization Header — Ensure the Authorization header is included in all requests
Incorrect Authentication Format — Use Bearer mbd-{key}, not Basic or a bare key
Invalid API Key — Verify your key at console.mbd.xyz
Wrong Base URL:
- Studio API: https://api.mbd.xyz/v3/studio
- Deploy API: https://api.mbd.xyz/v3/studio/deploy
- Alpha API: https://api.mbd.xyz/v3/alpha

Security Best Practices

Never commit API keys to version control — Store keys in environment variables or a secrets manager
Use environment variables:
```
export MBD_API_KEY="mbd-your-key-here"
```
Rotate API keys regularly — Generate new keys periodically and revoke old ones
Use HTTPS only — All embed APIs require HTTPS. Never send keys over unencrypted connections
Use different keys per environment — Separate keys for development, staging, and production

Quick Reference

API	Base URL	Auth Header
Studio	`https://api.mbd.xyz/v3/studio`	`Authorization: Bearer mbd-{key}`
Deploy	`https://api.mbd.xyz/v3/studio/deploy`	`Authorization: Bearer mbd-{key}`
Alpha	`https://api.mbd.xyz/v3/alpha`	`Authorization: Bearer mbd-{key}`

Support

For authentication issues or questions:

Check your API key at console.mbd.xyz
Contact support: [email protected]