Running a collector

Volunteer a machine that fetches for the shared record, and what it earns you.

A collector is a small program that fetches Clash Royale data for Elixir MCP with YOUR API key and posts the results back to us over HTTPS. It has no AWS credentials, no cloud access, no queues: it is a pure API client holding exactly two secrets: your Clash Royale key and the bearer token Elixir MCP issues you.

The fleet shares one rate budget; extra collectors add resilience, not quota.

Who may run one

Anyone with an Elixir account. Raising your hand is the whole enrollment: your collector is approved the moment you do, with no waiting list and no trial run on someone else's machine first. What keeps the record honest is not who you are but what every collector's results must pass, on every submit:

• Shape. Every result must have the shape of the Clash Royale API's answer for that kind of read, or it is refused.
• Identity. A player, clan or river race result must be about the tag the job asked for, and a battle log must have that player in every battle.
• Content-derived battle ids. A battle is identified by its time, its players and its kind, so every collector's copy of one battle lands on the same record, and a made-up battle has to agree with every other log of the same players.
• Provenance. The server stamps which collector sent each result from its token; a collector cannot speak as another.
• Your own leases only, and few of them. A collector can hand back only the work it was given, holds at most two unfinished jobs at a time, and has an hourly request budget.
• One new collector at a time. Until a collector of yours has delivered a result that passes, raising another is refused; one that was drained without ever delivering still counts until the maintainer revokes it. Collectors that have delivered never count, so you can run as many as you like, proving each in turn.
• Drain and revoke. Ten jobs in a row left to expire drain a collector automatically, and the maintainer can revoke any collector's token at any time, with immediate effect. When this page or the door says "quarantine", it means these two and nothing else: results that pass the checks above count at once, with no holding pen.

The maintainer is told when a collector is enrolled and sees every one.

What you need

• A machine that is usually on, with a static public IP (only because Supercell binds CR API keys to an IP; we never ask you for it, and it is never published).
• A Clash Royale API key from https://developer.clashroyale.com, allowlisted to that IP.

Setup

1. Raise your hand at Settings › Collectors › Run a collector on https://elixir.poapkings.com, pick a machine name and the Clash Royale card your collector will wear. The card is its public name, so pick a favourite; a card belongs to one collector, and one that is already taken is shown dimmed. You can change it later from the collector's own page. This is the only way a collector comes to exist: every one is bound to the account that raised it, and you can raise as many machines as you run, each gets its own name, card and token.

   What is public and what is not. The card name, the collector's status, and its fetch counts are public. Your machine name is private: it is visible to you and the maintainer, and to nobody else, which is why you can safely call it whatever your box is actually called. Your primary claimed player name and tag are public in the fleet listing (/api/public/status, which needs no sign-in, and the Collectors page in Settings): collectors are credited to the player who runs them, so running one attaches your CR identity to it. Your email address and IP are never published.

2. Raising your hand approves it: you land on the collector's own page, which offers your collector token as a one-time reveal: copy it, because it disappears from the server the moment you claim it. The offer is good for 72 hours: after that the staged token is discarded unclaimed. If it lapses, or you lose the token later, Replace the token on the same page stages a fresh one; it replaces the token your machine holds, which stops working. Claiming is a deliberate click, so nothing you paste into a chat window or a link preview can spend it for you. Put it in a .env (mode 0600) next to the binary alongside your own CR key:

   CR_API_TOKEN=your-clash-royale-key
   ELIXIR_API_TOKEN=emcg_...
   

3. Run the installer for your platform from the directory holding your .env. The collector's README has the commands for macOS, Windows and Linux: each downloads the installer from the current release with its signed SHA256SUMS, checks the signature and the installer's hash, and only then runs it. The installer fetches the right binary, verifies its SHA-256, and registers a service that keeps it running (launchd on macOS, systemd on Linux, a Scheduled Task on Windows). A host without a supervisor, such as a Synology NAS, runs it under scripts/run-forever.sh.

That is the whole setup. The server tells the running collector everything else at launch, pacing, backoff, what to fetch (it even sends the exact URL paths), so recording-schedule changes never require you to update anything. When a new binary IS required, the collector updates itself: the server names the exact version and SHA-256 it may install. There is no pin and no opt-out; the fleet shares one rate budget and one contract, so a stale client is everyone's problem.

The minimum collector version is 3.0.6. Older releases are refused work, but can still read the update instructions and update themselves.

How updates reach you

Your collector updates itself. Every candidate build waits until this server names it as the fleet's current version, so what you run is always a version somebody chose deliberately rather than the newest thing that compiled.

