GaslessTransact SDK

A TypeScript SDK for ERC-4337 gasless transactions. The SDK talks to a UGTP API that builds and submits UserOperations; it does not sign anything until you explicitly ask it to.

Installation

npm install @gaslesstransact/sdk ethers@6

Lifecycle

All transactions follow the same three-step flow:

1. Generate — POST your calls to the API; get back an unsigned UserOp, its hash, and an estimated max fee (in fee-token units if a paymaster is used).
2. Sign — sign the returned userOpHash with your signer.
3. Send — submit the signed UserOp to the API, which broadcasts handleOps and returns the relayer transaction hash immediately.

You can optionally poll or wait for a terminal status.

Quick Start

import { GaslessClient, BrowserSigner, NetworkId } from "@gaslesstransact/sdk";

const client = new GaslessClient({
  apiUrl: "https://api.gaslesstransact.io/api/v1",
  apiHeaders: { "x-api-key": "your-api-key" },
  networkId: NetworkId.SEPOLIA,
  signer: new BrowserSigner(),
});

// 1. Generate
const generated = await client.generateUserOperation({
  calls: [{ to: "0xRecipient…", data: "0x", value: "0x0" }],
  feeToken: "0xfFf9976782d46CC05630D1f6eBAb18b2324d6B14", // optional WETH on Sepolia
  headers: { "x-request-id": "generate-1" }, // optional per-call headers
});

// 2. Sign
const signature = await client.signUserOperationHash(generated.userOpHash);

// 3. Send
const result = await client.sendUserOperation({
  userOperation: { ...generated.userOperation, signature },
  userOpHash: generated.userOpHash,
  networkId: NetworkId.SEPOLIA,
});

// (optional) watch submitted -> terminal status
const status = await client.waitForTransaction(result.transactionHash, {
  timeoutMs: 120_000,
  onStatus: (nextStatus) => {
    console.log("status update", nextStatus.status, nextStatus.transactionHash);
  },
});
console.log(status.status, status.transactionHash);

Signers

The SDK ships two ISigner implementations:

• BrowserSigner — wraps a browser EIP-1193 provider (e.g. MetaMask).
• PrivateKeySigner — signs with a raw private key (server-side or scripts).

Custom signers only need to implement:

interface ISigner {
  getAddress(): Promise<string>;
  signMessage(message: string): Promise<string>;
}

Client Surface

A GaslessClient exposes:

• client.account — smart account address derivation, address info, and deployment status via direct RPC reads.
• client.transaction — low-level UGTP API transport for generate/send/status polling.
• client methods for signing, waiting, and shared network metadata lookups.

API Reference

GaslessClient

new GaslessClient({ apiUrl, networkId, signer });

• networkId should use the shared SupportedNetworkId union, typically via NetworkId.ETHEREUM, NetworkId.ARBITRUM, etc.

• the SDK now uses the bundled shared public factory address metadata for local smart-account derivation instead of accepting caller-provided factory overrides

• the bundled public contract metadata is sourced from the shared deployment registry in shared/src/deployments.ts

• pass provider / providers when you want explicit read providers, or rpcUrl / rpcUrls if you prefer raw RPC strings

• pass apiHeaders when every API request needs headers such as x-api-key; generate/send/status methods also accept per-call headers

• if no provider config is passed, the SDK falls back to built-in public read RPC defaults per supported network

• generateUserOperation(params) → GenerateUserOpResult

• signUserOperationHash(userOpHash) → signature

• sendUserOperation(params) → TransactionResult with the relayer transactionHash

• waitForTransaction(transactionHash, options?) → final observed TransactionStatus

• getSupportedNetworks() → NetworkConfig[]

• getNetworkConfig(networkId?) → NetworkConfig

• getSupportedTokens(networkId?) → TokenConfig[]

client.transaction

• generateUserOperation(request) → GenerateUserOpResult
• request must include networkId, ownerAddress, senderAddress, and calls
• request may include headers; they are applied to that HTTP request and are not serialized into the JSON body
• this is the low-level API transport shape; GaslessClient.generateUserOperation(...) derives ownerAddress and senderAddress for you
• sendUserOperation(params) → TransactionResult; params may include per-call headers
• getStatus(transactionHash, networkId, options?) → TransactionStatus; options may include headers
• waitForCompletion(transactionHash, networkId, options?) → final observed TransactionStatus; options may include headers for every poll
  • returns terminal status when confirmed/failed/dropped
  • returns the last observed non-terminal status on timeout
  • returns unknown on timeout if no status could be observed yet

client.account

• getSmartWalletAddress(networkId, ownerAddress?) → smart wallet address
• getSmartWalletAddressInfo(networkId, ownerAddress?) → address info
• isSmartWalletDeployed(networkId, ownerAddress?) → boolean

If ownerAddress is omitted, the module falls back to the configured signer address. The account module no longer calls the API. It derives the counterfactual address locally with SmartAccountFactory.getAddress(...) using the SDK's bundled public factory config, and checks deployment status with provider.getCode(...).

Provider Utilities

The SDK also exports:

• getDefaultRpcUrl(networkId) → built-in public read RPC URL
• createDefaultProvider(networkId) → default JsonRpcProvider
• resolveProviderForNetwork(networkId, config) → resolved read provider from provider / providers / rpcUrl / rpcUrls with public fallback
• new NetworkProviderResolver(config) → cached, validated per-network provider resolver used by Account

HTTP Utilities

The SDK also exports:

• new HttpClient({ baseUrl }) → reusable JSON-focused HTTP client with query-param support and automatic UGTP APIResponse unwrapping
• HttpError → normalized error type for non-2xx responses and API-level failures

Network Helpers

The SDK exports pure helpers for shared network metadata:

• getSupportedNetworks() → NetworkConfig[]
• getNetworkConfig(networkId) → NetworkConfig
• getSupportedTokens(networkId) → TokenConfig[]

Types

import type {
  Call,
  SendCallsParams,
  GenerateUserOperationRequest,
  GaslessClientConfig,
  ProviderConfig,
  UserOperation,
  GenerateUserOpResult,
  SendUserOperationParams,
  TransactionResult,
  TransactionStatus,
  WaitForTransactionOptions,
  NetworkConfig,
  TokenConfig,
  SmartWalletAddressInfo,
} from "@gaslesstransact/sdk";

License

MIT