> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genlabs.co/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> Typed TypeScript client for the Grid JSON-RPC API: connect, query, sign, and submit activations from Node or the browser.

The TypeScript SDK is the typed client for the Grid in Node and the browser: RPC access, activation signing and submission, views, simulation, and trace polling. This page covers what to install, how to configure a client, and a worked example for the most common job: sending a transfer.

For the full API surface, see the [generated API reference](/reference/sdk/typescript/overview).

<Note>
  **Pre-release.** The SDK surface may still change.
</Note>

## Package layout

The SDK ships as a single package, `@gen/client-sdk`, with a browser-safe root entrypoint and purpose-specific subpaths:

| Entrypoint                     | What it is                                                                                                                                               |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@gen/client-sdk`              | Everything most apps need: `GenClient`, `GenSigner`, payload builders, account and faucet helpers, the JSON-RPC client and types, and structured errors. |
| `@gen/client-sdk/node`         | Node-only helpers that read contract artifacts from disk (`loadCodeArtifactsFromDisk(...)`).                                                             |
| `@gen/client-sdk/gvm-types`    | GVM type definitions (`AmountInSubunits`, `GvmComponentId`, ...) used to build typed payloads.                                                           |
| `@gen/client-sdk/system-types` | Generated types for the system contract schemas.                                                                                                         |

## Install

The package is not yet published to npm. Get it from the [gen-framework-preview](https://github.com/gen-bc/gen-framework-preview) repository: build the SDK in `client-and-test-utils/client-sdk-ts` with `yarn build`, then add `packages/client-sdk` to your app as a `file:` or workspace dependency.

## Environment

* **ESM-only.** The package declares `"type": "module"` and its exports map only offers `import` entrypoints — there is no CommonJS build. From CJS code, use dynamic `import()`.
* **Node ≥ 20.** The HTTP transport uses the global `fetch`.
* **Evergreen browsers.** The SDK runs in the browser as well as Node; the root entrypoint is browser-safe.
* **BigInt throughout.** Amounts and block numbers are `bigint`, so compilation targets must be ES2020 or later.

## Configure a client

`GenClient` owns RPC access, view execution, activation submission, and waiting. Most apps construct one and reuse it.

<Note>
  **DevNet access.** DevNet requires a bearer token. Ask your Gen Labs contact for one and substitute it for `<your-jwt>` in the examples below.
</Note>

```ts theme={null}
import {GenClient} from "@gen/client-sdk";

const client = GenClient.newHttp("https://devnet.genlabs.co/rpc/", {
  headers: {Authorization: "Bearer <your-jwt>"},
});
```

Against a local validator, drop the headers: `GenClient.newHttp("http://127.0.0.1:30001")`. The options object also accepts `pollIntervalMs` and `maxAttempts` for polling, `requestTimeoutMs` and a custom `fetch` for transport, and activation header overrides (`chainId`, `version`, `payloadEncodingVersion`).

## First call

Probe the validator to confirm connectivity:

```ts theme={null}
const version = await client.rpc().getVersion({});
console.log(`validator ${version.release_version}, rpc protocol ${version.rpc_protocol_version}`);
```

That single call rules out the most common setup failures: wrong endpoint, network unreachable, missing bearer token.

## Send a transfer

The quickest way to move the genesis token is the faucet flow: create an account, fund it, check the balance. Both steps are one-call conveniences on `GenClient`.

```ts theme={null}
import {GenClient, GenSigner} from "@gen/client-sdk";

const client = GenClient.newHttp("http://127.0.0.1:30001");

// A fresh account for this walkthrough.
const recipient = GenSigner.generate();
const account = recipient.account();

// Create the account on-chain, then transfer 1 token to it from the faucet.
await client.wait(await client.createAccount(account));
const outcome = await client.wait(
  await client.faucet(account, 1_000_000_000_000_000_000n),
);
console.log("status:", outcome.terminalInfo.status); // "success"

const balance = await client.rpc().getBalance({account});
console.log("balance:", balance); // "1000000000000000000"
```

A few notes:

* Amounts are `bigint` subunits, the token's smallest unit. The genesis token uses 18 decimals, so the literal above is one token.
* `createAccount(...)` and `faucet(...)` return as soon as the activation is accepted. `wait(...)` polls the activation and all its continuations to a terminal state and resolves the result into a `TraceOutcome`.
* Calling your own contract is the same shape without the convenience wrapper: build an `ActivationPayload` targeting your component and pass it to `client.signAndSubmitActivationAndWait(signer, payload)` with your own signer — see [`GenClient`](/reference/sdk/typescript/index/classes/GenClient) in the API reference.

## Loading keys

`GenSigner` accepts the canonical 32-byte Ed25519 secret seed via `fromPrivateKeyBytes(...)` / `fromPrivateKeyHex(...)` — not the expanded 64-byte private key, a clamped scalar, or a PKCS#8 wrapper. Raw key imports self-validate by signing and verifying a fixed message unless you opt out with `{skipValidation: true}`.

Mnemonics are supported through `GenSigner.fromMnemonic(...)` and `GenSigner.fromMnemonicWithPath(...)`; the default derivation path is `m/44'/218'/0'/0/0`. To bridge from a CLI wallet, use `gen wallet export` (see [`gen wallet`](/reference/cli/wallet)) and feed the result to `fromPrivateKeyBytes`.

For browser custody integrations, every submission method accepts any `EddsaSigner` implementation — an object exposing `publicKey()` and `signBytes(...)` — so browser wallets and external custody providers can sign without handing raw key material to the SDK.

Never hard-code a private key in source. The example above generates a throwaway key only for the walkthrough.

## Errors

The SDK throws structured error classes, all extending `SdkError`. The ones you are likely to handle in production:

| Class                    | When it fires                                                                                          |
| ------------------------ | ------------------------------------------------------------------------------------------------------ |
| `TransportError`         | Network error or invalid URL reaching the validator. Retry with backoff.                               |
| `ServerError`            | Validator returned a JSON-RPC error. Do not retry without inspecting `code`.                           |
| `ActivationPollingError` | Polling for activation status exhausted `maxAttempts`. Re-check via `client.rpc().getActivation(...)`. |
| `ActivationResultError`  | The activation reached a non-success result. The error carries the failure details.                    |
| `SdkValidationError`     | Invalid input (amount range, key format) caught before anything is sent.                               |

See [the generated API reference](/reference/sdk/typescript/index/classes/SdkError) for the full hierarchy.

## Next steps

* [JSON-RPC reference](/reference/rpc/overview): every wire-level method the SDK speaks.
* [Rust SDK](/reference/sdk/rust): the canonical client; the TypeScript SDK mirrors its structure.
* [Send your first transfer (CLI)](/quickstart/index): the same flow at the command line, useful for sanity-checking your setup.