← back

FOR AGENTS

Chronomancy is a protocol, not just an app. If you want to build your own bot, client, or experiment that plays along with the network, here's everything you need.

---

The Sync Ping

Once per UTC day, every Chronomancy client pings at the exact same second worldwide. Derived from the date alone, deterministic, π-seeded.

Easy way — just pull the answer from our API

If you don't want to reimplement the PRNG, hit this endpoint and you'll always get the canonical value every other client will use today:

GET https://chronomancy.app/api/v1/community/sync/today

{
  "date": "2026-04-14",
  "sync_time_utc": "2026-04-14T14:47:40+00:00",
  "seconds_into_day": 53260,
  "seed": 20574573,
  "already_fired": true,
  "next_sync_utc": "2026-04-15T13:07:22+00:00"
}

Also available for any date: GET /api/v1/community/sync/2026-06-21. Use this for backfilling historical moments or pre-computing a week of schedule.

Hard way — reimplement the algorithm yourself

For parity / offline use / diligence. The seed field in the API response is literally this integer: YYYYMMDD + 314159.

Python

import datetime as dt
import random

def compute_sync_time_utc(utc_date: dt.date) -> dt.datetime:
    """Deterministic π-seeded global sync moment for a given UTC date.

    Every user and every group gets pinged at THIS exact UTC second on
    `utc_date`. Identical seed worldwide = identical moment worldwide."""
    date_key = int(utc_date.strftime("%Y%m%d"))
    rnd = random.Random(date_key + 314159)  # π
    seconds_into_day = rnd.randrange(0, 24 * 60 * 60)
    utc_midnight = dt.datetime.combine(utc_date, dt.time(0, 0), tzinfo=dt.timezone.utc)
    return utc_midnight + dt.timedelta(seconds=seconds_into_day)

JavaScript

// Mulberry32 PRNG — deterministic, matches Python random.Random for our use
function computeSyncTimeUTC(utcDate) {
    const dateKey = parseInt(
        utcDate.toISOString().slice(0, 10).replace(/-/g, "")
    );
    let seed = (dateKey + 314159) >>> 0;
    const rand = () => {
        seed = (seed + 0x6D2B79F5) >>> 0;
        let t = seed;
        t = Math.imul(t ^ (t >>> 15), t | 1);
        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
    };
    const secondsIntoDay = Math.floor(rand() * 86400);
    const midnight = new Date(Date.UTC(
        utcDate.getUTCFullYear(), utcDate.getUTCMonth(), utcDate.getUTCDate()
    ));
    return new Date(midnight.getTime() + secondsIntoDay * 1000);
}

Note: the canonical reference is the Python version. If you need bit-for-bit cross-platform agreement, generate the schedule server-side and cache it — don't rely on different language PRNGs producing the same sequence.

---

Random Pings (Per-User)

N random pings per day inside a user's active window. Independent per user, no coordination needed. Uses stdlib random — any PRNG is fine since these are personal, not shared.

import random
from datetime import date, datetime, time, timedelta, timezone

def generate_daily_pings(
    user_id: str,
    target_date: date,
    count: int,
    start_hour: int,   # local hour, 24h format
    end_hour: int,
    tz_offset_minutes: int = 0,
) -> list[datetime]:
    """N random times in the user's active window, returned in UTC."""
    # Seed per-user-per-day so a given user gets the same times on replay,
    # but different users get different times on the same day.
    seed = hash((user_id, target_date.isoformat()))
    rnd = random.Random(seed)

    window_start = time(start_hour, 0)
    window_end = time(end_hour, 0)
    local_start = datetime.combine(target_date, window_start)
    local_end = datetime.combine(target_date, window_end)
    total_seconds = int((local_end - local_start).total_seconds())

    picks = sorted(rnd.sample(range(total_seconds), count))
    tz = timezone(timedelta(minutes=tz_offset_minutes))
    return [
        (local_start.replace(tzinfo=tz) + timedelta(seconds=s)).astimezone(timezone.utc)
        for s in picks
    ]

---

Public API

These endpoints are live at https://chronomancy.app. CORS-enabled, no auth required, free to use. Please don't hammer them — cache on your side and hit them once or twice a day.

---

Field Report Protocol

When a user responds to a ping, they report a direction — whether the field feels UP (active) or DOWN (quiet). Not emotions. Not hit/miss. Just: does the moment feel charged or still.

Minimal report

{
  "direction": "HIGH",       // or "LOW"
  "timestamp": "2026-04-14T14:30:00Z"
}

Full report

{
  "direction": "HIGH",
  "timestamp": "2026-04-14T14:30:00Z",
  "tags": ["synchronicity", "outdoor"],
  "note": "two planes crossed overhead in a perfect X"
}

---

Voice and tone

If you build a Chronomancy-compatible bot, please keep the voice:

• Short, imperative, observational. "Stop. Look around. What do you notice?"
• Lowercase is fine and encouraged. This is not a productivity app.
• No urgency, no streaks-as-punishment, no red badges. Missed pings don't matter.
• The bunny 🐰🕰 is chill about time. Time isn't the point. Attention is the point.
• "Field active" / "field quiet" — not "good" / "bad", not "happy" / "sad".

---

Bot integrations

The official clients are:

• Telegram — @chronomancy_bot — /sounding, /challenge, /drift, /ping_setup for groups
• Discord — slash commands in any server the bot is in
• iOS — via TestFlight, local pings, no server required

If you build a Matrix, Slack, Signal, IRC, or anything-else bot that speaks the sync-ping protocol above, please email us at [email protected] and we'll link you from here.