Get Posts

Retrieve all social posts collected for a specific token with pagination, filtering, and sorting options.

Note: Social data collection begins only after a token has migrated from a launchpad or has locked liquidity.

Endpoint

GET https://enterprise.guardis.io/v1/socials/posts

Authentication

Include your API key in the X-API-Key header.

X-API-Key: your_api_key_here

---

Query Parameters

Parameter	Type	Required	Description
token_address	string	Yes	The mint address of the token
page_number	integer	Yes	Page number for pagination (1-indexed)
page_size	integer	Yes	Number of posts per page (max 100)
ordering	string	Yes	Sort order in format field:direction
min_followers	integer	No	Filter for minimum follower count
max_followers	integer	No	Filter for maximum follower count
from_date	string	No	Filter posts created after this date (ISO 8601)
to_date	string	No	Filter posts created before this date (ISO 8601)

Ordering Format

The ordering parameter uses the format field:direction where:

Fields:

• created_at — Sort by post creation time

• followers_count — Sort by author's follower count

Directions:

• asc — Ascending order

• desc — Descending order

Examples:

• followers_count:desc — Highest follower accounts first

• created_at:asc — Oldest posts first

• created_at:desc — Newest posts first

---

Example Request

curl -X GET "https://enterprise.guardis.io/v1/socials/posts?token_address=5GTRGGnmbMCjCUnc3xMweCgVqDEtSDxTdvVdwutcpump&page_number=1&page_size=20&ordering=followers_count:desc&min_followers=1000" \
  -H "X-API-Key: your_api_key_here"

---

Response Format

{
  "token_address": "5GTRGGnmbMCjCUnc3xMweCgVqDEtSDxTdvVdwutcpump",
  "page_number": 1,
  "page_size": 20,
  "total_posts": 842,
  "total_pages": 43,
  "ordering": "followers_count:desc",
  "filters": {
    "min_followers": 1000,
    "max_followers": null,
    "from_date": null,
    "to_date": null
  },
  "posts": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "platform": "twitter",
      "post_id": "1867482918473650",
      "post_url": "https://twitter.com/whale_alert/status/1867482918473650",
      "author": {
        "username": "whale_alert",
        "display_name": "Whale Alert 🐋",
        "profile_url": "https://twitter.com/whale_alert",
        "followers_count": 2847291,
        "verified": true
      },
      "content": "🚨 Major accumulation detected on $PREDICT\n\n5 wallets just bought 2.4M tokens in the last hour\n\nSmart money is moving 👀",
      "sentiment": 0.84,
      "followers": 3532,
      "created_at": "2025-12-07T14:32:08.000Z",
      "collected_at": "2025-12-07T14:32:15.000Z"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-fg2345678901",
      "platform": "twitter",
      "post_id": "1867472847291847",
      "post_url": "https://twitter.com/crypto_trader/status/1867472847291847",
      "author": {
        "username": "crypto_trader",
        "display_name": "Crypto Trader",
        "profile_url": "https://twitter.com/crypto_trader",
        "followers_count": 847291,
        "verified": false
      },
      "content": "$PREDICT looking strong here. Cup and handle forming on the 4H. Entry at current levels looks good.\n\nNFA DYOR",
      "sentiment": 0.72,
      "followers": 3532,
      "created_at": "2025-12-07T13:45:22.000Z",
      "collected_at": "2025-12-07T13:45:30.000Z"
    },
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-ab3456789012",
      "platform": "twitter",
      "post_id": "1867462918473847",
      "post_url": "https://twitter.com/defi_analyst/status/1867462918473847",
      "author": {
        "username": "defi_analyst",
        "display_name": "DeFi Analyst 📊",
        "profile_url": "https://twitter.com/defi_analyst",
        "followers_count": 524891,
        "verified": true
      },
      "content": "Thread on $PREDICT fundamentals 🧵\n\n1/ Just did a deep dive on the tokenomics and on-chain data. Here's what I found...",
      "sentiment": 0.68,
      "followers": 3532,
      "created_at": "2025-12-07T12:30:00.000Z",
      "collected_at": "2025-12-07T12:30:08.000Z"
    }
  ]
}

---

Field Reference

Response Wrapper

Field	Type	Description
token_address	string	The mint address of the token
page_number	integer	Current page number
page_size	integer	Number of posts per page
total_posts	integer	Total number of posts matching filters
total_pages	integer	Total number of pages available
ordering	string	Applied sort order
filters	object	Applied filters
posts	array	Array of post objects

