# Setting up your RPC
Documentation: next (source: develop).

Install the preview: `pnpm add @aephia/atlas-kit@next`. These docs follow develop and may include changes not yet published to npm.

> What an RPC endpoint is, which one to use for the z.ink test realm, and when to bring your own.

Markdown source of https://develop.atlas-kit-docs.pages.dev/start-here/rpc/ — see https://develop.atlas-kit-docs.pages.dev/ai/ for the full machine-readable surface.

The SDK does not talk to the blockchain directly. It asks an **RPC endpoint** —
a server that keeps a copy of the chain and answers questions about it. You
supply that endpoint; the SDK never picks one for you.

```ts
import { createSolanaRpc } from '@solana/kit';

const rpc = createSolanaRpc('https://testnet-rpc.z.ink');
```

## The public endpoint

`https://testnet-rpc.z.ink` is the public endpoint for the z.ink test realm. It
is what the examples use, and it is enough to get started.

It is shared infrastructure. Expect rate limiting under load, and do not build
anything you care about on top of it.

## Set the endpoint for this site

Every runnable example on this site uses the endpoint set here. It is stored in
your browser and nowhere else.

Checking verifies two things: that the endpoint answers, and that it is actually
the test realm. A working endpoint for the wrong network is the failure that
wastes the most time, so it is called out explicitly rather than left to fail
later.

## When to bring your own

Move to your own endpoint when you are polling on a schedule, serving other
people, or seeing rate-limit errors. A provider with z.ink support, or your own
node, both work — the SDK only needs something that speaks the Solana JSON-RPC
protocol for this network.

:::caution[Mainnet endpoints will not work]
SAGE C4 runs on z.ink, not Solana mainnet. Pointing the SDK at a mainnet RPC
gets you a working connection to the wrong chain: the Game account simply is not
there, and reads fail in confusing ways rather than saying "wrong network".

If reads fail immediately and consistently, check the endpoint first.
:::

## Using it from a browser

Reads work directly from browser code — `https://testnet-rpc.z.ink` sends
permissive CORS headers, so no proxy is needed.

This is worth knowing because it shapes what you can build. A dashboard that
reads fleet state needs no backend at all: the browser talks to the RPC, and the
SDK decodes the response. That read-only flow has no signer or key to protect.
If you add `executePlan`, the caller-provided signer and explicit write RPC
become security boundaries and execution can incur fees or move assets.

If you use a different provider, check its CORS policy before assuming the same.

## Freshness

Every read accepts a maximum age. The SDK caches decoded accounts, and a read
inside that window is served from cache rather than the network.

```ts
const sage = createSageClient({
  cluster: 'zink-ptr',
  rpc,
  defaultMaxAgeMs: 10_000,
});
```

That default applies to every read unless a specific call overrides it. Raising
it cuts RPC traffic; lowering it costs requests. [How Atlas Kit reads the
game](/start-here/how-it-thinks/) covers the caching model properly.

:::game[Why staleness is usually fine]
Most SAGE state changes on the scale of minutes or hours, not milliseconds. A
mining operation runs for a while; a fleet in transit arrives at a known time;
a starbase upgrade takes real time to complete.

Reading fleet state that is ten seconds old is almost always correct. The
exceptions are the ones you would expect — anything racing another player, like
a market order.
:::