Configuration

Both OxGasAuth and OxGasClient accept a configuration object when you create them. Only apiKey is required — the rest have sensible defaults.

Options

Option	Type	Default	Description
apiKey	string	required	Your project API key from the dashboard.
widgetUrl	string	0xGasless CDN	Override with a custom widget URL. Useful for self-hosted setups or local development.
network	string	"Ethereum"	The network name shown in the widget’s approval screens.
chainId	number	—	Pass a chain ID and the SDK looks up the name automatically. Takes precedence over network if both are provided.
zIndex	number	99999	The CSS z-index of the widget overlay. Raise this if other elements appear on top of the widget.
loginTimeout	number	300000	How long (in milliseconds) to wait for the user to complete login before rejecting. Default is 5 minutes.
signTimeout	number	120000	How long (in milliseconds) to wait for the user to approve a signing request. Default is 2 minutes.
debug	boolean	false	Enables detailed console logging. Turn this on during development to trace message flow between your app and the widget.

OxGasClient adds three more options on top of the above:

Option	Type	Default	Description
bundlerUrl	string	required	The bundler endpoint that receives your UserOperations.
paymasterUrl	string	required	The paymaster RPC URL used to sponsor gas.
rpcUrl	string	chain default	A custom RPC for reading on-chain state (balances, token info). If omitted, a default public RPC is used.
accountIndex	number	0	Derive a different smart account from the same signer by passing a non-zero index.

Examples

Minimal setup (auth only)

import { OxGasAuth } from '0xgas-auth';

const auth = new OxGasAuth({
  apiKey: 'your-api-key',
  chainId: 8453, // Base — resolved to "Base" in the widget
});

String shorthand

If you only need the API key and are happy with all defaults, you can pass a string directly:

const auth = new OxGasAuth('your-api-key');

Full client setup

import { OxGasClient } from '0xgas-auth';

const client = new OxGasClient({
  apiKey: 'your-api-key',
  chainId: 137,
  bundlerUrl: 'https://bundler.0xgasless.com/137',
  paymasterUrl: 'https://paymaster.0xgasless.com/v1/137/rpc/your-api-key',
  rpcUrl: 'https://polygon-rpc.com',
  debug: true,
  loginTimeout: 600_000, // 10 minutes
});

Custom widget URL (local development)

When working on the widget itself or running a self-hosted instance:

const auth = new OxGasAuth({
  apiKey: 'dev-key',
  widgetUrl: 'http://localhost:5173',
  debug: true,
});

Custom network name

For chains not in the built-in registry, or when you want a specific display name:

const auth = new OxGasAuth({
  apiKey: 'your-api-key',
  network: 'My Custom L2',
});

Network auto-resolution

When you pass chainId, the SDK resolves it to a human-readable name for the widget’s approval screens. For example, chainId: 42161 becomes "Arbitrum One". If the chain ID is not in the built-in list, it falls back to "Chain 42161".

You can override this at any time by passing network explicitly. The explicit network value always wins.

See Supported Networks for the full list of built-in chain IDs.