Skip to content

Indexer API ​

Production base URL: https://api.mochi.meme. Local development: http://localhost:8787.

The indexer returns candidate lists and content. It does not rank: every score is an eth_call to the contracts. See System architecture.

Authentication ​

When enabled, the invite gate protects content routes. /health and sign-in endpoints stay open; /gate/invites separately requires an account session. Content requests carry the mochi_gate cookie issued by POST /gate or POST /gate/session. The cookie is verified with HMAC over the same secret the web middleware uses.

CORS allows only the origins in WEB_ORIGINS configured with WEB_ORIGINS (localhost is allowed during development). Requests carry credentials; * is not allowed because the cookie is attached.

bash
# /health stays open without an invitation
curl http://localhost:8787/health

Endpoint summary ​

MethodPathParametersReturns
GET/health—Liveness, cursor, post count
GET/strategies—List of valid strategies
GET/candidatesstrategy, limit, community, viewer{ strategy, ids }
GET/postsids, viewer{ posts }
GET/communitiesq, viewer, limit, offset{ communities }
GET/communities/:nameviewer{ community } or 404
GET/profile/:addresslimit{ profile, ids, commentIds }
GET/by-handle/:handle—{ address } or 404
GET/by-handle/:handle/:n—{ id } or 404
GET/by-author/:address/:n—{ id } or 404
GET/searchq, limit{ results }
GET/notifications/:addresslimit{ notifications }
GET/activitycommunities, since, limit{ activity }
GET/replies/:idlimit{ ids }
GET/thread/:id—{ ids }
POST/gateform code, next303 + set-cookie
GET/gate/status—{ enabled, open, address }
POST/gate/challengeJSON address{ id, message }, expires in 5 minutes
POST/gate/sessionJSON id, signatureverifies wallet, sets cookies
GET/gate/invitesaccount session cookieown codes, remaining, joined
POST/gate/logout—revokes session, clears cookies, JSON
POST/gate/out—303, clears cookie
POST/push/subscribeJSON subscription + prefs{ ok }
POST/push/prefsJSON address, prefs{ ok }
POST/push/unsubscribeJSON endpoint{ ok }
POST/mediamultipart file{ cid, uri }
POST/dripJSON address{ ok, already | funded | txHash }

/health ​

Open route. live is the signal to trust:

json
{
  "ok": true,
  "reachable": true,
  "live": true,
  "tailAgeMs": 1200,
  "posts": 4213,
  "cursor": 63656426,
  "head": 63412000,
  "blocksSinceLastEvent": 32110
}
FieldMeaning
reachableWhether the latest head block can be read
liveTail just touched the chain within the heartbeat threshold
tailAgeMsHow long since the tail touched the chain; null if never
cursorLast block with an event. Does not advance when the chain is quiet
headLive-read head block, null if unreachable
blocksSinceLastEventhead − cursor. High is normal, not lag

Reading it correctly

cursor stands still on a quiet chain while the indexer is running fine. Trust live, not the block gap.

/strategies ​

json
{ "strategies": ["recent", "popular", "trending", "community", "joined"] }

/candidates ​

Selects the posts an algorithm will consider. Comments are always excluded from every strategy: a comment detached from its thread is a fragment, and the ranking contract has no way to know that.

ParameterDefaultNotes
strategyrecentAn invalid name also falls back to recent
limit500Clamped to 1…1000
community—Required with strategy=community
viewer—Required with strategy=joined

The five strategies:

StrategySourceOrder
recentAll root posts (parentId = "0")Newest first
popularRoot posts with a non-empty communityNewest first
trendingRoot posts within 24 hoursMost active likes first, then newest
communityRoot posts in the community communityNewest first
joinedRoot posts in communities viewer has joinedNewest first

popular skips posts with no community label; posts are immutable, so filtering is the only honest way to exclude them from this one feed.

json
{ "strategy": "popular", "ids": ["1042", "1039", "1031"] }
bash
curl -H 'Cookie: mochi_gate=...' \
  'http://localhost:8787/candidates?strategy=trending&limit=200'

/posts ​

Returns content for a list of ids. ids is a comma-separated numeric string, at most 1000 ids (the excess is truncated).

ParameterDefaultNotes
ids—Example ids=1,2,3
viewer—Address, to fill viewerVote

Each element in posts:

