Build with public data

Clout Caster API

These JSON routes expose only public core data. Every request is read-only, accepts cross-origin GET requests, and is limited to 60 requests per minute per client.

Shared rules

  • GET returns JSON. OPTIONS returns a 204 preflight response with no body.
  • CORS: Access-Control-Allow-Origin: *, with GET and OPTIONS allowed and Content-Type accepted.
  • GET responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.
  • Production uses one deployment-edge decision across replicas and restarts. If that protection is unavailable, requests fail closed with 503; local development uses the same 60-request fallback.
  • Request 61 returns 429 JSON with Retry-After. Invalid input returns 400, missing creator or Battle records return 404, and unavailable data returns 503.
  • Every GET error uses JSON with an error message and the same CORS and rate-limit headers.

App status

GET
/api/public/status

App identity, creator credit, network, currency, and available public routes.

Parameters: None

Example response

{
  "app": "Clout Caster",
  "creator": { "username": "lucifercaretaker", "fid": 1450388 },
  "network": "Base",
  "storeCurrency": "CLOUT"
}

V2 Battle detail

GET
/api/public/battles/{id}

Live or resolved Battle state, creator identities, reactions, and the public V2.0 component scores.

Parameters: id: positive Battle ID in the path

Example response

{
  "battle": { "id": 1, "status": "live", "formulaVersion": "v2.0" },
  "scoring": { "weights": { "cloutScore": 50, "momentum": 25, "streakConsistency": 15, "auraTier": 10 } }
}

Battle leaderboard

GET
/api/public/battle-leaderboard?limit=20

Current seasonal Battle Rank standings with record, rating, and win streak.

Parameters: limit: 1–50

Example response

{
  "formulaVersion": "v2.0",
  "entries": [{ "rank": 1, "fid": 1450388, "rating": 1240, "wins": 8 }]
}

Daily Arena

GET
/api/public/arena?limit=20

Current points-only Arena standings and recent public matchup results.

Parameters: limit: 1–50

Example response

{
  "pointsOnly": true,
  "standings": [{ "rank": 1, "fid": 1450388, "rating": 1024 }],
  "recentResults": []
}

Leaderboard

GET
/api/public/leaderboard?metric=elo&limit=20

Public creator standings. The default metric is ELO and the default limit is 20.

Parameters: metric: elo | rep | streak · limit: 1–50

Example response

{
  "metric": "elo",
  "entries": [{ "rank": 1, "fid": 1450388, "cloutElo": 1210 }]
}

Creator

GET
/api/public/creators/{fid}

Public creator identity, archetype, score tiers, streak, and latest spin summary.

Parameters: fid: positive Farcaster ID in the path

Example response

{
  "creator": {
    "fid": 1450388,
    "username": "lucifercaretaker",
    "cloutElo": 1000,
    "latestSpin": null
  }
}
Open API statusAbout the app