SDK reference

new GolApiError(status: number, code: string, message: string, correlationId: string | null)

new GolTransportError(message: string, options?: ErrorOptions)

type AccountFamily = "safe" | "nexus" | "kernel" | "alchemy" | "nexus7702";

interface AgentSigner {
  signTypedData(typedData: TypedDataPayload): Promise<Hex>;
}

type ApiKeyScope = ApiKey["scopes"][number];

interface CombinedGasApproval {
  mandateId: Hex;
  gasPolicyId: Hex;
  digest: Hex;
  ownerSigningHash: Hex;
  summary: {
    chainId: number;
    account: Address;
    core: Address;
    projectId: Hex;
    agent: Address;
    submitter: Address;
    recipient: Address;
    attester: Address;
    feeAsset: Address;
    maxPerActionWei: bigint;
    maxTotalWei: bigint;
    chargeableOutcomes: number;
    expiresAt: number;
  };
  encodeSubmission(ownerWalletSignature: Hex): Hex;
}

interface DeveloperRelayerTransaction {
  chainId: 84532;
  type: "eip1559";
  from: Address;
  to: Address;
  data: Hex;
  value: 0n;
  gas: bigint;
  maxFeePerGas: bigint;
}

interface Eip7702AuthorizationSigner {
  signAuthorization(request: {
    chainId: number;
    address: Address;
    nonce: number;
  }): Promise<{
    r: Hex;
    s: Hex;
    yParity?: number | undefined;
    v?: bigint | undefined;
  }>;
}

interface GasActionAuthorizationMessage {
  mandateId: Hex;
  actionId: Hex;
  deadline: number;
  inputHash: Hex;
  gasPolicyId: Hex;
  maxCharge: bigint;
}

type GasExecutionSummary = ListGasExecutionsResponse["data"][number];

interface GasMandateTerms {
  parentId: Hex;
  account: Address;
  agent: Address;
  accountProfileId: Hex;
  installEpoch: bigint;
  projectId: Hex;
  mode: number;
  policyVersion: number;
  policyHash: Hex;
  validFrom: number;
  expiresAt: number;
  maxDepth: number;
  maxActiveDescendants: number;
  approvalExpiresAt: number;
  salt: Hex;
}

interface GasPolicyInput {
  mandateId: Hex;
  account: Address;
  projectId: Hex;
  accountProfileId: Hex;
  installEpoch: Numeric;
  feeAsset: Address;
  submitter: Address;
  recipient: Address;
  attester: Address;
  maxPerAction: Numeric;
  maxTotal: Numeric;
  expiresAt: Numeric;
  chargeableOutcomes: Numeric;
  formulaVersion: Numeric;
  nonce: Numeric;
}

type GolEnvironment = Project["environments"][number]["name"];

type GolOwnerPayload = {
  primaryType: "CombinedGasApproval";
  message: {
    mandateId: Hex;
    gasPolicyId: Hex;
  };
} | {
  primaryType: "GasRevocation";
  message: {
    gasPolicyId: Hex;
    nonce: Numeric;
    deadline: Numeric;
  };
} | {
  primaryType: "SafetyAction";
  message: {
    mandateId: Hex;
    action: Numeric;
    nonce: Numeric;
    deadline: Numeric;
  };
};

interface MandateTermsInput {
  parentId: Hex;
  account: Address;
  agent: Address;
  accountProfileId: Hex;
  installEpoch: Numeric;
  projectId: Hex;
  mode: Numeric;
  policyVersion: Numeric;
  policyHash: Hex;
  validFrom: Numeric;
  expiresAt: Numeric;
  maxDepth: Numeric;
  maxActiveDescendants: Numeric;
  approvalExpiresAt: Numeric;
  salt: Hex;
}

type OwnerAccountCall = {
  to: Address;
  data: Hex;
  /** Safe must delegatecall MultiSendCallOnly. Other calls target the account itself. */
  operation: 0 | 1;
};

interface OwnerGasPolicy {
  mandateId: Hex;
  account: Address;
  projectId: Hex;
  accountProfileId: Hex;
  installEpoch: bigint;
  /** Formula version 2 supports native ETH only. */
  feeAsset: Address;
  /** The only address that may send an inline-settled action under this policy. */
  submitter: Address;
  /** The address the account reimburses. */
  recipient: Address;
  /** Signs revert claims; zero unless the revert bit is set. */
  attester: Address;
  maxPerAction: bigint;
  maxTotal: bigint;
  expiresAt: number;
  /** 1 = success, 2 = refusal, 4 = revert. */
  chargeableOutcomes: number;
  formulaVersion: number;
  nonce: bigint;
}

type OwnerOperation = {
  kind: "safe_transaction";
  family: "safe";
  account: Address;
  nonce: bigint;
  typedData: TypedDataPayload;
  expectedHash: Hex;
  /** Encode `execTransaction` after the owners sign `typedData`. */
  encode(signatures: Hex): {
    to: Address;
    data: Hex;
    value: 0n;
  };
} | {
  kind: "eoa_transaction";
  family: "nexus7702";
  account: Address;
  /** The owner's wallet sends this transaction from the account itself. */
  transaction: {
    from: Address;
    to: Address;
    data: Hex;
    value: 0n;
  };
} | {
  kind: "user_operation";
  family: UserOperationFamily;
  account: Address;
  userOperation: PackedUserOperation;
  userOpHash: Hex;
  /** The owner wallet signs `userOpHash` with EIP-191 `personal_sign`. */
  message: {
    raw: Hex;
  };
  /** Direct EntryPoint submission from any funded address, or give the signed operation to a bundler. */
  encode(ownerSignature: Hex, beneficiary: Address): {
    to: Address;
    data: Hex;
    value: 0n;
    gas: bigint;
    userOperation: PackedUserOperation;
  };
};

