Skip to content
shitOS
Terminal

SDK

Five functions. One toilet.

Sign flushes, ask the oracle, stream the network and decode receipts. Everything here hits real endpoints running in simulation mode.

TypeScripted25519 · base58Server-Sent EventsNot on npm yet, lives in /sdk

Quickstart

Flush in four lines

import { createDevice, signFlush, sendFlush, subscribe } from '@/sdk';

// 1. A device identity (in production this key lives in a secure element)
const device = createDevice('PRO');

// 2. Sign a flush over its canonical JSON
const telemetry = signFlush(device, {
  counter: 1,
  volumeL: 4.8,
  durationMs: 3120,
  profile: 'dual-low',
});

// 3. Ask the oracle
const verdict = await sendFlush(telemetry, 'https://shitos.vercel.app');
console.log(verdict.status); // "VERIFIED"

// 4. Watch the network
const stop = subscribe((e) => console.log(e.type, e.eventId));
  1. 1Get the SDKIt is in the ShitOS repo at /sdk. Copy the folder or import it with the @/sdk path alias. An npm package comes later.
  2. 2Make a devicecreateDevice() makes an ed25519 key. In simulation mode the oracle self-registers it from the pub field.
  3. 3Sign and sendsignFlush() builds the canonical payload, and sendFlush() returns the verdict.
  4. 4Listensubscribe() streams every detection, verdict, anchor and Degen Engine signal.

Playground

Try to fool the oracle

Your browser makes a real ed25519 key, signs real payloads and posts them to the live oracle. Then try the dirty tricks.

Device

Generated on first request

    Request · POST /api/telemetry
    // press a button
    Response
    // verdict appears here

    Reference

    API

    POST/api/telemetrySubmit a signed flush. 200 verified, 422 rejected with a reason, 400 malformed.
    GET/api/telemetryThe last 25 oracle verdicts from the audit log.
    GET/api/events/streamServer-Sent Events: hello, then protocol events. Simulated in Phase 1.
    GET/api/marketDexScreener-backed token data. {"launched":false} until the token exists.
    POST/api/waitlistJoin the hardware waitlist with { email, device }.
    GET/receipt/:id/opengraph-imagePNG share card for a receipt.

    SDK functions

    createDevice(kind?)
    New device identity: deviceId, ed25519 secret key, base58 public key.
    signFlush(device, event)
    Builds the v1 payload and signs its canonical JSON (keys sorted, sig excluded).
    sendFlush(telemetry, baseUrl?)
    POSTs to /api/telemetry and resolves with the verdict, including rejections.
    subscribe(onEvent, baseUrl?)
    Opens the SSE stream and calls you for every protocol event. Returns unsubscribe.
    decodeReceipt(id)
    Turns a /receipt/:id into a receipt object. Simulated receipts can never decode as verified.

    Rejection reasons

    UNKNOWN_DEVICE
    deviceId is not registered (or was revoked).
    BAD_SIG
    The signature does not match the payload. Someone edited it after signing.
    REPLAY
    counter is not greater than the last accepted one.
    CLOCK_SKEW
    ts is more than 120 s from server time.
    COOLDOWN
    Less than 30 s since this device’s last accepted flush. Tanks need to refill.
    RATE_LIMIT
    More than 10 flushes from this device in an hour. Please see a doctor.

    Limits

    10 flushes per device per hour, 30 s cooldown, ±120 s clock window. Identical payloads are idempotent.

    Webhooks

    Coming in Phase 2: signed POSTs for verified flushes and anchored batches.

    Mainnet

    Every response currently carries mode SIMULATION and solanaTransaction null. Nothing touches a real chain yet.