Run your studio’s contest pool.

Deploy and register your own EpochPrizePool, create an immutable series, then admit entries and settle past windows.

Keep admin and operator signing local#

These Base Sepolia examples use normal EOAs for admin and operator. Mainnet contests require the approved multisig configuration and a written legal decision before launch. Smart-wallet contract creation and operator ECDSA recovery have different requirements; do not assume a Base app smart wallet can deploy this pool or act as its operator. Protect the local key file and keep it out of source control. For an existing pool deployed with the admin as operator, the admin calls grantRole(OPERATOR_ROLE, operatorAddress) and verifies hasRole on-chain before using a new dedicated operator. For a new pool, pass the operator at prepare so no later role grant is needed.

1. Create the local setup#

export PLAYMOS_API_URL=https://api.sandbox.playmos.io/v1
npx --yes --package=@playmos/sdk@0.3.38 playmos-studio init
# Fund the admin EOA with Base Sepolia ETH.
# Set PLAYMOS_SECRET securely in this process environment.
npx --yes --package=@playmos/sdk@0.3.38 playmos-studio pool create \
  --series your-series --entry 250000 --epoch 3600
npx --yes --package=@playmos/sdk@0.3.38 playmos-studio pool own

The CLI is shipped inside @playmos/sdk; there is no separate playmos-studio npm package. init writes local admin/operator material. pool create prepares, signs locally, deploys and records the pool/transaction. pool own completes or resumes the ownership handshake. Inspect command output before proceeding.

2. Confirm ownership#

The prepare API returns unsigned transaction data and deployment bytecode. Preparing is not broadcasting. After the deployed address has a successful receipt, registration first returns a proof message. Inspect its studio, pool, wallet and chain, sign it locally with the admin, then register the signature. Continue only when ownership === 'confirmed'.

import { Playmos } from '@playmos/sdk';
 
export async function registerYourPool(
  ops: Playmos, prepared: import('@playmos/sdk').EpochPreparedPool,
  poolAddress: `0x${string}`,
  signMessage: (message: string) => Promise<`0x${string}`>,
) {
  // Preserve the same dedicated operator and sinks used for deployment.
  const input = { studioWallet: prepared.admin, admin: prepared.admin,
    operator: prepared.operator, feeSink: prepared.feeSink, poolAddress };
  const pending = await ops.epochs.registerPool(input);
  if (pending.ownership === 'confirmed') return pending;
  if (!pending.proof) throw new Error('No ownership challenge returned.');
  // Inspect the studio, pool, wallet and chain named in this message.
  const signature = await signMessage(pending.proof.message);
  const owned = await ops.epochs.registerPool({
    ...input, walletProof: { signature },
  });
  if (owned.ownership !== 'confirmed') throw new Error('Ownership is not confirmed.');
  return owned;
}

3. Create the first series#

npx --yes --package=@playmos/sdk@0.3.38 playmos-studio series create \
  --name your-series --entry 250000 --epoch 3600 --dry-run
# Review chain, roles and split; remove --dry-run to sign and send.

The CLI proves the RPC chain, checks admin/operator roles and avoids resending a recorded series transaction. Programmatically, call epochs.prepareSeries, inspect and sign unsignedTx, then call epochs.getSeries until created === true. A prepare response alone does not open a series.

Use the actual series terms#

All four buckets sum to 10000. Seed can be zero and the first three shares can change at series creation; Playmos’s 100 bps remains fixed. Entry is integer micro-USDC: 250000 means 0.25 USDC. A new clock, entry or split requires a new series. New immutable sink addresses require a new pool. Read addresses and fee terms from the prepare/chain response rather than copying them from another game.

4. Enter the current window#

Players call epochs.enter with their wallet provider, pool, series and a persisted attempt identity. The returned epochId comes from the mined entry event when confirmed. Preserve it across admission and scoring; the clock may advance before the transaction mines. Re-entry is supported and identityEntryCount records the paid count.

import { Playmos } from '@playmos/sdk';
 
export async function enterYourEpoch(
  publishableKey: string, provider: import('@playmos/sdk').Eip1193Provider,
  pool: `0x${string}`, series: string, attemptIdentity: string,
) {
  const player = new Playmos({
    apiKey: publishableKey,
    wallet: { provider },
    contracts: { epochPrizePool: pool },
    rpcUrl: 'https://sepolia.base.org',
  });
  const entry = await player.epochs.enter({ series, identity: attemptIdentity });
  // Persist the returned epochId, identity and txHash for server admission.
  // Confirmed entries use the mined event's epochId, not a guessed clock window.
  return entry;
}

