Base Feed Alpha API Documentation

Overview

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

Base ALPHA API URL

http://3.85.164.95: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://3.85.164.95: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://3.85.164.95: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://3.85.164.95: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://3.85.164.95: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 the development team.