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 documents both as they are deployed. It does not cover the protocol that SimTX servers use among themselves, the propagation model, or administrative and internal endpoints. The previous protocol version is archived at SimTX API v24; servers that speak v25 refuse v24 clients.

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
See something working in five minutes	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
Port a v24 client	Changes from v24

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. That is how the protocol grows within version 25 without breaking existing clients. 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.
• Physics, not a jukebox. The IQ a receiver gets is what an antenna at that location would deliver: propagation, fading, Doppler, noise and interference included. A station that cannot be heard is often simply out of range, below the horizon, or on the wrong side of the day-night terminator. See Propagation Basics.

Versioning

The game protocol version is the integer in the 8-byte preface. Only a breaking change increments it; version 25 replaced version 24, and the two are not compatible. Within version 25, additive changes that a peer may need to detect increment the protocol revision carried in both hellos, and optional capabilities of a deployment 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.