@hellomoon/camelot-sdk

TypeScript SDK for the Mooncast API — auth, read endpoints, transaction building, and a live WebSocket feed. Flip and settle transactions are automatically wrapped with the required Switchboard on-demand randomness instructions (commit / reveal), so you get ready-to-sign transactions.

Everything is exported under the coinflip namespace.

Installation

npm install @hellomoon/camelot-sdk @solana/web3.js @switchboard-xyz/on-demand @coral-xyz/anchor

Quick start

import { coinflip } from "@hellomoon/camelot-sdk";
import { Connection } from "@solana/web3.js";

const client = new coinflip.MooncastSdk({
  apiUrl: "https://api.mooncast.example",
  connection: new Connection("https://api.mainnet-beta.solana.com"),
  cluster: "mainnet",
  jwt, // optional — pass an existing token, or log in (below)
});

The constructor takes:

| Option | Required | Description | | ------------------ | -------- | --------------------------------------------------------------------------------- | | apiUrl | yes | Base URL of the Mooncast API. | | jwt | no | An existing JWT. Your frontend can pass one it already holds. | | connection | for tx | A @solana/web3.js Connection. Required for transaction methods (Switchboard). | | cluster | no | "mainnet" (default) or "devnet" — selects the Switchboard queue. | | computeUnitPrice | no | Priority fee in micro-lamports (default 75_000). |

Authentication

Auth is a wallet-signature challenge that returns a JWT. Sign the returned message with the user's wallet, then log in. On success the token is stored on the client automatically.

const { message } = await client.auth.challenge(wallet.publicKey.toBase58());

const signature = await wallet.signMessage(new TextEncoder().encode(message));

const token = await client.auth.login({
  wallet: wallet.publicKey.toBase58(),
  message,
  signature: bs58.encode(signature),
});

If the frontend already has a token, skip this and pass jwt to the constructor (or client.setJwt(token)).

Reading data

const config = await client.read.config();
const user = await client.read.user(wallet);
const tokens = await client.read.tokens();
const player = await client.read.player(wallet);
const rounds = await client.read.rounds(wallet, { limit: 20, offset: 0 });
const round = await client.read.round(123);

Building transactions

Transaction methods return ready-to-sign VersionedTransactions. Have the connected wallet sign and send them.

Flip a coin

Randomness is created and committed for you. Because Switchboard requires the randomness account to be created first, then committed in the same transaction as your program instruction, coinflip() returns two transactions to send in order:

const { randomnessAccount, createTransaction, commitTransaction } = await client.tx.coinflip({
  amount: 1_000_000,
  choice: coinflip.CoinflipSide.Heads,
});

// 1) create the randomness account
await wallet.sendTransaction(createTransaction, connection);
// 2) commit + flip
await wallet.sendTransaction(commitTransaction, connection);

// keep `randomnessAccount` — you need it to settle

Settle a flip

Prepends the Switchboard reveal instruction:

const settleTx = await client.tx.settle({ randomnessAccount });
await wallet.sendTransaction(settleTx, connection);

Other transactions

await client.tx.initUser();
await client.tx.deposit(5_000_000);
await client.tx.swap(2_000_000);

All of these require the client to be authenticated (a JWT) — the wallet the transaction is built for comes from the token, not the request body.

Live WebSocket feed

Open a socket (JWT-authenticated) and subscribe to rooms. On connect you automatically receive your own wallet's events and the global feed. Events are pushed live — including your own flip outcomes as they settle.

const socket = client.ws().connect();

socket.on(coinflip.events.GAME_ROUND, (round) => {
  console.log("flip settled:", round.is_win, round.outcome);
});

socket.on(coinflip.events.PLAYER_STATE, (player) => {
  console.log("player state changed:", player);
});

// subscribe to any public room
socket.subscribe("global");

// listen to everything
socket.on(coinflip.events.ALL, (data, message) => {
  console.log(message.type, data);
});

socket.close();

Event types (coinflip.events): CONFIG, TOKEN_WHITELIST, USER, PLAYER_STATE, GAME_ROUND, TRANSACTION, and ALL ("*").

Scaling

Each API instance consumes every event from its own exclusive queue and forwards to its locally connected clients, so you can run the API behind a load balancer and horizontally scale the WebSocket layer with no shared state.

Environments

• Browser: uses the global fetch and WebSocket. No extra setup.
• Node.js (18+): fetch is built in. For WebSockets, set globalThis.WebSocket (e.g. from the ws package) before connecting.

API surface

import { coinflip } from "@hellomoon/camelot-sdk";

coinflip.MooncastSdk; // main entry point
coinflip.CoinflipSide; // Tails = 0, Heads = 1
coinflip.events; // event-type constants
coinflip.WsClient; // websocket client
coinflip.CoinflipApiError;
// plus response types: Config, User, TokenWhitelist, PlayerState, GameRound, Transaction

License

MIT