SimTX API v24

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, read the list of stations, request coverage and weather maps, and publish packages to the extension catalog, all without the official SimTX Transmitter application.

The API has two parts:

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

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 endpoints.

How the pieces fit

                 HTTPS + JSON                                   TLS + binary (v24)
  client ───────────────────────▶ auth.simtx.net      client ───────────────────────▶ game server
    1. device login       → credentials                  4. Handshake (role + ticket)
    2. GET  /api/v1/servers → host and port              5. session request
    3. POST /api/v1/game-tickets → one-shot ticket       6. IQ in, samples out, or control traffic

• Receiving needs no account. The receiver, timestamped receiver and control roles accept anonymous connections. Such a client skips steps 1 to 3 and needs only a host and port.
• Transmitting needs an account with the game.transmit permission, and a fresh game ticket for every connection.
• 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 from SimTX in your own SDR software	SimTX API/Connection and handshake, then SimTX API/Receiver session
Transmit from your own software	SimTX API/Device login, SimTX API/Game tickets, then SimTX API/Transmitter session
Show a station list or map	SimTX API/Control session
Publish extensions from a script	SimTX API/Extension catalog protocol
Look up one packet	SimTX API/Packet list
Understand why the server hung up	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.
• SimTX API/Game tickets: exchanging a credential for a one-shot game server ticket.
• SimTX API/Permissions: permission identifiers and numeric capabilities.
• SimTX API/Public endpoints: status, profiles, releases and network test.

Game protocol

• SimTX API/Data types: byte order, string encodings and shared structures.
• SimTX API/Connection and handshake: TLS, the handshake, roles and handshake results.
• 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, 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: session limits, timeouts, how failures are reported, reconnection.
• SimTX API/Packet list: every packet ID in both directions.

Design notes

A few properties of the protocol are worth knowing before writing any code, because they explain most of its sharp edges:

• No length prefixes. Packets are an ID byte followed by a body whose layout the reader must already know. Reading one field too few or too many silently misaligns everything after it. Write the decoder carefully, and test it against a real server early.
• Silence is an answer. Several kinds of failure, especially invalid receiver requests and limit rejections, are reported by closing the connection without a message. When the socket closes right after a request, the request was probably invalid or over a limit. SimTX API/Limits and errors lists the cases.
• Exact version match. Server and client must both speak version 24. There is no negotiation and no backwards compatibility. A server that moves to a new version rejects old clients with a clear HandshakeResult rather than misbehaving.
• 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, noise and interference included. A station that cannot be heard is often simply out of range, or on the wrong side of the day–night terminator. See Propagation Basics.

Versioning

The game protocol version is a single integer sent in the handshake. Any incompatible change increments it. Within a version, the TLV-encoded transmitter request may gain new optional fields, which older clients simply do not send.

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 application. Keep request rates within the documented limits, identify your software honestly in clientName during device login, and do not use the API to disrupt other users.