What is this?

Star Atlas is a space game. SAGE is the part of it where fleets fly between star systems, mine asteroids, craft components, and trade at starbases. All of that lives on a blockchain, which means the game’s state is public: anyone can read it.

Reading it is harder than it sounds. The data on chain is raw bytes, laid out in a format the game’s program understands and nothing else does. This SDK does the translating.

const character = await sage.characters.forProfile(profileAddress);
const fleets = await character.fleets.all();

fleets[0].name; // "Ravager" — a string, not a padded byte array

Who this is for

Anyone building something that needs to know what is happening in SAGE: a fleet dashboard, a mining calculator, a market tracker, a Discord bot.

You do not need to know Solana. The pages ahead explain the handful of concepts you actually need, when you need them. If you do know Solana, the SDK will feel familiar and you can skip most of the explanation.

The non-custodial boundary

Contexts hold no signer or key material, signers are supplied explicitly to each write call, and Plans stay inspectable before authorization. Nothing signs, submits, or retries implicitly. Execution can incur fees or move assets, so treat an unknown outcome as possibly submitted until signer and chain history prove otherwise.

Read-only capability entries remain read-only. Curated action entries expose the planners currently available for Fleet movement, Fleet cargo transfer, and Starbase Player registration; not every generated instruction has a planner. The raw bindings escape hatch exposes the pinned generated clients without an SDK-level safety guarantee.

Which game, exactly

SAGE C4 running on the z.ink public test realm — a separate network from Solana mainnet, where the current version of the game runs.

The most common wrong turn

The @staratlas/sage and @staratlas/data-source packages on npm target the previous version of the game. They are not compatible with SAGE C4, and no amount of adapting will make them work.

AI assistants suggest them constantly, because they appear throughout older training data. If you find yourself installing either one, stop and come back here. See For AI assistants if you are working with one.

Why “C4”?

SAGE has been rebuilt several times as the game has evolved. C4 is the current generation, and it runs on its own program with its own account layouts. Data and tooling from earlier generations do not carry over — the accounts are shaped differently, so old decoders read garbage rather than failing cleanly.

Where to go next

Your first read gets live data on your screen in about five minutes. If you would rather understand the shape of things first, how the SDK thinks is the short version of the design.