Naming is not enough on its own. Every release is signed, and your collector installs a named release only after it checks the signature over the release's SHA256SUMS against the release key built into it, and the download against the hash this server named. So neither this server alone nor GitHub alone can put code on your machine. The release key:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIFvN1mZGTcFXSGnIXf8h33cxAhvrHPYn80BO5FkELh28 elixir-mcp-collector-release

Its fingerprint is SHA256:mktajl7kjMESYLyiY34rRu9hLTL6+EJS3I6aa/sGqeU, the one your collector logs when it verifies an update. This page is a second place to check it: the collector repository's SECURITY.md publishes the same line, with how to verify a release by hand. If the two ever disagree, do not install, and tell the maintainer.

The signed badge. Your collector tells this server, on every call, the SHA-256 of the binary it is running and the fingerprint of the release key it trusts. The fleet page on https://elixir.poapkings.com (/console/status/collectors) then marks each collector signed when that binary is exactly a release this server named for its version, dev build for a local build, unverified when the collector does not report its hash yet (an older release), and mismatch when it reports a hash that is not the named one: a local build under a release's version, or something wrong with the machine. The badge is public; the hash itself is seen only by you and the maintainer. It is what your collector says about itself, shown so a fleet that runs exactly the releases it was given is visible at a glance, not a check anything depends on. The same page draws the release key's fingerprint as the picture ssh-keygen -lv prints for it, so you can compare it with your own by eye.

What your collector can and cannot do

It leases fetch jobs, calls the CR API with your key, and posts the results. It never chooses targets, never sees user data, and holds nothing that touches our infrastructure. The token only works against three API routes, and revoking it is instant. While one of your collectors is active, your account holds the Family role (Roles); that is the reward, and the only one. There are no points, call credits or bonus slots. A collector on probation, draining or revoked earns no role.

The door, precisely

Three routes, all Authorization: Bearer emcg_…:

Config hands out pacing (1,500 ms between fetches), the 403 breaker (5 in a row, 300 s cooldown), the payload ceiling (5,000,000 bytes compressed and base64-encoded), the next check-in interval, your channel, your status, the address your requests arrive from (observed_ip, the one to allowlist on your CR key), the one Clash Royale path collector doctor may read to prove your key works from there, and the one release version and SHA-256 you may run. A pending token, the state of a hand raised before enrollment opened, can read config and nothing else, so doctor can tell you "installed, not yet promoted" instead of an error; a revoked token is told so (403 revoked) on config alone. A lease expires after 90 seconds unsubmitted; ten expired leases in a row drain the collector (it moves to draining, the maintainer is told, and lease answers 409 quarantined). So a submit that fails for a passing reason is retried on the same lease, inside those 90 seconds, on the budget config's submit_retry names: up to three attempts of at most 20 seconds, backing off from 500 ms, on a network failure, a 5xx, or a status in retry_statuses (429 today, the answer when the site's shared throttle is momentarily full). A 429 whose Retry-After is longer than the lease can wait, your hourly budget, is not retried. A collector that simply stops checking in is silent: after an hour without a check-in, elixir_collectors and the fleet page say silent (with silent_since and last_seen) beside the enrolment state under lifecycle, and the maintainer is told once per silence. A stop on purpose is draining, which is never silent; ask to be drained rather than leaving a machine quiet under active.

A lease may carry a filter. On a battlelog job it is filter.battles_after, the newest battle the service already holds for that player, spelled the way the API spells battleTime (20260911T123456.000Z). A collector that honours it drops every entry at or before that value before submitting, the body stays the API's own array, just shorter, and reports observed (entries before the filter) and filtered (entries dropped) beside fetched_at. Duplicates never cross the wire, and filtered: 0 on a full log tells the service the log rolled past what it had. Ignoring the filter is still correct, only wasteful. Live reads never carry one: the agent waiting on that fetch gets the whole log. Submit answers only after the payload is admitted and committed; a rejected payload is still a receipt, so never fake an ok. Lifecycle: probation → active → draining → revoked. A raised hand starts on probation, which already leases and submits; its first result that passes the checks makes it active. Ten expired leases drain one automatically; the maintainer can also drain one, put a drained one back on probation to try again, or revoke it.

Fair-use expectations

Your collector shares ONE global rate budget with the fleet (that is Supercell ToS posture, not a suggestion). The pacing the server hands out is load-bearing. A client that goes quiet holding leases is drained automatically and the maintainer told, and one that ignores the pacing runs into the door's hourly limits.

Collector email

Your weekly collector email includes the security status shown in the dashboard. Elixir also sends one notice for each collector it sees upgrade to a higher released version, with the old and new versions and available release notes. Both use your Collector activity email preference. See email from Elixir.

This material is unofficial and is not endorsed by Supercell. For more information see Supercell's Fan Content Policy: www.supercell.com/fan-content-policy.