Weekly Server Reset
The game server does a complete alpha reset every Sunday evening around 9pm PST. We use this reset as an opportunity to push breaking changes and new features. Join us on discord for announcements.

Getting Started

Thanks for checking out SpaceTraders! We are working on a multiplayer space trading platform built entirely on RESTful API endpoints to help aspiring and seasoned developers practice new languages and tools in a fun and meaningful way. You can try out the API by following the guide below under How To Play.

The game is a work in progress. If you think the idea is interesting, please let us know! We love hearing how our platform has helped support your learning or inspired you to build something cool.

If you want to try out the game with a GUI, we have several community built apps available on our spacetraders-awesome repository.

What's The Game?

SpaceTraders is a typical fleet management / trading / strategy game. Right now we've built the basic game features such as purchasing ships, navigating them around the universe, and trading goods at a profit. Later we plan to expand into construction, combat, exploration, factions, officers, ship modules and more.

Why An API Platform?

A RESTful API means you can use any programming language to play or automate the game.

For example, you can use our API to automate trades with Go, build out a frontend to visualize your fleet in React, extract market data into a MySQL database to analyze trends, or build a Voice-To-Command interface and control your fleet from a smart speaker.

How To Play Guide

All of the steps in this guide are executed from the command line. You will want to install HTTPie to follow along. If you are on a Mac and you have homebrew installed, you can execute the following:

brew install httpie

You can then hit any REST endpoint by simplying typing https along with the http method and the url. You can test this by hitting the game status endpoint which will tell us if the game is currently available to play:

https GET api.spacetraders.io/game/status
{
"status": "spacetraders is currently online and available to play"
}
This guide uses HTTPie because it's a clean and terse http client. Keep in mind that query parameters are passed as key==value and body payloads are passed as key=value.

Generate An Access Token

The API is only accessible if you have an access token. You can claim a username and generate a token by hitting the following endpoint. Make sure you save this token and don't share it with anyone. You can only generate a single token once per username.

Start by saving your desired username as a variable in your console.

https POST api.spacetraders.io/users/$username/token
Replace $username with the actual username you want to claim.

Copy your token and username and save them as variables in your console. This example assumes a Bash shell. The token will grant you access to the API. Saving these variables will make it easier to reuse for this tutorial.

token=yourTokenHere
username=yourUsernameHere

View Your User Account

Congratulations on taking your first steps toward the complete and total domination of galactic trade! Let's take a quick look at your account.

https GET api.spacetraders.io/users/$username token==$token
{
"user": {
"credits": 0,
"loans": [],
"ships": [],
"username": "space-trader"
}
}

Looks like you don't have much in the way of credits or assets. Let's see how we can fix that.

View Available Loans

Let's kick off our trade empire by taking out a small low-risk loan. We can use these funds to purchase our first ship and fill our cargo with something valuable.

https GET api.spacetraders.io/game/loans token==$token
{
"loans": [
{
"amount": 200000,
"collateralRequired": false,
"rate": 40,
"termInDays": 2,
"type": "STARTUP"
}
]
}

Take Out A Loan

Let's take out a small loan to kick off our new venture.

https POST api.spacetraders.io/users/$username/loans token==$token \
type=STARTUP
{
"user": {
"credits": 200000,
"loans": [
{
"due": "2021-03-10T06:27:28.956Z",
"id": "ckm07ctoe0250ti0jat8jt55h",
"repaymentAmount": 280000,
"status": "CURRENT",
"type": "STARTUP"
}
],
"ships": [],
"username": "space-trader"
}
}

View Ships To Purchase

Now our credits are looking much healthier! But remember, you will have to pay it back by the due date. Let's buy a small ship to start shipping goods around and hopefully make enough to pay back our loan.

https GET api.spacetraders.io/game/ships token==$token \
class==MK-I
{
"ships": [
{
"class": "MK-I",
"manufacturer": "Gravager",
"maxCargo": 300,
"plating": 10,
"purchaseLocations": [
{
"location": "OE-PM-TR",
"price": 184000
},
{
"location": "OE-NY",
"price": 184000
}
],
"speed": 1,
"type": "GR-MK-I",
"weapons": 5
},
{
"class": "MK-I",
"manufacturer": "Jackshaw",
"maxCargo": 100,
"plating": 5,
"purchaseLocations": [
{
"location": "OE-PM-TR",
"price": 94000
},
{
"location": "OE-NY",
"price": 94000
}
],
"speed": 2,
"type": "JW-MK-I",
"weapons": 5
},
{
"class": "MK-I",
"manufacturer": "Electrum",
"maxCargo": 100,
"plating": 5,
"purchaseLocations": [
{
"location": "OE-NY",
"price": 302400
}
],
"speed": 2,
"type": "EM-MK-I",
"weapons": 10
}
]
}

