Client Configuration

This page is the complete reference for the parameters accepted by the OstiumClient factory methods. Every factory returns a Promise<OstiumClient> and is async, so always await it.

import { OstiumClient } from '@ostium/builder-sdk';

const client = await OstiumClient.createSelfAndSelf({
  traderPrivateKey: process.env.TRADER_PRIVATE_KEY as `0x${string}`,
  rpcUrl: process.env.ARB_RPC_URL!,
  // shared options below are accepted by every write mode
  testnet: false,
  slippageBps: 25,
  builder: { address: '0xBuilderAddress', feeBps: 10 },
  alchemyApiKey: process.env.ALCHEMY_API_KEY!,
});

Shared options (all write modes)

These optional fields are accepted by createSelfAndSelf, createSelfAndGasless, createDelegatedAndSelf, and createDelegatedAndGasless.

Option	Type	Default	Description
`testnet`	`boolean`	`false`	Use Arbitrum Sepolia. Switches the contracts, subgraph endpoint, builder API endpoint, and the default Pimlico sponsor URL. See Testnet.
`slippageBps`	`number`	`25`	Default slippage tolerance in basis points (`25` = 0.25%). Used when a call does not pass its own slippage.
`builder`	`{ address: string; feeBps: number }`	—	Builder fee sharing. `feeBps` is in basis points, range `0`–`50` (0%–0.5%), in steps of `0.01` bps. Can be overridden per `openTrade()` call.
`subgraphUrl`	`string`	mainnet/testnet subgraph	Override the Ostium subgraph endpoint used by read methods (`getPairs`, `getOpenPositions`, …). Mainnet default is `https://builder.prod.bedrock.ostium.io/v1/subgraph/gn`.
`builderApiUrl`	`string`	`https://builder.prod.bedrock.ostium.io`	Override the builder API base URL used for live prices, OHLC candles, and the WebSocket price stream.
`rpcWsUrl`	`string`	—	WebSocket Arbitrum RPC endpoint for `streamAccountUpdates()`’s contract-log subscription. Can also be passed per stream call.
`rpcHttpUrl`	`string`	see below	HTTP RPC endpoint for the account stream’s missed-event sweep and block reads. Set it only to send those reads somewhere other than where they go by default.
`alchemyApiKey`	`string`	—	Alchemy API key for the same stream. Still fully supported — it just builds the Alchemy WebSocket and HTTP URLs for you.

These three are only needed for streamAccountUpdates(). Set them at client creation or per stream call, where the per-call value wins. When rpcHttpUrl is not set, the sweep and block reads go to the first of these that exists: the Alchemy URL (when alchemyApiKey is set), then rpcUrl, then the public Arbitrum RPC. Prefer rpcWsUrl: the stream makes only standard JSON-RPC calls, so any Arbitrum node works, and no vendor key needs to reach a browser bundle. With neither rpcWsUrl nor alchemyApiKey, the stream throws INVALID_CONFIG. Factories do not pre-fetch the pair list during construction. Pair metadata is loaded lazily by read methods and streams when they need it. Submit-capable gasless factories still derive the Safe address with one eth_call unless you pass a known safeAddress.

Submit-capable vs build-only

Every write mode can be created two ways:

Submit-capable — pass a private key; the SDK signs and submits.
Build-only — pass addresses only; use get*Tx() to return unsigned transaction data for your own wallet or Safe flow. No key ever touches the SDK.

The fields below differ between the two variants of each mode.

`createSelfAndSelf`

The trader EOA owns funds, signs, and pays gas. See Self + Self. Submit-capable

Field	Type	Required	Description
`traderPrivateKey`	`0x${string}`	Yes	Private key of the trader EOA. Holds USDC, owns positions, pays gas.
`rpcUrl`	`string`	Yes	Arbitrum One (or Sepolia) RPC URL.

Build-only

Field	Type	Required	Description
`traderAddress`	`0x${string}`	Yes	Trader EOA address. Used to build unsigned EOA transactions.
`rpcUrl`	`string`	No	RPC URL for reads/simulation. Defaults to the chain’s public RPC.

`createSelfAndGasless`

The trader EOA owns funds and signs; a Safe derived from the key submits gaslessly. See Self + Gasless. Submit-capable

Field	Type	Required	Description
`traderPrivateKey`	`0x${string}`	Yes	Private key of the trader EOA. A Safe is derived from this key to relay trades gaslessly.
`safeAddress`	`0x${string}`	No	Known Safe smart-account address for this key. Use the value from `client.getSmartAccountAddress()` to skip the derivation call during construction. Deterministic per key and chain.
`pimlicoUrl`	`string`	No	Pimlico-compatible bundler/paymaster RPC URL. Defaults to the Ostium sponsor URL (`…/v1/pimlico/sponsor?chainId=42161`, or the Sepolia variant on testnet).
`rpcUrl`	`string`	No	RPC URL for reads/simulation. Defaults to the public Arbitrum RPC.
`sponsorshipPolicyId`	`string`	No	Pimlico sponsorship policy ID.

