Posts API

Superhero posts live on chain; this API is the indexed, queryable copy. Use it to read a feed, load a thread, search post content, or find everything one account has written.

All paths are relative to https://api.superhero.com. Reads need no authentication. Posting is a contract call, not a REST operation. See Posting.

Endpoints

PostDto

A single-post read also carries slug, updated_at, post_id (the parent, null on a top-level post), is_hidden, token_mentions and version.

PostTrendMentionDto turns a #HASHTAG in the body into a renderable price chip:

type

On a single post, type is the contract entrypoint that created it, or unknown. The posting contract is one deployment per network (ct_2Hyt9ZxzXra5NAzhePkRsDPDWppoatVD7CtHnUoHVbuehwR8Nb on mainnet). On the list endpoints type is always the literal post.

Whether a post is a comment, hidden, or generated by a token launch or trade is encoded in the transaction's second argument, a string array carrying comment:<parentId>, hidden, bcl: or bcl-tx:. A comment surfaces as a non-null post_id.

GET /api/posts

# Newest 20 posts mentioning a topic
curl -s "https://api.superhero.com/api/posts?topics=superhero&order_by=created_at&order_direction=DESC&limit=20"

GET /api/posts/popular

Ranking is all-time with a freshness boost for new posts; window is accepted and ignored. Eight per-request weights tune it, each low, med (the default) or high:

Defaults are page=1 and limit=50. debug=1 returns the ranking breakdown alongside the items. Note the casing: tipsAmountAE has a capital AE; the rest are lowerCamelCase.

# A feed that leans on tips rather than comments
curl -s "https://api.superhero.com/api/posts/popular?limit=20&tipsAmountAE=high&comments=low"

GET /api/posts/{id}

One post, by either its id or its slug:

curl -s "https://api.superhero.com/api/posts/hello-world-2f8a91c4"

A hidden post is a 404. The path segment must start with a letter or digit and may then contain letters, digits and . _ ~ : -, up to 128 characters; anything else is a 400.

A slug is the first 60 characters of the content, lowercased, with everything that is not a letter, digit, ., _, ~ or - collapsed to a single -, then the first underscore-delimited segment of the post id. Slugs are not guaranteed unique; prefer the id.

GET /api/posts/{id}/comments

Paginated thread under a post. Takes order_direction (ASC or DESC), limit and page; there is no order_by; comments are ordered by time. Comments are posts, so items follow the PostDto shape.

GET /api/feed

The combined home feed, and the only cursor-paginated endpoint in the API.

sort=latest is a keyset-paginated union of posts, token creations and trades. sort=hot returns posts only, ranked by the same algorithm as /api/posts/popular. Responses are cached for 15 seconds.

{
  "items": [
    { "type": "post", "created_at": "2026-09-13T09:14:02.000Z", "data": {} }
  ],
  "next_cursor": "..."
}

Each item is a discriminated union:

next_cursor is null on the last page; pass it straight back as cursor and do not parse it. A cursor minted under one sort is ignored by the other, so switching sort restarts from the top.

Topics

A topic is a hashtag with a post count. GET /api/topics/name/{name} returns the topic with its posts array and post_count. GET /api/topics takes order_by of name, post_count or created_at, plus order_direction, search, limit and page. GET /api/topics/{id} accepts either a UUID or a name.

curl -s "https://api.superhero.com/api/topics/popular/trending"

See Trending & Topics for the topic row and how a tag maps to a token.

Tips

GET /api/tips/posts/{postId}/summary returns totalTips, an AE total as a decimal string. Parse it rather than comparing it. It 404s for an unknown post id.

curl -s "https://api.superhero.com/api/tips/posts/123/summary"

GET /api/tips lists individual tips, ordered by amount, type or created_at, with filters for sender, receiver, type and post_id. Combine post_id and receiver to list who tipped a post:

curl -s "https://api.superhero.com/api/tips?post_id=123&receiver=ak_YOUR_ADDRESS&order_by=created_at&order_direction=DESC&limit=100"

order_by=amount sorts numerically, not lexically.

GET /api/tips/accounts/{address}/summary returns two AE totals as decimal strings, both excluding self-tips:

{ "totalTipsSent": "12.5", "totalTipsReceived": "3.25" }

Posting analytics

Three endpoints under /api/posts/analytics, all taking start_date and end_date as YYYY-MM-DD. Defaults are the last 10 days. A start after the end, or an unparseable date, is a 400.

GET /api/posts/analytics

A bare array, one element per day, computed live:

Hidden posts are excluded throughout. sender_address scopes every figure to one author. GET /api/posts/analytics/past-24-hours returns the same object for a rolling 24-hour window.

GET /api/posts/analytics/top-posters

limit defaults to 10 and is clamped to 1–100. Each item:

sender_address · total_posts · total_comments · total_all · public_name

Ordered by total_all descending. public_name falls back to the address when no profile exists, so it is never null.

GET /api/posts/analytics/top-topics

Each item is topic_id, topic_name and post_count for the range, ordered by post_count descending. Same limit handling.

GET /api/posts/analytics/preview is a server-rendered HTML dashboard, not JSON.

Related

• API Conventions: the pagination envelope and the endpoints that differ from it
• Trending & Topics: the tag surface these posts reference
• Profile API: resolving sender_address to a display name
• Posting: how a post gets on chain
• The feed: what the ranking is trying to achieve