Getting started

One command: create-0gkit-app

The fastest path from zero to a running 0G app — pick a template, get a runnable project with .env.example, git init, and dependencies installed.

npm create 0gkit-app@latest my-app
cd my-app
0g dev          # in another terminal — starts the local devnet
npm run dev

Works with npm, pnpm, yarn, and bun. See the create-0gkit-app reference for flags, template descriptions, and troubleshooting.

Install the packages directly

0gkit packages are published independently under the @foundryprotocol/0gkit-* scope at version 0.1.0. Install only what you need. Every primitive depends on @foundryprotocol/0gkit-core and viem.

# Core + a primitive (storage shown):
npm install @foundryprotocol/0gkit-core @foundryprotocol/0gkit-storage viem

# Storage uploads also need the optional Node-only 0G SDK peers:
npm install @0gfoundation/0g-storage-ts-sdk ethers

Prefer the CLI? You do not have to install anything:

npx 0g doctor

Requirements: Node >=20.10. viem ^2.21 is a peer dependency of every primitive. @0gfoundation/0g-storage-ts-sdk, @0gfoundation/0g-compute-ts-sdk, and ethers are optional peers — install them only for live storage uploads / compute inference. (See Troubleshooting for the exact peer matrix.)

A 60-second end-to-end example

Upload bytes to 0G Storage and read them back. This is a Node script — storage uploads need a funded signer and the Node-only SDK peers.

import { Storage } from "@foundryprotocol/0gkit-storage";

const storage = new Storage({
  network: "galileo", // testnet — no real funds needed
  privateKey: process.env.ZEROG_PRIVATE_KEY,
});

// upload returns { root, tx, raw }
const { root, tx } = await storage.upload(new TextEncoder().encode("hello 0G"));
console.log("stored at root:", root);
console.log("funding tx:", tx.txHash, `(${tx.latencyMs} ms)`);

// download by root → Uint8Array
const bytes = await storage.download(root);
console.log("read back:", new TextDecoder().decode(bytes)); // "hello 0G"

Or do the same thing without writing any code, using the CLI:

echo "hello 0G" > hello.txt
export ZEROG_NETWORK=galileo
export ZEROG_PRIVATE_KEY=0x...                       # funded testnet key
ROOT=$(npx 0g storage put hello.txt --json | jq -r .root)
npx 0g storage get "$ROOT" out.txt
cat out.txt

Environment & keys

Every entrypoint reads the same environment variables. Flags always override env; env overrides the preset default.

Keys fund real transactions. Use a testnet key on galileo while developing — you never need real funds there. See Troubleshooting → key handling.

Supported networks

These are the network presets from @foundryprotocol/0gkit-core (networks.ts). getNetwork(name) returns the NetworkPreset.

aristotle and local are fully resolved. galileo is the default everywhere (testnet-first). A preset with no rpcUrl/chainId makes createClient throw a ConfigError — pass { rpcUrl, chainId } explicitly to target a custom network.

Where to go next

• Concepts — the shared Receipt, the error taxonomy, the client factory, the escape hatch.
• Packages — full API reference and examples for all 9 packages.