Spacetraders 3: Getting to know the game

Jan 9

Before writing any serious logic or automation, it helps to understand what kind of universe you are actually interacting with

In the previous posts, I focused on setting the technical foundations: how OpenAPI works in general, and how I prepared a PostgreSQL database to store and analyze data coming from the game. With that groundwork in place, this post takes a step back and looks at SpaceTraders itself.

This is not a coding guide, and it’s not an endpoint-by-endpoint walkthrough. Instead, it’s an overview of how the game world is structured, what the main mechanics are, and how the API reflects those mechanics. The goal is to build a mental model that makes later implementation decisions feel obvious rather than forced.

For a complete, browsable list of endpoints, the official OpenAPI definition is available here:

https://spacetraders.io/openapi

What follows is the perspective I wanted to have before actually starting to play.

What SpaceTraders Is, Conceptually

SpaceTraders is a persistent, shared simulation of a space economy, exposed entirely through an API.

You don’t control a pilot or a character in real time. You operate an agent that owns ships, signs contracts, trades goods, extracts resources, and explores a large procedural universe. Every action is an HTTP request, but the systems behind those requests behave like a strategy game with state, delays, risk, and limited information.

Once you look past the curl commands, the game feels like a mix of:

a logistics and trading simulator
a resource management game
and a practical exercise in working with rate-limited, stateful APIs

Agents and the `/my` Namespace

Everything you do belongs to your agent.

After registration, all endpoints under the /my/* namespace become agent-specific. This includes:

/my/agent for identity and credits
/my/contracts for progression
/my/ships for fleet management
/my/factions for reputation tracking

The API structure mirrors this idea very cleanly. Anything under /my assumes you are authenticated and acting on your own behalf. Anything outside of it describes the universe itself.

Reputation with factions is still fairly lightweight in the current alpha, but it’s already clear that long-term progression will be tied to who you work with and how consistently you deliver.

Systems, Waypoints, and Location Hierarchy

The universe is organized in layers.

At the top level, there are systems, each with absolute X and Y coordinates in the galaxy. Within each system, there are waypoints, which are the actual locations ships can interact with.

Waypoints have symbolic identifiers that encode this hierarchy. For example:

X1 refers to a sector
X1-BB43 refers to a system
X1-BB43-A1 refers to a waypoint

Waypoints can represent planets, moons, asteroid fields, stations, jump gates, and more. Some waypoints share the same coordinates, which effectively places them in orbit around the same body.

Two waypoint traits quickly become essential:

MARKETPLACE for trading goods
SHIPYARD for purchasing ships and, later, upgrades

Waypoints can also have temporary modifiers. One practical example is asteroids approaching a critical extraction limit, which pushes you to think about sustainability instead of endlessly farming one location.

Ships as Stateful Objects

Ships in SpaceTraders behave like small state machines.

Before a ship can travel, it must be in orbit. To trade, refuel, or repair, it must be docked. While navigating, most other actions are unavailable. This is reflected clearly in endpoints such as:

/my/ships/{shipSymbol}/orbit
/my/ships/{shipSymbol}/dock
/my/ships/{shipSymbol}/navigate

Orbiting and docking are idempotent, which makes them safe to call defensively. This small design detail matters a lot once you start automating behavior.

Ships also support different flight modes, updated through /my/ships/{shipSymbol}/nav. Choosing between cruise, burn, drift, or stealth affects fuel consumption, speed, and risk, which turns navigation into a strategic choice rather than a trivial one.

Contracts as Structured Progression

Contracts provide the main direction early in the game.

Through /my/contracts, you receive tasks that usually involve acquiring resources, transporting them to a specific waypoint, and delivering them before a deadline. Contracts expire, but new ones can be negotiated, which creates a steady incentive to stay active.

What’s interesting is how many systems a single contract touches. Even a simple delivery requires:

owning a ship
navigating between waypoints
extracting or purchasing goods
managing cargo space
and interacting with markets

Contracts are where all mechanics start to connect.

Extracting Resources and Managing Cooldowns

Mining and siphoning are not instant actions.

Extraction requires the right mounts and modules, and every extraction triggers a cooldown during which most other actions are unavailable. This is handled through endpoints like:

/my/ships/{shipSymbol}/extract
/my/ships/{shipSymbol}/siphon

Surveying adds another layer. Using /my/ships/{shipSymbol}/survey lets you identify more targeted resource deposits, but surveys expire and deposits are limited. This encourages planning and data collection rather than brute-force extraction.

Markets and Economic Behavior

Markets are driven by supply and demand, and they behave locally.

Each marketplace distinguishes between:

exports, which are produced locally
imports, which are consumed locally
exchange goods, which are traded only between agents

Market data is only visible when your ship is physically present at the waypoint, through endpoints such as:

/systems/{systemSymbol}/waypoints/{waypointSymbol}/market

This design quietly encourages you to deploy probe ships, gather historical price data, and think in terms of trends rather than snapshots. Fuel stands out as a universal exchange good, with demand driven entirely by player activity.

Once you start recording prices over time, the game begins to feel very data-friendly.

Exploration, Risk, and Information Gaps

Not all systems are equally safe or equally valuable.

Some contain hazards that can damage ships or affect crew morale. Others sit at the edge of the universe and trade in rarer goods. Exploration rewards agents willing to accept incomplete information and occasional losses.

Charting, surveying, and scouting all feed into this loop. Some information is only available by visiting a location, or by installing better scanners, which reinforces the idea that knowledge itself is a resource.

Outfitting, Maintenance, and Long-Term Decisions

Ships are composed of frames, reactors, engines, modules, and mounts.

Only modules and mounts can be swapped, and even that requires planning, since components must be present in the cargo hold during installation. Over time, ships degrade. Repairs restore condition but reduce long-term integrity, and scrapping yields credits at the cost of destroying the ship and its cargo.

These mechanics push you toward thinking about fleet lifecycle, and not just expansion.

Rate Limits as Part of the Game

SpaceTraders enforces strict rate limits per IP and per account.

It’s not just a technical constraint. It shapes how you interact with the game. Efficient agents batch requests, cache data, and react to events instead of polling constantly. In practice, this leads to cleaner designs and better data models.

Quickstart Cheat Sheet: From Registration to First Contract

To tie everything together, here is the high-level flow that mirrors the game’s own onboarding:

Register an agent
Endpoint: POST /register
Inspect agent state
Endpoint: GET /my/agent
Review available contracts
Endpoint: GET /my/contracts
Accept a contract
Endpoint: POST /my/contracts/{contractId}/accept
Locate a shipyard
Endpoint: GET /systems/{systemSymbol}/waypoints?traits=SHIPYARD
Purchase a ship
Endpoint: POST /my/ships
Navigate to a resource waypoint
Endpoint: POST /my/ships/{shipSymbol}/navigate
Extract resources
Endpoint: POST /my/ships/{shipSymbol}/extract
Deliver goods to the contract waypoint
Endpoint: POST /my/contracts/{contractId}/deliver
Fulfill the contract
Endpoint: POST /my/contracts/{contractId}/fulfill

This loop is simple, but it already touches navigation, extraction, cargo management, and markets. Almost every later system builds on it.

Final thoughts

SpaceTraders rewards agents who understand state, constraints, and delayed outcomes. It’s a game that favors planning, data collection, and incremental optimization.

With this overview in place, the next posts can focus on actual gameplay and design choices: how I store market data, how I decide where to send ships, what I automate first, and what turns out to be harder than expected.

This post is putting together everything I learned from the documentation, before taking the first real step.

spacetradersoverviewquickstart

Kamil Pospiech