SimTX API v24 - Revision history

Clanker: Archive the v24 protocol reference: use the v24 templates, links and categories

2026-10-24T16:13:27Z

Archive the v24 protocol reference: use the v24 templates, links and categories

Clanker: Clanker moved page SimTX API to SimTX API v24: Archive the v24 protocol reference

2026-10-24T16:11:21Z

Clanker moved page SimTX API to SimTX API v24: Archive the v24 protocol reference

← Older revision	Revision as of 16:11, 24 October 2026
(No difference)

Clanker: SimTX API documentation

2026-10-24T09:47:22Z

SimTX API documentation

New page

{{SimTX API navigation}}
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 '''[[SimTX API/Account service|account service]]''', an HTTPS JSON API at <code>auth.simtx.net</code>. 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 ==
<syntaxhighlight lang="text">
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
</syntaxhighlight>

* '''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 <code>game.transmit</code> [[SimTX API/Permissions|permission]], and a fresh [[SimTX API/Game tickets|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 ==
{| class="wikitable"
! 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 [[SimTX API/Packets/HandshakeResult|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 [[SimTX API/Packets/TransmitterSessionRequest|transmitter request]] may gain new optional fields, which older clients simply do not send.

The account service API is versioned in its path (<code>/api/v1/</code>). 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 <code>clientName</code> during [[SimTX API/Device login|device login]], and do not use the API to disrupt other users.

{{SimTX API navbox}}
[[Category:SimTX API]]

← Older revision		Revision as of 16:13, 24 October 2026
Line 1:		Line 1:
	{{SimTX API navigation}}		{{SimTX API v24 navigation}}
	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 '''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 API has two parts:
	* The '''[[SimTX API/Account service\|account service]]''', an HTTPS JSON API at <code>auth.simtx.net</code>. It signs users in, lists game servers and issues single-use game tickets.		* The '''[[SimTX API v24/Account service\|account service]]''', an HTTPS JSON API at <code>auth.simtx.net</code>. 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'''.		* 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'''.

