API clients

@gol/sdk/server exposes two typed clients. GolApiClient authenticates with a project API key and covers the project routes. GolManagementClient authenticates with a developer session token and covers the console management and session routes. Both inherit the same read-only project methods, so a project listing looks identical from either. Every method is a thin, typed wrapper over one documented route. There is no hidden behavior and no chain transaction behind a method: where a method changes authority, the authority is an owner signature you obtain separately. See owner signing.

Create a client

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!;

The constructor validates its arguments before any request, so a malformed key or a plain-HTTP base URL fails at startup rather than on the first call. See server entry point for the exact rules.

`GolApiClient` methods

Grouped by what they do. Scopes come from create a project and API key.

Identity and configuration

Method	Scope	Returns
`whoami()`	`project:read`	The project, environment, and scopes this key carries
`getGasConfiguration(projectId)`	`project:read`	The deployed core and router, relayer modes, attester, asset, reviewed account configurations, EIP-7702 delegate, tree limits, and gas limits
`getAccountStatus(projectId, account)`	`accounts:read`	The detected family, account kind and delegation, nonces, and whether the core is installed
`prepareEip7702Setup(projectId, account)`	`mandates:write`	The EIP-7702 authorization and initialization for an EOA to sign
`submitEip7702Setup(projectId, account, input)`	`mandates:write`	A GOL-sponsored setup, within the daily limit
`getEip7702Setup(projectId, account, setupId)`	`accounts:read`	One setup’s state and transaction

getAccountStatus is the first call for any account. A family of null means the account is not one of the supported configurations, and the flow stops there.

Owner gas policies

Method	Scope	Returns
`prepareGasPolicy(projectId, input)`	`mandates:write`	A compiled approval for the owner to sign. Creates no authority
`confirmGasPolicy(projectId, draftId, transactionHash)`	`mandates:write`	The policy once finalized, or an `observing` status to retry
`prepareGasPolicySafetyAction(projectId, gasPolicyId, input)`	`mandates:write`	A prepared owner pause, resume, or revoke of the root or any child mandate
`confirmGasPolicySafetyAction(projectId, gasPolicyId, input)`	`mandates:write`	The policy once confirmed, or an observation to retry
`prepareGasPolicyRevocation(projectId, gasPolicyId, deadline?)`	`mandates:write`	Both owner revocation paths
`confirmGasPolicyRevocation(projectId, gasPolicyId, transactionHash)`	`mandates:write`	The policy once confirmed, or an observation to retry
`getGasPolicy(projectId, gasPolicyId)`	`mandates:read`	Current on-chain policy state
`listGasPolicies(projectId, options?)`	`mandates:read`	A page of policies
`prepareChildMandate(projectId, gasPolicyId, input)`	`mandates:write`	A compiled child mandate for the parent agent to sign. Creates no authority
`submitChildMandate(projectId, gasPolicyId, draftId, authorization)`	`mandates:write`	A GOL-sponsored child creation, within the daily limit
`confirmChildMandate(projectId, gasPolicyId, draftId, transactionHash)`	`mandates:write`	A child you created yourself, once confirmed, or an observation to retry
`listChildMandates(projectId, gasPolicyId)`	`mandates:read`	Every recorded mandate of the policy’s tree, with on-chain status

prepareGasPolicy returns a plain summary in review: recipients, caps, gas caps, which outcomes the owner pays gas for, expiry, and the GOL attester and reimbursement recipient. Show it to the owner as part of your own review screen before they sign. The confirm methods answer with a discriminated union, so the retry case is explicit rather than a null check.

import { GolApiClient } from "@gol/sdk/server";

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

const result = await gol.confirmGasPolicy(projectId, draftId, transactionHash);

if (result.status === "confirmed") {
  const { gasPolicyId, status } = result.policy;
} else {
  // result is a GasObservation: the approval is not at the selected head yet.
}

getGasPolicy reports unavailable when the on-chain state is unknown or conflicting, rather than guessing. Treat that as unresolved and retry later, not as revoked.

Actions

