Execution and observation

An action is the only thing in GOL that moves value. Your agent signs it, the API relays it, and the contract checks it against the owner’s signed policy before the transfer happens. Integrate hosted gas is the end-to-end walkthrough; this page is the SDK detail for the action itself.

Prepare, sign, submit

The API compiles the exact EIP-712 GasActionAuthorization payload, including maxChargeWei, the most network gas the action may be charged. signPreparedGasExecution recomputes the transfer from the prepared fields, refuses a charge above the ceiling you pass, has your agent sign, and returns the submission body. Your agent never needs ETH.

import { GolApiClient } from "@gol/sdk/server";
import { signPreparedGasExecution } from "@gol/sdk";
import type { AgentSigner } from "@gol/sdk";
import { randomBytes } from "node:crypto";
import type { Hex } from "viem";

declare const gol: GolApiClient;
declare const projectId: string;
declare const agentWallet: AgentSigner;
declare const mandateId: string;
declare const gasPolicyId: string;
declare const merchant: `0x${string}`;

// 32 random bytes, generated once per logical action and then reused.
const actionId = `0x${randomBytes(32).toString("hex")}` as Hex;

const input = {
  mandateId,
  gasPolicyId,
  recipient: merchant,
  amountBaseUnits: "250000",
  deadline: Math.floor(Date.now() / 1000) + 600,
};

const prepared = await gol.prepareGasExecution(projectId, actionId, input);
const body = await signPreparedGasExecution(agentWallet, prepared, {
  recipient: merchant,
  amountBaseUnits: 250_000n,
  maxChargeWei: 92_000_000_000_000n, // your ceiling for this action's gas
});
const execution = await gol.submitGasExecution(projectId, actionId, body);

The action ID is your idempotency key. It is also sent as the Idempotency-Key header, and the SDK validates that it is a 32-byte hex value before making the request, throwing GolTransportError otherwise.

Retries never move value twice

Store actionId and the agent signature before you submit, and reuse exactly those values on a retry. This is the rule that makes a timeout safe.

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

declare const gol: GolApiClient;
declare const projectId: string;
declare const actionId: Hex;
declare const input: {
  mandateId: string;
  gasPolicyId: string;
  recipient: `0x${string}`;
  amountBaseUnits: string;
  deadline: number;
};
declare const agentSignature: Hex;
declare const maxChargeWei: string;

// Same ID, same signature, same fields: the original execution comes back.
const retried = await gol.submitGasExecution(projectId, actionId, {
  ...input,
  maxChargeWei,
  agentSignature,
});

Retry	Result
Same `actionId`, same signature, same fields	The original execution. No second transfer
Same `actionId`, different signature or fields	Refused with `conflict`
New `actionId`, same intended transfer	A second transfer, if the owner’s caps allow it

Never mint a new actionId to work around a timeout. That is how a retry becomes a duplicate payment.

States

State	Meaning	Terminal
`accepted`, `signed`, `broadcast`	Accepted and being sent by the GOL relayer	No
`external_pending`	Waiting for your developer-operated relayer to sign and submit `transaction`	No
`external_submitted`	Your relayer’s bytes were accepted and are being observed	No
`indeterminate`	Sent, awaiting chain evidence. Do not resubmit; GOL resolves it	No
`collected`	The owner’s account paid the charge, inline in the action transaction or by a later revert claim	Yes
`not_charged`	Reached the selected head with no chargeable outcome, such as an unconsented outcome or a lifecycle refusal	Yes
`uncollectable`	A charge applied but was not paid, for example because the account was short of ETH	Yes
`rejected_preflight`	Refused before sending; no value moved	Yes
`finalized`	A reverted transaction under revert consent, awaiting GOL’s claim	No
`claim_signed`, `claim_submitted`, `claim_indeterminate`	GOL is claiming a reverted transaction’s gas	No
`disputed`	Under review after a dispute	No

Treat any state you do not recognize as non-terminal. waitForGasExecution stops at a terminal state by default.

import { waitForGasExecution } from "@gol/sdk/server";
import type { GasExecutionResponse } from "@gol/sdk";

declare const gol: import("@gol/sdk/server").GolApiClient;
declare const projectId: string;
declare const executionId: string;

// Stop as soon as a developer relayer needs to act, or at a terminal state.
const next = await waitForGasExecution(gol, projectId, executionId, {
  until: (execution: GasExecutionResponse) =>
    execution.state === "external_pending" ||
    ["collected", "not_charged", "uncollectable", "rejected_preflight"].includes(
      execution.state,
    ),
  intervalMs: 20_000,
});

GasExecutionResponse is exported from the browser-safe root entry point, so a server module can import it as a type without touching anything credentialed.

What the result contains

getGasExecution returns separate views rather than one blended number, which is the point: network cost, what the owner owes, what the owner actually paid, and GOL’s own cost never collapse into a single figure.

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

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

const execution = await gol.getGasExecution(projectId, executionId);

execution.payer; // "owner_reimbursement" | "developer" | "developer_relayer"
execution.relayerMode; // "gol" | "developer" | null
execution.state;
execution.receipt?.outcome; // "success" | "refusal" | "revert"
execution.receipt?.totalNetworkWei; // what the network charged
execution.settlement?.chargedWei; // what the owner's account paid
execution.settlement?.paid; // false when the account could not cover the charge
execution.settlement?.recipient; // who was reimbursed
execution.receipt?.golLossWei; // what GOL absorbed

