Public API Reference

Direct access to SagaDAO's snapshot data. Our API provides fast, cached access to holder information for Seeker and Saga Genesis collections.

Get Holders

            GET
            /api/public/holders
        

Retrieves a list of wallets holding the specified collection NFTs. Data is updated periodically via our snapshot system.

Query Parameters

Parameter	Type	Required	Description
type	string	Yes	Collection type: `'saga'`, `'seeker'`, or `'both'` for all collections.
wallet	string	No	Filter results for a specific wallet address. If not in cache, performs live on-chain verification.
limit	number	No	Maximum number of records to return. Default 1000, no maximum cap.
offset	number	No	Pagination offset. Default 0.
download	boolean	No	Set to `'true'` to download full dataset without limit.

Example Request

# cURL example
curl "https://www.sagadaobot.app/api/public/holders?type=saga&limit=5"
        

// JavaScript / Node.js
const fetch = require('node-fetch');

async function getHolders() {
    const response = await fetch('https://www.sagadaobot.app/api/public/holders?type=seeker&limit=10');
    const data = await response.json();
    console.log(data);
}

getHolders();
        

# Python
import requests

response = requests.get('https://www.sagadaobot.app/api/public/holders', params={
    'type': 'saga',
    'limit': 10
})

data = response.json()
print(data)
        

Response Structure

{
  "success": true,
  "type": "saga",
  "source": "cache_snapshot",
  "timestamp": "2026-03-16T20:30:00.000Z",
  "collections": ["Saga Genesis"],
  "data": [
    {
      "holder_address": "HeH3...92a1",
      "token_count": 3
    }
  ],
  "meta": {
    "count": 50,
    "totalCount": 17867,
    "limit": 50,
    "offset": 0,
    "isComplete": false
  }
}
        

Wallet Lookup Response

When using the wallet parameter, if the wallet is not in cache, the API performs live on-chain verification:

{
  "success": true,
  "type": "saga",
  "source": "live_verification",
  "timestamp": "2026-03-16T20:30:00.000Z",
  "collections": ["Saga Genesis"],
  "data": [
    {
      "holder_address": "7xKXt...abc",
      "collection_address": "46pcSL5...",
      "token_count": 1,
      "token_address": "NFT mint address"
    }
  ],
  "meta": { "verified": true, "cached": false }
}
        

Error Responses

If the request fails, the API returns a JSON object with success: false and an error message.

{
  "success": false,
  "error": "Invalid or missing type. Use 'saga', 'seeker', or 'both'."
}
        