Line 18:		Line 18:

	* '''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.		* '''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 <code>game.transmit</code> [[SimTX API/Permissions\|permission]], and a fresh [[SimTX API/Game tickets\|game ticket]] for every connection.		* '''Transmitting needs an account''' with the <code>game.transmit</code> [[SimTX API v24/Permissions\|permission]], and a fresh [[SimTX API v24/Game tickets\|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.		* '''One TCP connection is one session.''' A client that wants two receivers, or a receiver and a transmitter, opens two connections.

Line 25:		Line 25:
	! If you want to… !! Read		! If you want to… !! Read
	\|-		\|-
	\| See something working in five minutes \|\| [[SimTX API/Quick start]]		\| See something working in five minutes \|\| [[SimTX API v24/Quick start]]
	\|-		\|-
	\| Receive IQ from SimTX in your own SDR software \|\| [[SimTX API/Connection and handshake]], then [[SimTX API/Receiver session]]		\| Receive IQ from SimTX in your own SDR software \|\| [[SimTX API v24/Connection and handshake]], then [[SimTX API v24/Receiver session]]
	\|-		\|-
	\| Transmit from your own software \|\| [[SimTX API/Device login]], [[SimTX API/Game tickets]], then [[SimTX API/Transmitter session]]		\| Transmit from your own software \|\| [[SimTX API v24/Device login]], [[SimTX API v24/Game tickets]], then [[SimTX API v24/Transmitter session]]
	\|-		\|-
	\| Show a station list or map \|\| [[SimTX API/Control session]]		\| Show a station list or map \|\| [[SimTX API v24/Control session]]
	\|-		\|-
	\| Publish extensions from a script \|\| [[SimTX API/Extension catalog protocol]]		\| Publish extensions from a script \|\| [[SimTX API v24/Extension catalog protocol]]
	\|-		\|-
	\| Look up one packet \|\| [[SimTX API/Packet list]]		\| Look up one packet \|\| [[SimTX API v24/Packet list]]
	\|-		\|-
	\| Understand why the server hung up \|\| [[SimTX API/Limits and errors]]		\| Understand why the server hung up \|\| [[SimTX API v24/Limits and errors]]
	\|}		\|}

	== Reference pages ==		== Reference pages ==
	=== Account service ===		=== Account service ===
	* [[SimTX API/Account service]]: base URL, authentication, credential formats, errors and rate limits.		* [[SimTX API v24/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 v24/Device login]]: signing a user in from a desktop or command-line program.
	* [[SimTX API/Server directory]]: discovering game servers.		* [[SimTX API v24/Server directory]]: discovering game servers.
	* [[SimTX API/Game tickets]]: exchanging a credential for a one-shot game server ticket.		* [[SimTX API v24/Game tickets]]: exchanging a credential for a one-shot game server ticket.
	* [[SimTX API/Permissions]]: permission identifiers and numeric capabilities.		* [[SimTX API v24/Permissions]]: permission identifiers and numeric capabilities.
	* [[SimTX API/Public endpoints]]: status, profiles, releases and network test.		* [[SimTX API v24/Public endpoints]]: status, profiles, releases and network test.

	=== Game protocol ===		=== Game protocol ===
	* [[SimTX API/Data types]]: byte order, string encodings and shared structures.		* [[SimTX API v24/Data types]]: byte order, string encodings and shared structures.
	* [[SimTX API/Connection and handshake]]: TLS, the handshake, roles and handshake results.		* [[SimTX API v24/Connection and handshake]]: TLS, the handshake, roles and handshake results.
	* [[SimTX API/Receiver session]]: requesting a receiver and decoding IQ.		* [[SimTX API v24/Receiver session]]: requesting a receiver and decoding IQ.
	* [[SimTX API/Transmitter session]]: admission, streaming samples, live updates and telemetry.		* [[SimTX API v24/Transmitter session]]: admission, streaming samples, live updates and telemetry.
	* [[SimTX API/Control session]]: station list, banners, health, coverage and weather maps, monitoring.		* [[SimTX API v24/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 v24/Extension catalog protocol]]: listing, fetching, uploading and deleting catalog entries.
	* [[SimTX API/Moderation session]]: moderator tools. Not usable without moderator permission.		* [[SimTX API v24/Moderation session]]: moderator tools. Not usable without moderator permission.
	* [[SimTX API/Limits and errors]]: session limits, timeouts, how failures are reported, reconnection.		* [[SimTX API v24/Limits and errors]]: session limits, timeouts, how failures are reported, reconnection.
	* [[SimTX API/Packet list]]: every packet ID in both directions.		* [[SimTX API v24/Packet list]]: every packet ID in both directions.

	== Design notes ==		== Design notes ==
Line 64:		Line 64:

	* '''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.		* '''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.		* '''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 v24/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 [[SimTX API/Packets/HandshakeResult\|HandshakeResult]] rather than misbehaving.		* '''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 [[SimTX API v24/Packets/HandshakeResult\|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.		* '''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]].		* '''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 ==		== Versioning ==
	The game protocol version is a single integer sent in the handshake. Any incompatible change increments it. Within a version, the TLV-encoded [[SimTX API/Packets/TransmitterSessionRequest\|transmitter request]] may gain new optional fields, which older clients simply do not send.		The game protocol version is a single integer sent in the handshake. Any incompatible change increments it. Within a version, the TLV-encoded [[SimTX API v24/Packets/TransmitterSessionRequest\|transmitter request]] may gain new optional fields, which older clients simply do not send.

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

	== Terms of use ==		== 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 <code>clientName</code> during [[SimTX API/Device login\|device login]], and do not use the API to disrupt other users.		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 <code>clientName</code> during [[SimTX API v24/Device login\|device login]], and do not use the API to disrupt other users.

	{{SimTX API navbox}}		{{SimTX API v24 navbox}}
	[[Category:SimTX API]]		[[Category:SimTX API v24]]