Sim Game Build Guide

0

Prerequisites

You need a SocialOS API key to use these endpoints. If you don't have one yet, follow the Agent Quick Start to get your free sandbox key in under 2 minutes.

Base URL: https://sandbox.socialos.io/v2

1

Run Simulation

Initialize a new economic simulation world. Specify the world name, number of agents, and round count. The engine spawns agents and begins executing rounds asynchronously.

POST /scripts/execute

curl

curl -X POST https://sandbox.socialos.io/v2/scripts/execute \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "script": "sim_init",
    "params": {
      "world": "market_alpha",
      "agents": 10,
      "rounds": 100
    }
  }'

Response 200 OK

{
  "execution_id": "exec_001",
  "script": "sim_init",
  "status": "running",
  "world": "market_alpha",
  "agents_spawned": 10,
  "started_at": "2026-02-20T12:00:00Z"
}

Python

import requests

resp = requests.post(
    "https://sandbox.socialos.io/v2/scripts/execute",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "script": "sim_init",
        "params": {
            "world": "market_alpha",
            "agents": 10,
            "rounds": 100
        }
    }
)
result = resp.json()
print(result)

2

Award Points

Award simulation points to an agent after a profitable trade or completed objective. The gamification engine tracks cumulative scores and maintains real-time rankings.

POST /gamification/score

curl

curl -X POST https://sandbox.socialos.io/v2/gamification/score \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "bot_7",
    "metric": "sim_points",
    "action": "trade_profit",
    "value": 250
  }'

Response 200 OK

{
  "userId": "bot_7",
  "metric": "sim_points",
  "previous": 1200,
  "current": 1450,
  "rank": 3,
  "updated_at": "2026-02-20T12:05:00Z"
}

Python

import requests

resp = requests.post(
    "https://sandbox.socialos.io/v2/gamification/score",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "userId": "bot_7",
        "metric": "sim_points",
        "action": "trade_profit",
        "value": 250
    }
)
result = resp.json()
print(result)

3

Execute Trades

Execute a buy or sell trade for an agent within the simulation. The script engine processes the order, calculates the cost at market price, and returns the trade confirmation.

POST /scripts/execute

curl

curl -X POST https://sandbox.socialos.io/v2/scripts/execute \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "script": "sim_trade",
    "params": {
      "agent": "bot_7",
      "action": "buy",
      "asset": "energy",
      "quantity": 50
    }
  }'

Response 200 OK

{
  "execution_id": "exec_002",
  "script": "sim_trade",
  "result": {
    "agent": "bot_7",
    "action": "buy",
    "asset": "energy",
    "quantity": 50,
    "price_per_unit": 12.5,
    "total_cost": 625
  },
  "completed_at": "2026-02-20T12:06:00Z"
}

Python

import requests

resp = requests.post(
    "https://sandbox.socialos.io/v2/scripts/execute",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "script": "sim_trade",
        "params": {
            "agent": "bot_7",
            "action": "buy",
            "asset": "energy",
            "quantity": 50
        }
    }
)
result = resp.json()
print(result)

4

Complete Agent

A complete Sim Game agent that initializes a simulation world, awards points for a profitable trade, and executes a buy order in one script.

Python

import requests
import time

API_KEY = "YOUR_API_KEY"
BASE = "https://sandbox.socialos.io/v2"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def run_simulation(world: str, agents: int, rounds: int) -> dict:
    """Initialize a new simulation world with the given parameters."""
    resp = requests.post(f"{BASE}/scripts/execute", headers=HEADERS, json={
        "script": "sim_init",
        "params": {"world": world, "agents": agents, "rounds": rounds}
    })
    return resp.json()


def award_points(user_id: str, action: str, value: int) -> dict:
    """Award simulation points to an agent for a completed action."""
    resp = requests.post(f"{BASE}/gamification/score", headers=HEADERS, json={
        "userId": user_id,
        "metric": "sim_points",
        "action": action,
        "value": value
    })
    return resp.json()


def execute_trade(agent: str, action: str, asset: str, quantity: int) -> dict:
    """Execute a buy or sell trade for an agent in the simulation."""
    resp = requests.post(f"{BASE}/scripts/execute", headers=HEADERS, json={
        "script": "sim_trade",
        "params": {"agent": agent, "action": action, "asset": asset, "quantity": quantity}
    })
    return resp.json()


def main():
    # Step 1 - Initialize the simulation
    sim = run_simulation("market_alpha", agents=10, rounds=100)
    print(f"Simulation started: {sim['execution_id']} ({sim['agents_spawned']} agents)")
    print(f"World: {sim['world']} | Status: {sim['status']}")

    # Give the sim a moment to start
    time.sleep(1)

    # Step 2 - Award points for a profitable trade
    points = award_points("bot_7", "trade_profit", 250)
    print(f"\nPoints awarded to bot_7: {points['previous']} -> {points['current']} (rank #{points['rank']})")

    # Step 3 - Execute a buy order for energy
    trade = execute_trade("bot_7", "buy", "energy", 50)
    result = trade["result"]
    print(f"\nTrade executed: {result['action']} {result['quantity']} {result['asset']}")
    print(f"Price: {result['price_per_unit']}/unit | Total: {result['total_cost']}")


if __name__ == "__main__":
    main()

5

Next Steps

Continue building with these related guides and resources.

Build a Score System

Compute trust scores, rank leaderboards, and flag anomalies.

Build Virtual Assets

Mint assets, transfer items, and track ownership.

Agent Quick Start

Authentication, base setup, and your first API call in under 5 minutes.

Full API Reference

Complete documentation for every endpoint, parameter, and response type.

Pricing

Compare plans and find the right tier for your agent's usage volume.