Method	Scope	Returns
`prepareGasExecution(projectId, actionId, input)`	`actions:submit`	The exact `GasActionAuthorization` payload and `maxChargeWei` for your agent to sign
`submitGasExecution(projectId, actionId, input)`	`actions:submit`	The execution, including the original one on an exact retry
`getGasExecution(projectId, executionId)`	`project:read`	One execution with its receipt, settlement, any claim receipt, and ledger
`submitDeveloperRelayerTransaction(projectId, executionId, rawSignedTransaction)`	`actions:submit`	Your developer relayer’s signed transaction for an `external_pending` execution
`listGasExecutions(projectId, options?)`	`project:read`	A page of executions, optionally filtered by state
`openGasExecutionDispute(projectId, executionId, reason)`	`mandates:write`	A dispute that freezes new submissions under the policy

See execution and observation for the action lifecycle and the idempotency rule.

Webhooks

Method	Scope	Returns
`createWebhookEndpoint(projectId, input)`	`webhooks:manage`	The endpoint and its one-time `secret`
`listWebhookEndpoints(projectId)`	`webhooks:manage`	Every endpoint on the project
`rotateWebhookSecret(projectId, endpointId)`	`webhooks:manage`	A new one-time `secret`
`setWebhookEndpointEnabled(projectId, endpointId, enabled)`	`webhooks:manage`	The updated endpoint
`deleteWebhookEndpoint(projectId, endpointId)`	`webhooks:manage`	A deletion acknowledgement
`sendWebhookTest(projectId, endpointId)`	`webhooks:manage`	The test event ID
`listWebhookDeliveries(projectId, endpointId, limit?)`	`webhooks:manage`	Recent delivery attempts

See webhooks.

`GolManagementClient` methods

Use this client for developer sign-in and for the management routes a console needs. It is not on the agent action path.

Method	Returns
`startEmailChallenge(email)`	A challenge to deliver by your own channel
`verifyEmailChallenge(challengeId, code)`	A session token
`createGoogleSession(input)`	A session for a Google ID token from your own server-side OAuth exchange
`renewSession()`	A refreshed session
`revokeSession()`	Nothing; the session is gone
`getIdentity()`	The signed-in developer and their projects
`listProjects()` / `createProject(input)`	The developer’s projects
`listApiKeys(projectId)` / `createApiKey(projectId, input)`	The project’s API keys
`rotateApiKey(projectId, apiKeyId, input)` / `revokeApiKey(projectId, apiKeyId)`	Key lifecycle
`listAuditEvents(projectId, limit?)`	Recent audit events, limit clamped to 1 to 100

Methods that need a session throw GolTransportError when the client has no sessionToken, so a misconfigured client fails before the request.

Keep the session token in an HTTP-only cookie and out of client JavaScript. A token in browser storage is readable by any script on the page, and it identifies a developer account rather than one project.

Read values, do not hard-code them

Addresses, limits, and asset identifiers belong in your configuration, read from the API. The values in current availability are a record of a deployment; getGasConfiguration is that deployment as it is now.

import { GolApiClient } from "@gol/sdk/server";
import type { Address } from "viem";

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

const config = await gol.getGasConfiguration(projectId);
const status = await gol.getAccountStatus(projectId, account);

if (status.family === null) {
  throw new Error("The account is not a supported configuration.");
}
if (!status.coreInstalled) {
  // Install the core through the owner path before preparing an approval.
}

Pagination

List methods take PageOptions and return a data array with a cursor. limit, cursor, and environment are all optional.

import { GolApiClient } from "@gol/sdk/server";

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

let cursor: string | undefined;
let total = 0;
do {
  const page = await gol.listGasExecutions(projectId, { limit: 100, cursor });
  total += page.data.length;
  cursor = page.nextCursor ?? undefined;
} while (cursor);

Transport behavior

Each request sends Accept: application/json, cache: no-store, and Authorization: Bearer <credential> when a credential is present. A 204 response is treated as an empty body, which is what revokeSession returns. Anything other than a 2xx becomes a GolApiError carrying the API’s own code, the HTTP status, and a correlationId. A transport failure, a non-JSON body, or an invalid baseUrl becomes a GolTransportError. See errors.

Get started

Guides

Reference

Create a client

`GolApiClient` methods

Identity and configuration

Owner gas policies

Actions

Webhooks

`GolManagementClient` methods

Read values, do not hard-code them

Transport behavior

​Create a client

​GolApiClient methods

​Identity and configuration

​Owner gas policies

​Actions

​Webhooks

​GolManagementClient methods

​Read values, do not hard-code them

​Pagination

​Transport behavior

Create a client

`GolApiClient` methods

Identity and configuration

Owner gas policies

Actions

Webhooks

`GolManagementClient` methods

Read values, do not hard-code them

Pagination

Transport behavior