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. If a relayer lane has capacity, the API broadcasts handleOps and returns a relayer transaction hash; otherwise it returns queued and you can poll by userOpHash.

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
  // transferred asset(s) the percentage transfer fee is charged on; one element per moved token
  transferredAssets: [{ address: "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", amount: "0x0" }],
  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 queued/submitted -> terminal status
const statusLookupHash = result.transactionHash ?? result.userOpHash;
const status = await client.waitForTransaction(statusLookupHash, {
  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.fee — approximate native/fee-token preview using gas prices, call-gas estimation, and the paymaster fee formula.
• 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; transactionHash is present once submitted, while queued results can be polled by userOpHash

• waitForTransaction(transactionHashOrUserOpHash, 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 includes a transferredAssets array (each { address, amount }, amount a hex quantity in that token's base units); the API quotes each asset's value into the selected fee token through trusted Uniswap V3 routes and sums them before signing the paymaster payload (a single op can move several different tokens)
• 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(transactionHashOrUserOpHash, networkId, options?) → TransactionStatus; options may include headers
• waitForCompletion(transactionHashOrUserOpHash, networkId, options?) → final observed TransactionStatus; options may include headers for every poll
  • returns terminal status when confirmed/failed/dropped
  • uses the API-provided polling hint internally between polls
  • returns the last observed non-terminal status on timeout
  • returns unknown on timeout if no status could be observed yet

client.fee

• estimate({ networkId, feeToken?, senderAddress?, calls?, transferredAssets }) → FeeEstimate
• when calls and senderAddress are supplied for a deployed account, the SDK encodes the SmartAccount calldata, estimates execution gas with a small buffer, and uses that in the preview
• when calls are omitted, or the smart account is not deployed yet, the SDK falls back to the transfer-style heuristic until generateUserOperation(...) returns the precise signed cap
• GaslessClient.estimateFee(...) defaults networkId from the client and derives senderAddress from the signer when calls are supplied

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