Server entry point

@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 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.

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.

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.

startEmailChallenge, verifyEmailChallenge, createGoogleSession, renewSession, and revokeSession exist for a server that implements developer sign-in itself. GOL’s own console at 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.

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.

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.

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 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.

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 for the shape and the retry rules.

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).

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.

Get started

Guides

Reference

Server entry point

Create a client

Base URL rules

Pass your own fetch

Read configuration at runtime

Scope the key

Handle errors

Polling helpers

Webhook verification

​Create a client

​Base URL rules

​Pass your own fetch

​Read configuration at runtime

​Scope the key

​Handle errors

​Polling helpers

​Webhook verification

Create a client

Base URL rules

Pass your own fetch

Read configuration at runtime

Scope the key

Handle errors

Polling helpers

Webhook verification