Knowledge Center

Base NFT & Token Feeds

Suggest Edits

Base Feed Alpha API Documentation

Overview

The Base Feed API provides personalized and popular feed recommendations for Base tokens and NFTs, enriched with metadata. This API is designed to help users discover relevant tokens and NFTs based on their wallet activity and general popularity.

How does it work?

We use multiple custom machine learning and AI models to score content and wallets and predict the probability of every wallet on Base making a Swap or a Mint in the future. Our ranking models use advanced Transformer architectures (LLM-like models but where words are actions) and online learning so that the recommendations change in real time based on the latest wallet action onchain.


Demo

You want to see how the Token & NFT Feed looks like for you? Head to our playground here: http://alpha-api.mbd.xyz:8506, add your Wallet address, and enjoy our recommendations, you can simulate actions on tokens you find interesting on Base, and the feed will refresh in realtime showing you more of what you like!

Base ALPHA API URL

http://alpha-api.mbd.xyz:8000

Authentication

No authentication is required for the current alpha version.

Endpoints

1. Get Personalized Feed

Returns personalized recommendations for a specific wallet address.

GET /base/feed/for-you/{wallet_address}

Parameters

  • wallet_address (path parameter): Ethereum wallet address
  • top_k (query parameter, optional): Number of recommendations to return (default: 25, min: 1, max: 500)

Example Request

curl "http://alpha-api.mbd.xyz:8000/base/feed/for-you/0x742d35Cc6634C0532925a3b844Bc454e4438f44e?top_k=5"

Example Response

{
  "status": "success",
  "items": [
    {
      "itemId": "base.0x333333c465a19c85f85c6cfbed7b16b0b26e3333",
      "score": 0.0824,
      "metadata": {
        "name": "ORA Coin",
        "symbol": "ORA",
        "decimals": 18,
        "chain": "base",
        "prices": [
          {
            "marketplace_id": "uniswap_v3_10000",
            "marketplace_name": "Uniswap V3 1.00%",
            "value_usd_cents": 52,
            "value_usd_string": "0.5202",
            "value_usd_string_high_precision": "0.5202424288",
            "liquidity_usd_string": "1454409.12"
          }
        ],
        "holder_count": 92763,
        "supply": "32216648304476000000000000"
      }
    }
  ]
}

2. Get Popular Feed

Returns popular items across all users.

GET /base/feed/popular

Parameters

  • top_k (query parameter, optional): Number of recommendations to return (default: 25, min: 1, max: 500)

Example Request

curl "http://alpha-api.mbd.xyz:8000/base/feed/popular?top_k=5"

Example Response

Same structure as the personalized feed response.

3. Record Event

Record user interaction events for improving recommendations.

POST /base/events

Request Body

{
  "wallet_address": "string",
  "item_id": "string",
  "event_type": "string"
}

Example Request

curl -X POST "http://alpha-api.mbd.xyz:8000/base/events" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "item_id": "base.0x333333c465a19c85f85c6cfbed7b16b0b26e3333",
    "event_type": "mint"
  }'

Example Response

{
  "status": "success",
  "message": "Event mint recorded successfully"
}

Item Types and Metadata

The API returns two types of items:

Tokens

  • Identified by: chain.contract_address
  • Metadata includes:
    • Name
    • Symbol
    • Decimals
    • Chain
    • Prices (from various DEXes)
    • Holder count
    • Total supply
    • Creation info

NFTs

  • Identified by: chain.contract_address.token_id
  • Metadata includes:
    • Name
    • Collection name
    • Image URL
    • Description
    • Attributes
    • Creator info

Rate Limits

The alpha version currently has no rate limits implemented, but please be considerate with your API usage.

Error Handling

The API uses standard HTTP status codes:

  • 200: Success
  • 400: Bad Request (e.g., invalid wallet address)
  • 500: Internal Server Error

Error responses include a detail message explaining the error.

Example Code

Python example using the requests library:

import requests

BASE_URL = "http://alpha-api.mbd.xyz:8000"

# Get personalized recommendations
wallet_address = "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
response = requests.get(
    f"{BASE_URL}/base/feed/for-you/{wallet_address}",
    params={"top_k": 5}
)
recommendations = response.json()

# Get popular items
response = requests.get(
    f"{BASE_URL}/base/feed/popular",
    params={"top_k": 5}
)
popular_items = response.json()

Support

This is an alpha version and under active development. For issues or questions, please contact by email here: [email protected] or message us directly on Farcaster: https://warpcast.com/mbd or X: https://x.com/mbdtheworld

Updated 13 days ago