FieldTypeMeaning
idstringOn-chain id
communitystringCommunity label, "" if none
authorstringAuthor address
handlestring | nullCurrent handle
textstringContent
createdAtnumberUnix seconds
mediaURIstring"" or content address (ipfs://…)
parentIdstring"0" for a root post, otherwise the parent post
replyCountnumberNumber of direct replies
authorIndexnumberWhich post by the author (1-based)
likeCountnumberNumber of likers, raw
dislikeCountnumberNumber of dislikers, raw
viewerVote"up" | "down" | nullRequires viewer; null when there is no vote
authorKarmanumberAuthor's postKarma + commentKarma
json
{
  "posts": [
    {
      "id": "1042",
      "community": "monad",
      "author": "0xabc...",
      "handle": "alice",
      "text": "m/monad first post",
      "createdAt": 1726000000,
      "mediaURI": "",
      "parentId": "0",
      "replyCount": 3,
      "authorIndex": 5,
      "likeCount": 14,
      "dislikeCount": 2,
      "viewerVote": "up",
      "authorKarma": 220
    }
  ]
}

/communities ​

Lists communities in alphabetical order, matching a name prefix.

ParameterDefaultNotes
q""Prefix match, case-insensitive
viewer—To fill joined
limit100Clamped 1…100
offset0

GET /communities/:name returns one community or 404 { "error": "no such community" }.

FieldTypeMeaning
namestringCommunity name (lowercase)
creatorstringCreator address
metadataURIstringMetadata URI
createdAtnumberUnix seconds
memberCountnumberNumber of active members
postCountnumberNumber of root posts in the community
joinedbooleanWhether viewer has joined

/profile/:address ​

address must be 0x + 40 hex characters, otherwise 400.

ParameterDefaultNotes
limit50Clamped 1…200, applies to both ids and commentIds
json
{
  "profile": {
    "address": "0xabc...",
    "handle": "alice",
    "posts": 5,
    "comments": 12,
    "joined": 1726000000,
    "votes": 9,
    "postKarma": 220,
    "commentKarma": 40
  },
  "ids": ["1042", "1010"],
  "commentIds": ["1050", "1049"]
}

ids are root posts (Posts), commentIds are comments (Comments). postKarma and commentKarma are weighted caches; the official number remains PostRegistry.karmaOf, read directly from the chain. joined is the time of the first post, not the time the handle was registered.

Handle and post addressing ​

EndpointReturnsNotes
/by-handle/:handle{ "address": "0x…" }Handle resolved live, can change owner
/by-handle/:handle/:n{ "id": "1042" }The n-th post of the current handle
/by-author/:address/:n{ "id": "1042" }The n-th post by address, does not drift

n must be an integer ≥ 1. Because a handle can change owner, the address is what never drifts; addressing /posts by id is the most durable.

limit defaults to 8, clamped 1…25. Addresses are searched in full; names are searched by prefix, ordered by post count descending.

json
{ "results": [{ "address": "0xabc...", "handle": "alice", "posts": 5 }] }

/notifications/:address ​

address must be correctly formatted, otherwise 400. limit defaults to 50, clamped 1…200. Your own actions are excluded.

FieldTypeMeaning
kind"reply" | "like" | "dislike"Notification type
actorstringWho did it
actorHandlestring | nullThat person's handle
postIdstring | nullThe affected post
replyIdstring | nullThe comment, when kind=reply
textstring | nullRelated content
blocknumberBlock, used for sorting and estimating time
weightnumber | nullThe vote's weight on like/dislike; null on a reply

Sorted by block descending. Like/dislike carry no timestamp in the event, so the client estimates time from block height.

/activity ​

Recent top-level posts in the communities named in communities (comma separated), after block since. limit defaults to 100, clamped 1…200. This is a plain read for the notification bell: which of these a reader wants to see is a client preference, so no preference is applied here.

FieldTypeMeaning
idstringPost id
communitystringCommunity name
authorstringAuthor address
handlestring | nullAuthor's handle
textstringPost text
blocknumberBlock it landed in
createdAtnumberUnix seconds
weightedLikesnumberWeighted likes, the same 100-point scale karma uses
bash
curl -H 'Cookie: mochi_gate=...' \
  'http://localhost:8787/activity?communities=cats,monad&since=63380000'

/replies/:id and /thread/:id ​

id must be a numeric string, otherwise 400.

  • /replies/:id returns direct children, oldest first. limit defaults to 200, clamped 1…500.
  • /thread/:id returns all descendants, flattened, so the client can rebuild the tree itself. At most 2000 ids.
json
{ "ids": ["1050", "1049", "1051"] }

Comments are never ranked; they are read chronologically.

Gate ​

EndpointUse
POST /gateForm code and next; sets the cookie then 303 to next
GET /gate/status{ enabled, open, address }, always 200
POST /gate/outRevokes the invite session, clears cookies, 303 to /gate/

Invite links use /gate?code=… on the web app and only prefill the form. A code is spent atomically when POST /gate accepts it; repeated submissions fail. The recipient then proves their wallet through /gate/challenge and /gate/session. The signed message binds the account, domain, nonce and expiry; challenges cannot be replayed or moved between pending browser sessions.

GET /gate/invites requires the additional HttpOnly mochi_invite cookie issued after account proof. A wallet address in the query or the older read cookie is insufficient. Responses are private and not cached. Codes report usedAt, usedBy and an optional indexed handle; acceptance without account creation appears as pending. Quotas do not refill on login. /gate/logout revokes the current account session and returns JSON for the app's sign-out action.

next accepts only internal paths; //evil.com is treated as /.

/push/* ​

Web Push, so a reader can be told with the app closed. The browser sends its push subscription and a copy of its notification preferences, because the push is sent from here with no browser awake to consult.

  • POST /push/subscribe — { address, subscription: { endpoint, keys }, prefs }. One row per endpoint; re-subscribing with a different address moves it.
  • POST /push/prefs — { address, prefs }, updates the copy for each of that address's endpoints.
  • POST /push/unsubscribe — { endpoint }, forgets one browser.

Sending needs VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY, and VAPID_SUBJECT on the indexer. Without them push stays off and only the bell works.

Media upload ​

POST /media accepts multipart with a file field (PNG, JPEG, WebP, or GIF, at most 5 MB) and returns { "cid": "bafy…", "uri": "ipfs://bafy…" }. Only the CID goes on-chain; the image bytes live on IPFS.

Starter drip ​

POST /drip with { "address": "0x…" } sends 0.05 MON from the indexer's drip wallet so a brand-new account can pay gas for its first transaction — usually the faucet claim. One drip per address, tracked in the local database; an address that already holds at least 0.02 MON is left alone, and a replay answers { "ok": true, "already": true }. Needs DRIP_PRIVATE_KEY on the indexer (DRIP_AMOUNT overrides the size); without it the route answers 503. Per-caller (6/minute) and global (60/hour) windows cap abuse.

Documentation for Monad testnet. It describes what is actually running.