Onboarding guide

Welcome! This guide walks you through connecting to the Wingbits real-time flight data stream, step by step. You do not need to be a developer to get the first flights showing up on your screen — if you can copy and paste a few commands, you're good. The whole thing takes about 10 minutes.

Throughout this guide, replace <CUSTOMER> with your company name wherever you see it (for example, acme). We'll send you a file named prod-<CUSTOMER>-trial.creds — that file is your key to the stream.

---

What you'll be connecting to

Wingbits delivers live aircraft positions (and more) over a system called NATS. Think of NATS like a radio: we broadcast flight updates on different "channels" (called subjects), and you tune in to the ones you care about. It's fast, lightweight, and there are ready-made libraries for almost every programming language — but you can also just listen in from your terminal, which is what we'll do first.

Two things you need:

1. The NATS command-line tool (nats) — free, we'll install it below.

2. Your credentials file (prod-<CUSTOMER>-trial.creds) — we send this to you by email. Keep it private; it's like a password.

Don't have credentials yet? If you're interested in trialing our NATS integration but don't yet have a credentials file, email us at [e-mail] and we'll get you set up.

---

Step 1 — Install the NATS tool

Pick your operating system.

macOS (using Homebrew):

brew install nats-io/nats-tools/nats

Windows (using Scoop):

scoop install nats

Linux (or anything else):

curl -sf https://binaries.nats.dev/nats-io/natscli/nats@latest | sh

Check it worked by running:

nats --version

If you see a version number (e.g. 0.1.x), you're ready. If it says "command not found", the install didn't complete — see Troubleshooting.

---

Step 2 — Save your credentials file

We send you your credentials as a file called prod-<CUSTOMER>-trial.creds. Save it somewhere you can find it — your Downloads folder is fine. Open a terminal in that same folder so the next commands can find the file.

What do credentials actually look like? This is the #1 source of confusion, so check now that you really have them. A valid creds file is plain text, about 13 lines, and contains two long codes between labeled markers:

• A JWT that starts with eyJ... and is several hundred characters long (around 700+), sitting between -----BEGIN NATS USER JWT----- and ------END NATS USER JWT------.

• A seed that starts with SU... and is 58 characters long, sitting between -----BEGIN USER NKEY SEED----- and ------END USER NKEY SEED------.

If what you received has no eyJ... block and no SU... block, you don't actually have credentials yet — email [e-mail] before going further.

Received your credentials as text instead of a file? Sometimes the credentials arrive pasted into a document or email body rather than as an attachment. They'll look like a block starting with -----BEGIN NATS USER JWT----- and ending with ------END USER NKEY SEED------. If so, you need to save that block as a file yourself:

1. Copy the entire block (from the first -----BEGIN to the last -----).

2. Open a plain-text editor (TextEdit in plain text mode, Notepad, VS Code).

3. Paste it in and save the file as prod-<CUSTOMER>-trial.creds.

   • macOS shortcut: copy the block, then run pbpaste > ~/Downloads/prod-<CUSTOMER>-trial.creds in your terminal.

Not sure how to "open a terminal in a folder"?

• macOS: right-click the folder → New Terminal at Folder.

• Windows: open the folder, type cmd in the address bar, press Enter.

Confirm the file is really there before continuing. In your terminal, run:

ls prod-<CUSTOMER>-trial.creds

