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 currently plan:

• Profile creation, Character and Starbase Player registration, and first faction enrollment;
• Fleet movement, docking, completed-subwarp settlement, early stopping, wallet ship import, empty Fleet creation, and ship assembly into a Docked Fleet;
• Fleet cargo transfers and wallet cargo deposits and withdrawals;
• Fleet mining start/stop and Crafting Process start/completion/cancellation;
• combat stimulants, singleton Fleet/Starbase attacks, and Loot retrieval;
• Local Market orders, cancellation/filled-escrow withdrawal, and directional Faction Market trades;
• Claim Stake placement, building changes/finalization/cancellation, rent top-up, deconstruction, and Fleet-transfer start/recovery;
• full-balance Loyalty ATLAS claims.

The separate planning entry provides signer-free simulatePlan and explicit executePlan, with confirmation and reconciliation. Not every generated instruction has a planner: standalone warp arrival settlement, for example, is unsupported. 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

Completely new to the game? The game, explained simply introduces the player, galaxy, Fleets, economy, and progression without assuming any Star Atlas or blockchain knowledge.

Your first read gets live data on your screen in about five minutes. If you already understand the game and want the SDK’s design, continue with how Atlas Kit reads the game.