Post

Field	Type	Description
id	string	Unique identifier (UUID) for this post record
platform	string	Social platform (twitter, telegram, etc.)
post_id	string	Platform-specific post identifier
post_url	string	Direct URL to the post
author	object	Information about the post author
content	string	Text content of the post
sentiment	number	Sentiment score for this post (-1.0 to 1.0)
followers	number	The number of followers of the user
created_at	string	ISO 8601 timestamp when post was published
collected_at	string	ISO 8601 timestamp when post was collected by Guardis

Author

Field	Type	Description
username	string	Author's username/handle
display_name	string	Author's display name
profile_url	string	URL to author's profile
followers_count	integer	Author's follower count at time of collection
verified	boolean	Whether the account is verified

---

Example Usage

JavaScript:

async function fetchPosts(tokenAddress, options = {}) {
  const params = new URLSearchParams({
    token_address: tokenAddress,
    page_number: options.page || 1,
    page_size: options.pageSize || 20,
    ordering: options.ordering || "created_at:desc",
    ...(options.minFollowers && { min_followers: options.minFollowers }),
    ...(options.maxFollowers && { max_followers: options.maxFollowers }),
    ...(options.fromDate && { from_date: options.fromDate }),
    ...(options.toDate && { to_date: options.toDate })
  });

  const response = await fetch(
    `https://enterprise.guardis.io/v1/socials/posts?${params}`,
    {
      headers: {
        "X-API-Key": "your_api_key_here"
      }
    }
  );

  return response.json();
}

// Fetch top influencer posts
const data = await fetchPosts("5GTRGGnmbMCjCUnc3xMweCgVqDEtSDxTdvVdwutcpump", {
  ordering: "followers_count:desc",
  minFollowers: 10000,
  pageSize: 10
});

console.log(`Found ${data.total_posts} posts from accounts with 10k+ followers`);

for (const post of data.posts) {
  console.log(`\n@${post.author.username} (${post.author.followers_count.toLocaleString()} followers)`);
  console.log(`Sentiment: ${post.sentiment.toFixed(2)}`);
  console.log(`Engagement: ${post.engagement.likes} likes, ${post.engagement.retweets} RTs`);
  console.log(`Content: ${post.content.substring(0, 100)}...`);
}

Python:

import requests

def fetch_posts(token_address, page=1, page_size=20, ordering="created_at:desc", **filters):
    params = {
        "token_address": token_address,
        "page_number": page,
        "page_size": page_size,
        "ordering": ordering,
        **{k: v for k, v in filters.items() if v is not None}
    }
    
    response = requests.get(
        "https://enterprise.guardis.io/v1/socials/posts",
        params=params,
        headers={"X-API-Key": "your_api_key_here"}
    )
    
    return response.json()

# Fetch top influencer posts
data = fetch_posts(
    "5GTRGGnmbMCjCUnc3xMweCgVqDEtSDxTdvVdwutcpump",
    ordering="followers_count:desc",
    min_followers=10000,
    page_size=10
)

print(f"Found {data['total_posts']} posts from accounts with 10k+ followers")

for post in data["posts"]:
    print(f"\n@{post['author']['username']} ({post['author']['followers_count']:,} followers)")
    print(f"Sentiment: {post['sentiment']:.2f}")
    print(f"Engagement: {post['engagement']['likes']} likes, {post['engagement']['retweets']} RTs")
    print(f"Content: {post['content'][:100]}...")

# Paginate through all results
def fetch_all_posts(token_address, **filters):
    all_posts = []
    page = 1
    
    while True:
        data = fetch_posts(token_address, page=page, **filters)
        all_posts.extend(data["posts"])
        
        if page >= data["total_pages"]:
            break
        page += 1
    
    return all_posts

# all_posts = fetch_all_posts("5GTRGGnmbMCjCUnc3xMweCgVqDEtSDxTdvVdwutcpump", min_followers=1000)

---

Error Responses

Status Code	Description
400	Missing required parameters or invalid values
401	Missing or invalid API key
404	Token not found or social tracking not yet active
422	Invalid ordering format, date format, or pagination values
500	Internal server error

{
  "code": 400,
  "message": "Missing required parameter: ordering"
}

{
  "code": 422,
  "message": "Invalid ordering format. Use 'field:direction' (e.g., 'created_at:desc')"
}

{
  "code": 422,
  "message": "Invalid ordering field. Valid fields: created_at, followers_count"
}

{
  "code": 422,
  "message": "page_size must be between 1 and 100"
}