Field	What it holds
`payer`, `relayerMode`, `submitter`	Who fronted the action’s gas and who sent it
`quote`	The caps the action was accepted under, including `maxChargeWei`, the agent-signed maximum
`settlement`	How the gas was paid: `kind` (`inline` or `claim`), `outcome`, metered `gasUnits` and `gasPriceWei`, the declared L1 and operator fees, `chargedWei`, `paid`, `recipient`, and `submitter`
`transaction`	For a developer-operated relayer only: the exact `to`, `data`, chain, gas limit, maximum fee, and submitter your relayer signs
`receipt`	The action’s transaction and block, its `finalizedBlockNumber`, its `outcome`, and the fee breakdown: `gasUsed`, `effectiveGasPrice`, `executionWei`, `l1DataWei`, `operatorWei`, `totalNetworkWei`, `eligibleOwnerWei`, `golLossWei`, `developerCostWei`
`claimReceipt`	A later revert claim’s transaction, `collectedWei`, `golClaimNetworkCostWei`, and a `status` of `collected` or `reverted`
`ledger`	Entries of `category`, `amountWei`, and `transactionHash`, one per cost component
`disputes`	Each dispute with its `status`, `reason`, `openedAt`, `resolvedAt`, and `resolution`
`transactionHashes`, `broadcasts`	Every hash involved, and each broadcast attempt with its `providerId` and outcome

receipt, settlement, and claimReceipt are null until the corresponding transaction is observed, so read them with optional chaining rather than assuming presence. finalizedBlockNumber shows how far the background observation has progressed; the hosted Base Sepolia setup settles at the lower safe head and continues observing through finalized, so a populated receipt is not by itself a finality claim. A refusal or a revert is a contract outcome, not an API error: the request succeeded and the contract declined the action because it fell outside the owner’s rules, usually a cap. No USDC moved. With refusal consent the owner still pays that transaction’s gas inline. An API-level refusal with capability_unavailable is different: the action was never sent, for example because the policy is paused, revoked, expired, or disputed.

List actions

listGasExecutions pages through a project’s history and accepts a state filter. Each summary carries the three cost figures already reduced, so a table needs one call.

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

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

const open = await gol.listGasExecutions(projectId, {
  limit: 50,
  state: "external_pending",
});
for (const summary of open.data) {
  console.log(
    summary.id,
    summary.state,
    summary.totalNetworkWei,
    summary.collectedWei,
    summary.golCostWei,
    summary.disputed,
  );
}

Open a dispute

If a charge looks wrong, open a dispute. New submissions under that execution’s gas policy pause until GOL resolves it, and a confirmed overcharge is refunded from GOL’s funds.

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

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

const dispute = await gol.openGasExecutionDispute(
  projectId,
  executionId,
  "The collected amount exceeds the gas actually used.",
);

Polling is authoritative. Webhooks tell you when to look, not what is true. Treat a webhook as a hint to fetch, deduplicate by event ID because delivery is at least once and may be out of order, and reconcile against getGasExecution.

Relay it yourself

For a policy the owner approved with a developer-operated relayer, submission returns the execution in external_pending with transaction. developerRelayerTransaction checks that the calldata is the agent’s signed action under this execution’s mandate, action, and gas policy, and returns the EIP-1559 envelope. Your relayer chooses its nonce and a priority fee no higher than maxFeePerGas, signs from the approved submitter, and submits the raw bytes.

import { developerRelayerTransaction } from "@gol/sdk";
import type { GasExecutionResponse } from "@gol/sdk";
import { GolApiClient } from "@gol/sdk/server";
import type { LocalAccount } from "viem";

declare const gol: GolApiClient;
declare const projectId: string;
declare const execution: GasExecutionResponse;
declare const relayer: LocalAccount;
declare const nonce: number;

const tx = developerRelayerTransaction(execution, { submitter: relayer.address });
const raw = await relayer.signTransaction({ ...tx, nonce, maxPriorityFeePerGas: 1_000_000n });
await gol.submitDeveloperRelayerTransaction(projectId, execution.id, raw);

GOL broadcasts the bytes and observes the receipt like its own, and you may broadcast them too. The owner reimburses your recipient inline in the action transaction; GOL records no cost for it.

Reconcile from your own records

The figures are separately observable, so your application can check its own accounting without trusting a summary. The receipt’s network cost and the inline charge are different fields, which is exactly the pair to compare.

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

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

const { receipt, settlement } = await gol.getGasExecution(projectId, executionId);

if (receipt && settlement?.kind === "inline") {
  const networkCostWei = BigInt(receipt.totalNetworkWei);
  const chargedWei = BigInt(settlement.chargedWei);

  if (chargedWei > networkCostWei) {
    // GOL records the difference as a refund obligation and returns it through a dispute.
  }
}

Because the caps, the agent’s maximum charge, and the outcomes the owner pays for are in the quote the action was accepted under, you can also check that a charge stayed inside what the owner and the agent agreed to, rather than only inside the network’s own total.

Get started

Guides

Reference

Execution and observation

Prepare, sign, submit

Retries never move value twice

States

What the result contains

List actions

Open a dispute

Relay it yourself

Reconcile from your own records

​Prepare, sign, submit

​Retries never move value twice

​States

​What the result contains

​List actions

​Open a dispute

​Poll or subscribe

​Relay it yourself

​Reconcile from your own records

Prepare, sign, submit

Retries never move value twice

States

What the result contains

List actions

Open a dispute

Poll or subscribe

Relay it yourself

Reconcile from your own records