Choose one of the available ships and send a request to purchase it. The Jackshaw looks like a good cheap option.

Purchase A Ship

https POST api.spacetraders.io/users/$username/ships token==$token \
location=OE-PM-TR \
type=JW-MK-I
{
"user": {
"credits": 106000,
"loans": [
{
"due": "2021-03-10T06:27:28.956Z",
"id": "ckm07ctoe0250ti0jat8jt55h",
"repaymentAmount": 280000,
"status": "CURRENT",
"type": "STARTUP"
}
],
"ships": [
{
"cargo": [],
"class": "MK-I",
"id": "ckm07ezq50354ti0j1drcey9v",
"location": "OE-PM-TR",
"manufacturer": "Jackshaw",
"maxCargo": 100,
"plating": 5,
"spaceAvailable": 100,
"speed": 2,
"type": "JW-MK-I",
"weapons": 5,
"x": 21,
"y": -26
}
],
"username": "space-trader"
}
}

Save your ship ID to a variable so we can resuse it in a moment.

shipId=yourShipId

Now let's load it up with fuel and metals and see if we can make a profitable trade.

Purchase Ship Fuel

https POST api.spacetraders.io/users/$username/purchase-orders token==$token \
shipId=$shipId \
good=FUEL \
quantity=20
{
"credits": 105960,
"order": {
"good": "FUEL",
"pricePerUnit": 2,
"quantity": 20,
"total": 40
},
"ship": {
"cargo": [
{
"good": "FUEL",
"quantity": 20,
"totalVolume": 20
}
],
"class": "MK-I",
"id": "ckm07ezq50354ti0j1drcey9v",
"location": "OE-PM-TR",
"manufacturer": "Jackshaw",
"maxCargo": 100,
"plating": 5,
"spaceAvailable": 80,
"speed": 2,
"type": "JW-MK-I",
"weapons": 5,
"x": 21,
"y": -26
}
}

View Marketplace

Each location has a marketplace of goods. Let's see what's available to us.

https GET api.spacetraders.io/game/locations/OE-PM-TR/marketplace token==$token
{
"location": {
"marketplace": [
{
"pricePerUnit": 4,
"quantityAvailable": 406586,
"symbol": "METALS",
"volumePerUnit": 1
},
{
"pricePerUnit": 231,
"quantityAvailable": 5407,
"symbol": "MACHINERY",
"volumePerUnit": 4
},
{
"pricePerUnit": 8,
"quantityAvailable": 406586,
"symbol": "CHEMICALS",
"volumePerUnit": 1
},
{
"pricePerUnit": 1,
"quantityAvailable": 462806,
"symbol": "FUEL",
"volumePerUnit": 1
},
{
"pricePerUnit": 127,
"quantityAvailable": 19961,
"symbol": "SHIP_PLATING",
"volumePerUnit": 2
},
{
"pricePerUnit": 30,
"quantityAvailable": 403,
"symbol": "DRONES",
"volumePerUnit": 2
},
{
"pricePerUnit": 1283,
"quantityAvailable": 8738,
"symbol": "SHIP_PARTS",
"volumePerUnit": 5
}
],
"name": "Tritus",
"symbol": "OE-PM-TR",
"type": "MOON",
"x": 21,
"y": -26
}
}

Metals look like a solid trade good. Let's fill our cargo full.

https POST api.spacetraders.io/users/$username/purchase-orders token==$token \
shipId=$shipId \
good=METALS \
quantity=30
{
"credits": 178725,
"order": {
"good": "METALS",
"pricePerUnit": 3,
"quantity": 30,
"total": 90
},
"ship": {
"cargo": [
{
"good": "FUEL",
"quantity": 20,
"totalVolume": 20
},
{
"good": "METALS",
"quantity": 30,
"totalVolume": 30
}
],
"class": "MK-I",
"id": "ckne4w8me01141ds62dnui0c8",
"location": "OE-PM-TR",
"manufacturer": "Jackshaw",
"maxCargo": 50,
"plating": 5,
"spaceAvailable": 0,
"speed": 1,
"type": "JW-MK-I",
"weapons": 5,
"x": 23,
"y": -28
}
}

Find Nearby Planet

Now we need to find a nearby planet to unload our cargo.