A client-supplied transaction hash or browser confirmed flag does not authorize a paid round. The trusted backend must match a successful receipt from the expected chain, pool and series, with the exact attempt identity and the authenticated player's event payer. Refuse bytes32-shaped proof identities; the SDK's low-level compatibility hasher passes those through. Identity strings can be predictable and are received/echoed by the service, so they are not authentication.

Your backend must atomically consume each paid event once, using chain + pool + transaction hash + logIndex; a smart-wallet bundle can contain several entries. Persist the paid epoch for scoring and settlement. Define sale, admission and score deadlines explicitly; the contract's epoch end is not a studio grace-period policy. The Hub uses its paid-seat horizon for score/settlement eligibility.

The published SDK 0.3.38 includes RPC-backed epoch views, backend verifyEntry, exported event/error ABIs and read-only epochs.resumeEntry. Bind verification to the authenticated payer and atomically consume the returned event replay key on your backend. Retain the existing payment's hash/identity when a read fails; do not charge again to retry admission. Both the original seven-field and studio-share eight-field Entered signatures are supported.

Keep purchases and attempts within the competition#

For paid replay, block a new entry purchase during an active run and reuse an unused paid attempt before selling another. Allow another paid attempt after completion while the competition is open. The server checks the exact competition ID and closing time at quote creation, immediately before signing and when admitting a new run. Unused entries expire at closing; they remain in payment history and never carry admission into the next competition. Reload resumes the server-owned active attempt. A previously started run follows your published bounded finish and scoring policy, so an ongoing turn does not silently hold another competition open.

Cancellation before submission creates no paid admission. Pending or uncertain payments remain recoverable with their original key; define a late-confirmation and refund policy before accepting entry fees. See the in-game checkout workflow.

5. Settle a completed window#

Your trusted backend validates scores and selects winners. The operator signs settlementTypedData. In SDK 0.3.38, epochs.executeSettlement sends the signed result directly through the client’s configured wallet; that wallet pays gas. The separate server HTTP route POST /v1/epochs/:epochId/settle/signed accepts a studio secret and relays the operator signature through the service when that capability is configured. Do not treat these as the same transport. For an own pool, do not use the service-signer epochs.settle path as a substitute for your operator. The current window is still accepting entries; settle a past one.

import { Playmos } from '@playmos/sdk';
 
import { settlementTypedData } from '@playmos/sdk';
 
export function operatorSettlement(
  pool: `0x${string}`, series: string, pastEpochId: string,
  winners: `0x${string}`[], amountsMicro: string[],
) {
  return settlementTypedData({
    pool, chainId: 84532, series, epochId: pastEpochId,
    winners, amounts: amountsMicro, // Integer micro-USDC; never USD decimals.
  });
}
 
export async function executeSignedSettlement(
  client: Playmos, pool: `0x${string}`, series: string, pastEpochId: string,
  winners: `0x${string}`[], amountsMicro: string[], signature: `0x${string}`,
) {
  // Your operator EOA signs operatorSettlement(...) locally.
  // client needs a wallet provider: this SDK method sends from that wallet.
  // The separate HTTP /settle/signed service relay is not called here.
  const receipt = await client.epochs.executeSettlement({
    epochPrizePool: pool, series, epochId: pastEpochId,
    winners, amounts: amountsMicro, signature,
  });
  // A broadcast is not terminal settlement. Read epochs.get for this window.
  return receipt;
}

A transaction hash or pending response is not terminal success. Read epochs.get, its terminal state and read provenance. Empty-window roll and refund are different outcomes from a winner payment.

6. Withdraw or refund#

epochs.prize reads the contest prize pool. Read the pool's withdrawable(wallet) for a wallet's credited balance and use epochs.withdraw for its wallet-signed pull. A timeout does not activate refunds automatically: the protocol's permissionless refundEpoch must first make the oldest eligible paid window Refunded. Then claimableRefund / claimRefund credit the retained pool share; the player withdraws afterward. Fee, studio revenue and seed already carried onward are excluded. This protocol escape hatch is separate from discretionary refunds. Missing amountMicro is unknown, not zero. See payout and withdrawal states.

Current pools move seed into carry at entry time. It can attach to a later paid epoch before the source settles; settlement pays pool + incomingSeed. outgoingSeed is a compatibility slot that stays zero.

The CLI supports init, pool create, pool own and series create. There is no operator run command; the operator loop remains your backend/script.