V1 API Deprecation

This guide follows the V1 API which is no longer maintained (but will remain available to play). You can now try out the V2 API here: V2 API - Getting Started.

Getting Started

Thanks for checking out SpaceTraders! We are working on a multiplayer space trading game built on REST endpoints. Our platform allows you to use any programming language to play the game, create a custom client, or automate your fleet of ships.

You can try the API in less than five minutes by following the guide below. If you want to try out the game with a GUI, we have several community built apps available on our spacetraders-awesome repository.

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/claim

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/my/account token==$token

{
  "user": {
    "credits": 0,
    "joinedAt": "2021-05-13T02:29:41.741Z",
    "shipCount": 0,
    "structureCount": 0,
    "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/types/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/my/loans token==$token \
  type=STARTUP

{
  "credits": 200000,
  "loan": {
    "due": "2021-05-15T02:32:43.269Z",
    "id": "ckoma153c0060zbnzquw2xa29",
    "repaymentAmount": 280000,
    "status": "CURRENT",
    "type": "STARTUP"
  }
}

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/systems/OE/ship-listings token==$token \
  class==MK-I

{
  "shipListings": [
    {
      "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/my/ships token==$token \
  location=OE-PM-TR \
  type=JW-MK-I

{
  "user": {
    "credits": 178875
  },
  "ship": {
    "cargo": [],
    "class": "MK-I",
    "id": "ckno9324k0079iiop71j5nrob",
    "location": "OE-PM-TR",
    "manufacturer": "Jackshaw",
    "maxCargo": 50,
    "plating": 5,
    "spaceAvailable": 50,
    "speed": 1,
    "type": "JW-MK-I",
    "weapons": 5,
    "x": 21,
    "y": -24
  }
}

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/my/purchase-orders token==$token \
  shipId=$shipId \
  good=FUEL \
  quantity=20

{
  "user": {
    "credits": 178815
  },
  "order": {
    "good": "FUEL",
    "pricePerUnit": 3,
    "quantity": 20,
    "total": 60
  },
  "ship": {
    "cargo": [
      {
        "good": "FUEL",
        "quantity": 20,
        "totalVolume": 20
      }
    ],
    "class": "MK-I",
    "id": "ckm07ezq50354ti0j1drcey9v",
    "location": "OE-PM-TR",
    "manufacturer": "Jackshaw",
    "maxCargo": 50,
    "plating": 5,
    "spaceAvailable": 30,
    "speed": 1,
    "type": "JW-MK-I",
    "weapons": 5,
    "x": 21,
    "y": -24
  }
}

View Marketplace

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

https GET api.spacetraders.io/locations/OE-PM-TR/marketplace token==$token

{
  "marketplace": {
    "goods": [
      {
        "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
      }
    ]
  }
}

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

https POST api.spacetraders.io/my/purchase-orders token==$token \
  shipId=$shipId \
  good=METALS \
  quantity=25

{
  "credits": 178125,
  "order": {
    "good": "METALS",
    "pricePerUnit": 23,
    "quantity": 25,
    "total": 690
  },
  "ship": {
    "cargo": [
      {
        "good": "FUEL",
        "quantity": 20,
        "totalVolume": 20
      },
      {
        "good": "METALS",
        "quantity": 25,
        "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": 21,
    "y": -24
  }
}

Find Nearby Planet

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

https GET api.spacetraders.io/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/my/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/my/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/my/sell-orders token==$token \
  shipId=$shipId \
  good=METALS \
  quantity=25

{
  "credits": 178755,
  "order": {
    "good": "METALS",
    "pricePerUnit": 21,
    "quantity": 25,
    "total": 630
  },
  "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/my/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"
  }
}