interface OwnerOperationOptions {
  verificationGasLimit?: bigint;
  callGasLimit?: bigint;
  preVerificationGas?: bigint;
  maxFeePerGas?: bigint;
  maxPriorityFeePerGas?: bigint;
}

interface OwnerSigner {
  signTypedData(typedData: TypedDataPayload): Promise<Hex>;
  signMessage?(args: {
    message: {
      raw: Hex;
    };
  }): Promise<Hex>;
}

interface PackedUserOperation {
  sender: Address;
  nonce: bigint;
  initCode: Hex;
  callData: Hex;
  accountGasLimits: Hex;
  preVerificationGas: bigint;
  gasFees: Hex;
  paymasterAndData: Hex;
  signature: Hex;
}

interface PreparedChildMandateExpectations {
  core?: Address;
  parentMandateId?: Hex;
  parentAgent?: Address;
  agent?: Address;
  recipients?: readonly Address[];
  maxPerActionBaseUnits?: bigint;
  maxTotalBaseUnits?: bigint;
  tree?: {
    maxDepth: number;
    maxActiveDescendants: number;
  };
}

interface PreparedGasExecutionExpectations {
  core?: Address;
  mandateId?: Hex;
  gasPolicyId?: Hex;
  agent?: Address;
  recipient?: Address;
  amountBaseUnits?: bigint;
  deadline?: number;
  /** The largest network charge the agent accepts for this action. */
  maxChargeWei?: bigint;
  relayerMode?: "gol" | "developer";
}

interface PreparedGasPolicyExpectations {
  /** The platform project UUID the approval must bind. */
  projectId?: string;
  core?: Address;
  account?: Address;
  agent?: Address;
  recipients?: readonly Address[];
  maxPerActionBaseUnits?: bigint;
  maxTotalBaseUnits?: bigint;
  maxGasPerActionWei?: bigint;
  maxGasTotalWei?: bigint;
  chargeableOutcomesMask?: number;
  /** The relayer the owner intends to approve; for `gol`, the configured relayer and recipient. */
  relayer?: {
    mode: "gol";
    submitter?: Address;
    recipient?: Address;
  } | {
    mode: "developer";
    submitter: Address;
    recipient: Address;
  };
  attester?: Address;
  tree?: {
    maxDepth: number;
    maxActiveDescendants: number;
  };
}

interface PreparedGasRevocation {
  account: Address;
  policyId: Hex;
  nonce: bigint;
  deadline: number;
  digest: Hex;
  ownerSigningHash: Hex;
  encodeSubmission(ownerWalletSignature: Hex): Hex;
}

interface RawHashSigner {
  sign(request: {
    hash: Hex;
  }): Promise<Hex>;
}

type SafetyActionCode = (typeof SAFETY_ACTION_CODES)[SafetyActionName];

type SafetyActionName = keyof typeof SAFETY_ACTION_CODES;

type SignatureFormat = "safe_threshold" | "nexus_k1" | "kernel_root" | "alchemy_entity_zero" | "eoa";

type SmartAccountFamily = Exclude<AccountFamily, "nexus7702">;

interface TransferPolicyInput {
  asset?: Address;
  recipients: readonly Address[];
  maxPerActionBaseUnits: bigint;
  maxTotalBaseUnits: bigint;
}

interface TypedDataPayload {
  domain: Record<string, unknown>;
  types: Record<string, Array<{
    name: string;
    type: string;
  }>>;
  primaryType: string;
  message: Record<string, unknown>;
}

type UserOperationFamily = Exclude<AccountFamily, "safe" | "nexus7702">;

interface WalletSigningInput {
  family: AccountFamily;
  account: Address;
  core: Address;
  payload: GolOwnerPayload;
  chainId?: number;
}

interface WalletSigningPayload {
  family: AccountFamily;
  method: "eth_signTypedData_v4";
  typedData: TypedDataPayload;
  expectedHash: Hex;
  digest: Hex;
  signatureFormat: SignatureFormat;
}

new GolApiClient(options: GolApiClientOptions)

new GolApiError(status: number, code: string, message: string, correlationId: string | null)

new GolManagementClient(options: GolManagementClientOptions)

new GolTransportError(message: string, options?: ErrorOptions)

interface GolApiClientOptions extends GolClientOptions {
  apiKey: string;
}

interface GolClientOptions {
  baseUrl: string;
  fetch?: typeof fetch;
}

interface GolManagementClientOptions extends GolClientOptions {
  sessionToken?: string | null;
}

interface GolWebhookEvent<Data = unknown> {
  id: string;
  type: "gas_execution.updated" | "gas_policy.confirmed" | "gas_policy.revoked" | "gas_policy.paused" | "gas_policy.resumed" | "gas_policy.child_created" | "gas_policy.child_updated" | "account.eip7702_setup_updated" | "webhook.test" | (string & {});
  createdAt: string;
  projectId: string;
  environment: "test" | "live";
  data: Data;
}

interface PageOptions {
  limit?: number;
  cursor?: string;
  environment?: "test" | "live";
}

interface WaitOptions {
  intervalMs?: number;
  timeoutMs?: number;
  signal?: AbortSignal;
}