If it prints the filename back, you're good. If it says No such file or directory, the file isn't in this folder — find where you saved it, or re-save it here. (Tip: on macOS you can avoid folder confusion entirely by using the file's full path in the next step — type --creds " and then drag the file from Finder into the terminal to paste its full path.)

---

Step 3 — Connect

In the same terminal window from Step 2, paste the command below and press Enter. You only need to run it once — it saves a "context" (a saved connection) called prod-<CUSTOMER>-trial so you don't have to retype the server and credentials every time.

Copy this as a single line (don't break it across multiple lines):

nats context add prod-<CUSTOMER>-trial --server "nats://nats-cluster.wingbits.com:4222" --creds "prod-<CUSTOMER>-trial.creds" --select

Why one line? If you split a command across multiple lines using \, the backslash must be the very last character on the line — a single stray space after it will break the whole command (you'll see command not found errors). Pasting it as one line avoids this entirely.

The --select at the end makes this your active connection. If the command runs with no error and returns you to a normal prompt, it worked.

---

Step 4 — Test your connection

Let's make sure everything is wired up correctly:

nats context info

You should see your server (nats-cluster.wingbits.com) and your credentials file listed. Now try actually pulling in some flights:

nats sub "flights.5s.>"

Within a few seconds you should start seeing flight updates streaming down your screen. That's it — you're connected to live aircraft data. Press Ctrl + C to stop.

If nothing shows up, jump to Troubleshooting.

---

Step 5 — Choose the right stream for you

We broadcast the same flight data at three different speeds. Pick the one that matches how "live" you need it to be. Faster = more data to handle.

Channel (subject)	How often each aircraft updates	Best for
flights.full.>	Every update, up to ~2× per second	Live maps, anything needing the freshest position
flights.5s.>	Once every 5 seconds	Most use cases — a great default
flights.dd.>	Once every 10 seconds	Dashboards, analytics, lower bandwidth

The > at the end is a wildcard meaning "every aircraft you're allowed to see." So flights.5s.> = all your aircraft, updated every 5 seconds.

To listen to a channel, just sub (subscribe) to it:

nats sub "flights.5s.>"      # all aircraft, every 5 seconds
nats sub "flights.full.>"    # all aircraft, as fast as it comes

Following one specific aircraft

Every aircraft has a unique ID called an ICAO hex (a 6-character code like 7820d9). To follow just one aircraft, put its hex at the end:

nats sub "flights.full.7820d9"

Following a list of aircraft (a fleet)

If you only need certain aircraft, we grant you access to that exact list and you subscribe to each one. You can listen to several at once:

nats sub "flights.full.7820d9" "flights.full.a1b2c3" "flights.full.c0ffee"

Just tell us which aircraft (or geographic area) you care about, and we'll set your access up to match.

---

Optional add-ons

These are extra data feeds available on request. Once enabled for your account, you subscribe to them the same way:

Add-on	Subject	What it is
ACAS / TCAS	flights.acas	Collision-avoidance "resolution advisory" events
ADS-C	flights.adsc	Oceanic / satellite-based positions (aircraft over open ocean)

nats sub "flights.acas"
nats sub "flights.adsc"

---

Understanding the data

Each message is a small JSON record describing one aircraft at one moment. To keep messages tiny and fast, the field names are short codes. Here's what they mean:

Code	Field	Description
h	ICAO Hex	The aircraft's unique ID
f	Flight	Flight number / callsign
la	Latitude	Aircraft latitude
lo	Longitude	Aircraft longitude
ab	Barometric Altitude	Altitude from barometric pressure
ag	Geometric Altitude	Altitude from GPS
gs	Ground Speed	Speed over the ground
tr	Track	Direction of travel (track angle)
th	True Heading	Heading relative to true north
mh	Magnetic Heading	Heading relative to magnetic north
og	On Ground	Whether the aircraft is on the ground
sq	Squawk	Transponder squawk code
c	Category	Aircraft category
t	Type	Message type
v	Version	ADS-B version
a	Alert	Alert status
em	Emergency	Emergency status
spi	SPI	Special Position Indicator
br	Baro Rate	Rate of climb/descent (barometric)
gr	Geometric Rate	Rate of climb/descent (GPS)
i	IAS	Indicated air speed
m	Mach	Mach number
ct	Calculated Track	Track calculated from position
oat	Outside Air Temperature	Air temperature outside the aircraft
tat	Total Air Temperature	Total air temperature
wd	Wind Direction	Direction the wind is coming from
ws	Wind Speed	Wind speed
ro	Roll	Roll angle
trr	Track Rate	Rate of change in track
rs	RSSI	Received signal strength
sn	Seen	When the message was last seen
sp	Seen Position	When the position was last seen
rc	Radius of Containment	Position accuracy measure
rdi	Receiver Direction	Direction from receiver to aircraft
rds	Receiver Distance	Distance from receiver to aircraft
nh	Nav Heading	Selected heading
nq	Nav QNH	Altimeter setting
naf	Nav Altitude FMS	Altitude from the Flight Management System
nam	Nav Altitude MCP	Altitude set on the Mode Control Panel
n	Navigation Integrity Category	NIC value
nb	NIC Baro	NIC value from barometric source
np	Navigation Accuracy for Position	NAC-p value
nv	Navigation Accuracy for Velocity	NAC-v value
s	SIL	Source Integrity Level
st	SIL Type	Type of SIL
sda	SDA	System Design Assurance level
gv	Geometric Vertical Accuracy	Accuracy of geometric altitude
gpb	GPS OK Before	GPS was recently OK

Not every field appears in every message — aircraft only report what their equipment supports.

---

Using the data in your own software

The terminal is great for testing, but you'll probably want to pull this into your own application. NATS has official libraries for most languages (Python, JavaScript, Go, Java, C#, Rust, and more). They all use the same server address, credentials file, and subjects you used above.

Python example (pip install nats-py):

import asyncio, json
import nats

async def main():
    nc = await nats.connect(
        "nats://nats-cluster.wingbits.com:4222",
        user_credentials="prod-<CUSTOMER>-trial.creds",
    )

    async def on_message(msg):
        data = json.loads(msg.data)
        print(f"{data.get('h')}  lat={data.get('la')}  lon={data.get('lo')}")

    await nc.subscribe("flights.5s.>", cb=on_message)
    await asyncio.Event().wait()  # keep listening

asyncio.run(main())

Node.js example (npm install nats):

import { connect, credsAuthenticator } from "nats";
import { readFileSync } from "fs";

const nc = await connect({
  servers: "nats://nats-cluster.wingbits.com:4222",
  authenticator: credsAuthenticator(readFileSync("prod-<CUSTOMER>-trial.creds")),
});

const sub = nc.subscribe("flights.5s.>");
for await (const msg of sub) {
  const data = JSON.parse(msg.string());
  console.log(data.h, data.la, data.lo);
}

---

Troubleshooting

nats: command not found The tool didn't install. Re-run the install step for your OS, then close and reopen your terminal.

no such file or directory mentioning your .creds file Your terminal isn't in the same folder as the credentials file. Either move the .creds file into the folder your terminal is in, or use the full path to it, e.g. --creds "/Users/you/Downloads/prod-<CUSTOMER>-trial.creds".

nats: error: nats: Authorization Violation The credentials aren't being accepted, or you're subscribing to a channel you don't have access to yet. Double-check you're using the exact .creds file we sent, and that you're subscribing to a subject you've been granted. If it persists, contact us — we may need to adjust your access.

It connects, but no flights appear

• Try flights.full.> instead of flights.5s.> (more frequent updates).

• Confirm with us which subjects your account is allowed to see — trial accounts are sometimes scoped to a specific region or aircraft list.

connection refused / timeout Your network may be blocking outbound port 4222. Check with your IT team, or try from a different network to confirm.

---

Need help?

Reply to your onboarding email or reach out to your Wingbits contact. Tell us:

• What command you ran

• The exact message you got back

and we'll get you sorted quickly.

Happy tracking! ✈️

— The Wingbits Team