Complete reference for the rpsa_sdk package, organized around the decisions you make while building and validating a strategy.
Subclass Strategy, implement next_move(), and return one legal move every round.
Opt in with uses_context to read wallets, auctions, perks, and live match state.
Understand AST scans, smoke tests, context checks, and the most common blockers.
The required shape of every uploaded strategy file.
Import Strategy from rpsa_sdk. Your class must subclass it and implement next_move(context: Context) -> str.
Live match data and economy actions available when uses_context is enabled.
When uses_context = True, the runtime injects a Context object before each call to next_move(). Read methods reflect current match state. Mutating methods run inside a DB savepoint and return a result dict; they never raise.
| Name | Description |
|---|---|
| context.credits() | Your current wallet balance as Decimal. Refreshed from the database each call. |
| context.opponent_wallet | Opponent wallet balance as a turn-start snapshot. |
| context.round | Current round number, 1-indexed. Round 0 is the pre-match bid window. |
| context.consecutive_wins() | Number of consecutive wins at the start of this turn. Returns 0 on a loss streak. |
| context.market_state() | Full market snapshot with total_rounds, posted_price_items, active_auctions, active_perks, and purchases. |
context.bid(stock_id: str, amount: Decimal)
Returns { ok: True, bid_id: str } on success or { ok: False, error: str } on failure. Common errors include WINDOW_CLOSED, INSUFFICIENT_FUNDS, and INVALID_BID.
context.activate(perk_code: str, t_start: int, **params)
Returns activation metadata on success or an error result on failure. t_start must be at least context.round + 1. WindowWager and WindowHedge require a Decimal stake param.
notify(own_move, opp_move) to track it yourself between rounds.The sandbox validates imports before a strategy can run.
The sandbox enforces a strict allowlist at process startup. Importing anything outside these lists fails validation with an AST scan error.
abc, builtins, collections, copy,
dataclasses, decimal, enum, functools,
heapq, itertools, json, math,
operator, pathlib, pickle, queue,
random, re, statistics, string,
struct, time, typing, uuidnumpy, scipy, sklearn,
torch, torchvision,
tensorflow, keras,
xgboost, lightgbm,
pandas (read-only ops)os, sys, subprocess, socket, ctypes,
importlib, _socket, _subprocess, _ctypes,
# plus calls to eval, exec, compile, __import__
# and attributes: __class__, __subclasses__,
# __globals__, __builtins__
# and open(..., "w") or open(..., "a")Private C extension modules with names starting with _ are allowed unless explicitly blocked above.
Every upload must pass three checks before season enrollment.
Every upload is queued for validation. All stages must pass before the strategy can be enrolled in a season. Validation typically completes in under 2 minutes.
random is allowed, but os.urandom is not. Calls like time.sleep() can time out, large state can exceed memory limits, and re-uploading resets validation to pending.Choose the smallest tier that fits your strategy.
No ML libraries. Uses only the standard library allowlist and rpsa_sdk. Fastest execution with the lowest sandbox overhead.
from rpsa_sdk import Strategy
class RockAlways(Strategy):
def next_move(self, context) -> str:
return "rock"May import NumPy, PyTorch, scikit-learn, and other ML packages from the allowlist. Detected by the AST scanner.
import numpy as np
from rpsa_sdk import Strategy
class RandomBot(Strategy):
def next_move(self, context) -> str:
return np.random.choice(["rock", "paper", "scissors"])A zip archive containing strategy.py and a trained model file. Use this when your strategy loads a model artifact.
import pickle
from rpsa_sdk import Strategy
class ModelBot(Strategy):
def __init__(self):
with open(self.model_path, "rb") as f:
self.model = pickle.load(f)
def next_move(self, context) -> str:
return self.model.predict()Ship a trained model alongside strategy.py.
Tier C uploads must be a .zip archive with this exact structure:
archive.zip
|-- strategy.py # required: must contain your Strategy subclass
|-- model.<ext> # required: pkl, pt, h5, joblib, onnx, ...
|-- requirements.txt # optional: extra allowed packagesBefore the first call to next_move(), the runtime sets self.model_path to an absolute path for your extracted model file.
def __init__(self):
import pickle
with open(self.model_path, "rb") as f:
self.clf = pickle.load(f)Useful building blocks for stronger entries.
These patterns separate a competitive entry from AlwaysRock. Combine them in a single strategy for better expected value.
Track opponent move history through notify(), predict the next move from recent frequency, and counter it.
from collections import Counter
from rpsa_sdk import Strategy
class FrequencyCounter(Strategy):
uses_context = True
def __init__(self):
self._opp_history = []
self._beats = {"rock": "paper", "paper": "scissors", "scissors": "rock"}
def next_move(self, context) -> str:
if len(self._opp_history) < 10:
return "rock"
counts = Counter(self._opp_history[-20:])
predicted = counts.most_common(1)[0][0]
return self._beats[predicted]
def notify(self, own_move: str, opp_move: str) -> None:
self._opp_history.append(opp_move)Read both wallets from context and shift aggression based on the capital gap.
from rpsa_sdk import Strategy
class WalletAdaptive(Strategy):
uses_context = True
def next_move(self, context) -> str:
my_wallet = context.credits()
opp_wallet = context.opponent_wallet
# Behind by more than 50 cr: switch to aggressive rock spam
if opp_wallet - my_wallet > 50:
return "rock"
# Comfortably ahead: play safe scissors to avoid paper traps
if my_wallet - opp_wallet > 30:
return "scissors"
return "paper"Read market_state(), bid during open auction windows, and activate owned perks at strategic rounds.
from decimal import Decimal
from rpsa_sdk import Strategy
class AuctionAware(Strategy):
uses_context = True
_bid_placed = False
def next_move(self, context) -> str:
market = context.market_state()
# Bid on LossCap in the pre-match Vickrey if we have not yet
if not self._bid_placed and context.round <= 1:
for auction in market["active_auctions"]:
if "LossCap" in auction.get("perk_id", ""):
result = context.bid(auction["stock_id"], Decimal("15"))
if result["ok"]:
self._bid_placed = True
# Activate LossCap once we own it; schedule it for the next round
owned = {p["perk_code"] for p in market.get("purchases", [])}
activated = {p["perk_code"] for p in market.get("active_perks", [])}
if "LossCap" in owned and "LossCap" not in activated and context.round == 5:
context.activate("LossCap", t_start=context.round + 1)
return "rock"market_state()["active_auctions"] every round. A stock with window_phase == "open" accepts bids; closed means the auction has cleared.Jump between the SDK, the rules, and the participation guide when you are tuning a strategy for ranked play.