SimTX API

The SimTX API is the set of public interfaces that third-party software uses to work with SimTX. With it, a program can receive the simulated radio spectrum as raw IQ samples, put its own transmitter on the air, manage persistent stations and launch satellites, read the list of stations, request coverage and weather maps, satellite ephemerides and pass predictions, and publish packages to the extension catalog, all without the official SimTX applications.

The API has two parts:

• The account service, an HTTPS JSON API at auth.simtx.net. It signs users in, manages stations and satellites, lists game servers and issues single-use game tickets.
• The game protocol, a protobuf protocol over TLS spoken directly with a game server. Receiving, transmitting and control traffic all use it. The current version is 25.

This reference covers what a client sends and receives. The version 24 reference is at SimTX API v24.

How the pieces fit

              HTTPS + JSON                                     TLS + protobuf (v25)
  client ────────────────────────▶ auth.simtx.net      client ────────────────────────▶ game server
    1. device login         → credentials                 5. preface + ClientHello (role, ticket)
    2. GET  /api/v1/stations → your stations              6. ReceiverStart or TransmitterStart
    3. GET  /api/v1/servers  → host and port              7. IQ in, samples out, or control traffic
    4. POST /api/v1/game-tickets → one-shot ticket

• Receiving needs no account. An ad-hoc receiver, which brings its own callsign, position and antenna, and the control role accept anonymous connections. Such a client skips steps 1 to 4 and needs only a host and port.
• Transmitting needs an account and a station. A transmitter is bound to one of the account's persistent stations. It needs the game.transmit permission and a fresh game ticket for every connection.
• Station-bound reception works on the account's own stations and on any PUBLIC station of another account, including satellites.
• One TCP connection is one session. A client that wants two receivers, or a receiver and a transmitter, opens two connections.

Where to start

If you want to...	Read
Receive IQ with a minimal script	SimTX API/Quick start
Receive IQ in your own SDR software	SimTX API/Connection and handshake, SimTX API/Framing, then SimTX API/Receiver session
Transmit from your own software	SimTX API/Device login, SimTX API/Stations, SimTX API/Game tickets, then SimTX API/Transmitter session
Create stations or launch a satellite	SimTX API/Station endpoints, SimTX API/Satellites
Track a satellite and correct Doppler	SimTX API/Tracking and pointing
Show a station list or map	SimTX API/Control session
Publish extensions from a script	SimTX API/Extension catalog protocol
Look up one message	SimTX API/Packet list
Understand why a session ended	SimTX API/Session status, SimTX API/Limits and errors

Reference pages

Account service

• SimTX API/Account service: base URL, authentication, credential formats, errors and rate limits.
• SimTX API/Device login: signing a user in from a desktop or command-line program.
• SimTX API/Server directory: discovering game servers and their features.
• SimTX API/Station endpoints: creating and editing stations, launching and deorbiting satellites.
• SimTX API/Game tickets: exchanging a credential for a one-shot game server ticket, optionally bound to a station.
• SimTX API/Permissions: scopes, permission identifiers and numeric capabilities.
• SimTX API/Public endpoints: status, public satellites, profiles, releases and network test.

Game protocol

• SimTX API/Connection and handshake: TLS, the preface, the hello, roles and hello results.
• SimTX API/Framing: length-delimited frames, size limits and skipping unknown frames.
• SimTX API/Data types: protobuf types, conventions and shared messages.
• SimTX API/Session status: how receiver and transmitter sessions are bound, updated, refused and ended.
• SimTX API/Receiver session: requesting a receiver and decoding IQ.
• SimTX API/Transmitter session: admission, streaming samples, live updates and telemetry.
• SimTX API/Control session: station list, banners, health, coverage and weather maps, ephemerides, passes, monitoring.
• SimTX API/Extension catalog protocol: listing, fetching, uploading and deleting catalog entries.
• SimTX API/Moderation session: moderator tools. Not usable without moderator permission.
• SimTX API/Limits and errors: the error model, session limits, rate limits and timeouts.
• SimTX API/Compatibility and versioning: protocol revisions, the feature registry and what may change.
• SimTX API/Packet list: every frame member in both directions.
• SimTX API/Schema: the .proto files.

Stations and satellites

• SimTX API/Stations: persistent stations, station-bound and ad-hoc sessions, what the station dictates.
• SimTX API/Satellites: user-launched satellites, the orbit model, ephemerides, passes and deorbiting.
• SimTX API/Tracking and pointing: steerable antennas, rotators and Doppler correction.

Design notes

• Protobuf frames. Every message is a protobuf message. On the wire each one is a varint length followed by a ClientFrame or ServerFrame, a message with a single oneof. The recommended approach is to generate bindings from the .proto files with protoc. A hand-written codec needs only varints, 32- and 64-bit little-endian values and length-delimited fields; SimTX API/Quick start shows one in a few dozen lines of Python.
• Unknown is not an error. A frame whose oneof member a reader does not know, and a field it does not know, are skipped. See SimTX API/Compatibility and versioning.
• Rejections are never silent. A refused hello gets a ServerHello with a status, a refused or ended session a SessionStatus with an error code and a reason, and a failed request an Error with its request_id.
• Real time. Receivers get samples at the rate of the simulation, and transmitters must send samples at the rate they declared. Neither side waits for the other. A client that falls behind loses data.
• Simulated reception. The IQ a receiver gets includes the propagation, fading, Doppler shift, noise and interference at its location and antenna. See Propagation Basics.

Versioning

The game protocol version is the integer in the 8-byte preface; the current version is 25. Both hellos carry a protocol revision, and optional server capabilities appear in the feature registry. See SimTX API/Compatibility and versioning.

The account service API is versioned in its path (/api/v1/). New response fields may be added without a version change; clients must ignore fields they do not recognise.

Terms of use

SimTX is a shared simulation with other people listening. Software built on this API is subject to the same rules as the official applications. Keep request rates within the documented limits, identify your software honestly in clientName during device login and in ClientHello.client_name, and do not use the API to disrupt other users.