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

# Server entry point

> Typed API clients, base URL rules, and keeping credentials off the client.

`@gol/sdk/server` holds everything that carries a project credential: the API clients, the polling helpers, and webhook verification. Import it from your server only. Its requests send your API key or your developer session token, so bundling it into a web page or a mobile app publishes that credential.

The root [`@gol/sdk`](/sdk/browser) entry point is the one for browser code. The split is deliberate: a reader can tell from the import path alone whether a module can touch a secret.

## Create a client

`GolApiClient` authenticates with a project API key.

```ts theme={null}
import { GolApiClient } from "@gol/sdk/server";

export const gol = new GolApiClient({
  baseUrl: "https://api.gol.network",
  apiKey: process.env.GOL_API_KEY!,
});

export const projectId = process.env.GOL_PROJECT_ID!;

const identity = await gol.whoami();
console.log(identity.project.id, identity.apiKey.scopes, identity.environment);
```

Read the key from a server-side secret store or environment variable. Never from a request parameter, a repository, or a value your browser sends to your server.

`GolManagementClient` authenticates with a developer session token and covers the console management routes: projects, API keys, audit history, and the session lifecycle.

```ts theme={null}
import { GolManagementClient } from "@gol/sdk/server";

export const console = new GolManagementClient({
  baseUrl: "https://api.gol.network",
  sessionToken: process.env.GOL_CONSOLE_SESSION!,
});

const identity = await console.getIdentity();
```

Session tokens and API keys are not interchangeable. An API key identifies a project; a session token identifies a signed-in developer. Keep the session token in an HTTP-only cookie so client JavaScript cannot read it, and call `revokeSession` on sign-out.

<Note>
  `startEmailChallenge`, `verifyEmailChallenge`, `createGoogleSession`, `renewSession`, and `revokeSession` exist for a server that implements developer sign-in itself. GOL's own console at [console.gol.network](https://console.gol.network) is a first-party client, not a dependency of yours: build your own sign-in and UI with your own product's conventions. Google sign-in is disabled on the hosted console pending provider setup and a verified round trip.
</Note>

## Base URL rules

The client validates its configuration at construction, so a mistake fails immediately instead of at the first request.

| Rule               | Behavior                                                                                     |
| ------------------ | -------------------------------------------------------------------------------------------- |
| Scheme             | Must be `https`, except `http` on `localhost`, `127.0.0.1`, or `[::1]` for local development |
| Credentials        | The URL may not contain a username or password                                               |
| Query and fragment | The URL may not contain `?` or `#`                                                           |
| Trailing slash     | Removed, so `https://api.gol.network/` and `https://api.gol.network` behave the same         |
| API key format     | Must match `gol_test_...` or `gol_live_...` followed by base64url characters                 |

Each violation throws `GolTransportError` from the constructor.

## Pass your own fetch

`fetch` is injectable, which is what makes the client testable without a network.

```ts theme={null}
import { GolApiClient } from "@gol/sdk/server";

const calls: string[] = [];
const recordingFetch: typeof fetch = async (input, init) => {
  calls.push(`${init?.method ?? "GET"} ${String(input)}`);
  return new Response(JSON.stringify({ project: { id: "stub" } }), {
    status: 200,
    headers: { "content-type": "application/json" },
  });
};

const gol = new GolApiClient({
  baseUrl: "https://api.gol.network",
  apiKey: "gol_test_stub",
  fetch: recordingFetch,
});
```

Every request the client makes is a `GET`, `POST`, or `DELETE` with `Accept: application/json`, `cache: no-store`, and a bearer `Authorization` header when a credential is present.

## Read configuration at runtime

`getGasConfiguration` returns the deployed core, relayer, attester, recipient, asset, and limits for your project and environment. Read it at startup and pass the values into any request, rather than hard-coding an address from the docs.

```ts theme={null}
import { GolApiClient } from "@gol/sdk/server";
import type { Address } from "viem";

declare const gol: GolApiClient;
declare const projectId: string;

const config = await gol.getGasConfiguration(projectId);

const core = config.core as Address;
const perActionWei = config.limits.recommendedPerActionWei;
const totalWei = (BigInt(config.limits.recommendedPerActionWei) * 20n).toString();
```

[Current availability](/availability) lists the same values for the supported Base Sepolia setup, with the exact network and versions they belong to. A value in the docs is a record of a deployment; a value from the API is the deployment as it is right now.

## Scope the key

The key's scopes decide which methods succeed. `GolApiClient` does not pre-check them, so a missing scope surfaces as a `GolApiError` with code `authorization_denied`. The scopes each method needs are listed in [create a project and API key](/get-started/test-project).

## Handle errors

Every client method rejects with `GolApiError` when the API returns a non-2xx status, and with `GolTransportError` when the request cannot be made or the response is not JSON. See [errors](/sdk/errors) for the shape and the retry rules.

```ts theme={null}
import { GolApiError, GolTransportError } from "@gol/sdk/server";
import type { GolApiClient } from "@gol/sdk/server";

declare const gol: GolApiClient;
declare const projectId: string;

try {
  await gol.getGasPolicy(projectId, `0x${"00".repeat(32)}`);
} catch (error) {
  if (error instanceof GolApiError) {
    console.error(error.status, error.code, error.correlationId);
  } else if (error instanceof GolTransportError) {
    console.error("the API could not be reached", error.cause);
  } else {
    throw error;
  }
}
```

`correlationId` is the value to quote in a bug report. Do not log the API key or the full `Authorization` header alongside it.

## Polling helpers

Six helpers wrap a confirm-or-retry loop. Each polls until the API answers, then returns: `waitForGasPolicyConfirmation`, `waitForGasPolicySafetyAction`, `waitForGasPolicyRevocation`, `waitForGasExecution`, `waitForEip7702Setup` (until `confirmed` or `failed`), and `waitForChildMandate` (until the child leaves `pending`).

```ts theme={null}
import {
  waitForGasExecution,
  waitForGasPolicyConfirmation,
  waitForGasPolicySafetyAction,
} from "@gol/sdk/server";
import type { GolApiClient } from "@gol/sdk/server";
import type { Address } from "viem";

declare const gol: GolApiClient;
declare const projectId: string;
declare const draftId: string;
declare const transactionHash: `0x${string}`;
declare const gasPolicyId: Address;
declare const executionId: string;

const options = { intervalMs: 20_000, timeoutMs: 90 * 60_000 };

const policy = await waitForGasPolicyConfirmation(
  gol,
  projectId,
  draftId,
  transactionHash,
  options,
);
const paused = await waitForGasPolicySafetyAction(
  gol,
  projectId,
  gasPolicyId,
  { action: "pause", transactionHash },
  options,
);
const settled = await waitForGasExecution(gol, projectId, executionId, {
  intervalMs: 20_000,
  timeoutMs: 120 * 60_000,
});
```

Each helper also accepts a `signal`, so you can stop waiting when a request is aborted. A timeout throws `GolTransportError`. The underlying `confirmGasPolicy`, `confirmGasPolicySafetyAction`, `confirmGasPolicyRevocation`, `getGasExecution`, `getEip7702Setup`, and `listChildMandates` methods are public if you would rather own the loop, and `waitForGasExecution` accepts `until` to change the state you are waiting for.

## Webhook verification

`verifyWebhook` is in this entry point because it needs the Node.js `crypto` module and your endpoint secret. See [webhooks](/sdk/webhooks).