Build-only

Field	Type	Required	Description
`traderAddress`	`0x${string}`	Yes	Trader EOA that owns USDC and positions.
`safeAddress`	`0x${string}`	Yes	Safe smart-account address that will submit delegated calls.
`rpcUrl`	`string`	No	RPC URL for reads/simulation. Defaults to the chain’s public RPC.

`createDelegatedAndSelf`

A delegate EOA signs and pays gas on behalf of a separate trader. See Delegated + Self. Submit-capable

Field	Type	Required	Description
`delegatePrivateKey`	`0x${string}`	Yes	Private key of the delegate EOA. Signs and pays gas for all transactions.
`traderAddress`	`0x${string}`	Yes	Trader this delegate acts for. The trader must have called `setDelegate(delegateAddress)`.
`rpcUrl`	`string`	Yes	Arbitrum One (or Sepolia) RPC URL.

Build-only

Field	Type	Required	Description
`traderAddress`	`0x${string}`	Yes	Trader this delegate acts for.
`delegateAddress`	`0x${string}`	Yes	Delegate EOA that will submit the transaction.
`rpcUrl`	`string`	No	RPC URL for reads/simulation. Defaults to the chain’s public RPC.

`createDelegatedAndGasless`

A Safe derived from the delegate key submits sponsored user operations on behalf of the trader. See Delegated + Gasless. Submit-capable

Field	Type	Required	Description
`delegatePrivateKey`	`0x${string}`	Yes	Private key of the delegate EOA. A Safe is derived from this key and submits user operations via Pimlico.
`safeAddress`	`0x${string}`	No	Known Safe smart-account address for the delegate key. Use the value from `client.getSmartAccountAddress()` to skip the derivation call during construction. Deterministic per key and chain.
`traderAddress`	`0x${string}`	Yes	Trader this delegate acts for. The trader must have called `setDelegate(safeAddress)`, where `safeAddress` is the Safe derived from the delegate key (`client.getSmartAccountAddress()`).
`pimlicoUrl`	`string`	No	Pimlico bundler/paymaster RPC URL. Defaults to the Ostium sponsor URL (chain-aware).
`rpcUrl`	`string`	No	RPC URL for reads/simulation. Defaults to the public Arbitrum RPC.
`sponsorshipPolicyId`	`string`	No	Pimlico sponsorship policy ID.

Build-only

Field	Type	Required	Description
`traderAddress`	`0x${string}`	Yes	Trader this delegate acts for.
`delegateAddress`	`0x${string}`	Yes	Delegate EOA that owns the Safe.
`safeAddress`	`0x${string}`	Yes	Safe smart-account address that will submit delegated calls.
`rpcUrl`	`string`	No	RPC URL for reads/simulation. Defaults to the chain’s public RPC.

`createReadOnly`

No signer, no submitter, no private key. All read methods work; write methods throw INVALID_CONFIG. See Read-only.

Field	Type	Required	Description
`rpcUrl`	`string`	No	Arbitrum RPC URL. Defaults to the chain’s public RPC.
`testnet`	`boolean`	No	Use Arbitrum Sepolia. Defaults to `false`.
`subgraphUrl`	`string`	No	Override the subgraph endpoint.
`builderApiUrl`	`string`	No	Override the builder API base URL.
`alchemyApiKey`	`string`	No	Alchemy API key for `streamAccountUpdates()`.

Read-only clients do not accept slippageBps or builder — those only apply to write modes that submit or build trades.

Notes

All factories are async — await them.
Client creation does not fetch pair metadata from the subgraph. Reads and streams populate that cache lazily.
Mode is inferred from the fields you pass; you don’t set mode directly.
Builder fee defaults (builder at client creation) can be overridden per openTrade() call via builder.address / builder.feeBps.
On testnet: true, omitted pimlicoUrl, subgraphUrl, and builderApiUrl resolve to their Sepolia defaults — you can still override any of them.

SDK

Client Modes

Helpers

Previews & Limits

Read Methods

Live State

Write Methods

Builder API

Builder

Trader

Legacy

Client Configuration

Shared options (all write modes)

Submit-capable vs build-only

`createSelfAndSelf`

`createSelfAndGasless`

`createDelegatedAndSelf`

`createDelegatedAndGasless`

`createReadOnly`

Notes

​Shared options (all write modes)

​Submit-capable vs build-only

​createSelfAndSelf

​createSelfAndGasless

​createDelegatedAndSelf

​createDelegatedAndGasless

​createReadOnly

​Notes

Shared options (all write modes)

Submit-capable vs build-only

`createSelfAndSelf`

`createSelfAndGasless`

`createDelegatedAndSelf`

`createDelegatedAndGasless`

`createReadOnly`

Notes