https GET api.spacetraders.io/game/systems/OE/locations token==$token type==PLANET
{
"locations": [
{
"name": "Carth",
"symbol": "OE-CR",
"type": "PLANET",
"x": 16,
"y": 17
},
{
"name": "Koria",
"symbol": "OE-KO",
"type": "PLANET",
"x": -48,
"y": -7
},
{
"name": "Ucarro",
"symbol": "OE-UC",
"type": "PLANET",
"x": -75,
"y": 82
},
{
"name": "Prime",
"symbol": "OE-PM",
"type": "PLANET",
"x": 20,
"y": -25
}
]
}

Looks like Prime is right next to us. Let's create a flight plan to send our ship to the planet.

Create Flight Plan

https POST api.spacetraders.io/users/$username/flight-plans token==$token \
shipId=$shipId \
destination=OE-PM
{
"flightPlan": {
"arrivesAt": "2021-03-08T06:41:19.658Z",
"departure": "OE-PM-TR",
"destination": "OE-PM",
"distance": 1,
"fuelConsumed": 1,
"fuelRemaining": 19,
"id": "ckm07t6ki0038060jv7b2x5gk",
"shipId": "ckm07ezq50354ti0j1drcey9v",
"terminatedAt": null,
"timeRemainingInSeconds": 67
}
}

You can monitor your ship's flight plan until it arrives. Save your flight plan ID to a variable so we can resuse it in a moment.

flightPlanId=yourFlightPlanId

View Flight Plan

https GET api.spacetraders.io/users/$username/flight-plans/$flightPlanId token==$token
{
"flightPlan": {
"arrivesAt": "2021-03-08T06:41:19.658Z",
"departure": "OE-PM-TR",
"destination": "OE-PM",
"distance": 1,
"fuelConsumed": 1,
"fuelRemaining": 19,
"id": "ckm07t6ki0038060jv7b2x5gk",
"shipId": "ckm07ezq50354ti0j1drcey9v",
"terminatedAt": "2021-03-08T06:41:18.752Z",
"timeRemainingInSeconds": 0
}
}

Sell Trade Goods

Let's place a sell order for our metals.

https POST api.spacetraders.io/users/$username/sell-orders token==$token \
shipId=$shipId \
good=METALS \
quantity=30
{
"credits": 178935,
"order": {
"good": "METALS",
"pricePerUnit": 7,
"quantity": 30,
"total": 210
},
"ship": {
"cargo": [
{
"good": "FUEL",
"quantity": 18,
"totalVolume": 18
}
],
"class": "MK-I",
"id": "ckne4w8me01141ds62dnui0c8",
"location": "OE-PM",
"manufacturer": "Jackshaw",
"maxCargo": 50,
"plating": 5,
"spaceAvailable": 32,
"speed": 1,
"type": "JW-MK-I",
"weapons": 5,
"x": 20,
"y": -25
}
}

Next Steps

Congratulations! You made your first profitable trade. You will likely want to trade in higher margin goods, but metals are a sure-fire way to make some credits. Try buying another ship, exploring each market, and maybe automate your way to wealth and glory! When you're ready to pay back your loan, you can hit the final endpoint in this guide:

https PUT api.spacetraders.io/users/$username/loans/$loanId token==$token
{
"user": {
"credits": 32000,
"loans": [
{
"due": "2021-03-10T00:39:03.890Z",
"id": "cklzuwr840088jpvqhvyrgk73",
"repaymentAmount": 168000,
"status": "PAID",
"type": "STARTUP"
}
],
"ships": [
{
"cargo": [
{
"good": "FUEL",
"quantity": 4,
"totalVolume": 4
}
],
"class": "MK-I",
"id": "cklzv1dih0238jpvqvr19pk62",
"location": "OE-PM",
"manufacturer": "Jackshaw",
"maxCargo": 100,
"plating": 5,
"spaceAvailable": 96,
"speed": 2,
"type": "JW-MK-I",
"weapons": 5
}
],
"username": "space-trader"
}
}

FAQ

Are there API Docs?

Yes, see api.spacetraders.io.

Note that this documentation might not always be up to date. Work is being done to improve the API documentation but it's on hold currently until beta stage. If you see anything which is incorrect please let us know.

Where can I submit bugs?

You can either directly submit an issue using our issue tracker: https://github.com/SpaceTradersAPI/issues-and-suggestions/issues

-- or --

Feel free to join our discord at https://discord.gg/jh6zurdWk5 and describe your issue to us. All our members are extremely helpful and often come from various development levels and backgrounds.

How can I support this project?

Consider supporting us, it would let us scale better as our users grow and server costs increase.

Support us on Patreon

Is this project open source? Can I contribute to the codebase?

We get this one a lot! The codebase is currently private while we work towards our main featureset.

Part of the reason for this, is that we don't want to give away all of the game mechanics and facets of discovery and exploration we have planned.

That being said, we also do plan to go open sourced eventually post-launch.