Introduction

Bazaar is a permissionless perpetual futures protocol on Arbitrum: any asset with a Pyth price feed can be listed and traded on a fully on-chain central limit order book, margined in USDC. The contracts are immutable, with no owner, pauser or upgrade key, and every role an exchange keeps for itself (listing, insuring, liquidating, firing stops) is open to anyone.

The protocol is not yet deployed: there is no official deployment on any network, so these pages use placeholder factory addresses until Bazaar’s deployments page lists one.

This site documents the TypeScript tools for building on it. They come in two packages:

The keeper is built on the SDK: the chain client, the ABIs, the price layer, the formulas and the market reader are the same code a frontend uses.

What the SDK Does

• Reads, batched into as few RPC calls as the node allows: the market list with labels, a market’s whole state at one block (prices, funding, margin, open interest, insurance, ADL, termination, the book), an account’s position, health, orders, withdrawable amount and fees, and a portfolio across every market.
• Live data: a streamed, composed Pyth price per market with freshness and venue-closed flags, and typed contract events with refreshed snapshots, safe across reorgs.
• Writes, checked before they are built: each builder validates its inputs the way the contract will, then returns a PreparedCall (target, calldata, ETH value, a one-line summary, the USDC it pulls) for your code to simulate and send.
• Explanations: a revert decoded to a named error and a sentence for the user, for every custom error the contracts declare, and for the failures wallets raise.

What It Does Not Do

• It never holds a key. It does not sign or send on its own. A write is a PreparedCall that you simulate and hand to the user’s wallet (or, in a bot, to a viem WalletClient holding the bot’s key). Signatures for gasless calls and USDC permits are requested from an EIP-1193 wallet with eth_signTypedData_v4, so the wallet shows the user what they sign.
• It does not choose for you whom you serve, which markets you show, or how you present them. The contracts cannot tell who calls them; that decision belongs to whoever puts an interface in front of users (see Bazaar’s integrator guide).
• It does not run a relayer or an indexer. It builds and verifies gasless requests and reads Bazaar’s subgraph; running those services is yours.
• It does not re-explain the protocol. Margin, funding, liquidation, ADL and termination are defined in Bazaar’s own docs, which these pages link wherever a rule matters.

A Taste

Connect a browser wallet, read the user’s account on the ETH/USD market, and place a limit order, simulated before the wallet is asked to sign:

const [user] = (await window.ethereum.request({ method: "eth_requestAccounts" })) as Address[];
const bz = await Bazaar.connect({ transport: window.ethereum, factory: FACTORY, prices: { token: pythToken } }); // tokens from your backend

const eth = await bz.markets.getMarket("ETH/USD");
const me = await bz.account.accountSnapshot(eth, user!);
console.log(`position ${formatUnits18(me.position.size)}, margin ratio ${me.health?.marginRatio ?? "-"}`);

const call = await bz.trade.createOrder(eth.address, user!, {
  orderType: OrderType.Limit, isLong: true, size: parseUnits18("0.5"), limitPrice: parseUnits18("2400"),
  expirationBlock: me.block + orders.blocksIn(3600), // one hour of Arbitrum blocks
});
const sim = await bz.simulate(call); // as the user, before anything is signed
if (sim.ok) await bz.send(window.ethereum, call); // the wallet signs and sends
else console.error(errorMessage(sim.error)); // "This order needs $1,240.50 of collateral ..."

FACTORY is the deployment’s factory address, from Bazaar’s deployments page, and pythToken a function of your page that returns a short-lived Pyth Pro token from your backend (see Connecting). Amounts are 18-decimal bigints: parseUnits18("0.5") is half a unit, parseUnits18("2400") is $2,400.

A Map of These Docs

Getting Started

• Installation: requirements, installing, TypeScript settings.
• Quick Start: a Frontend: a plain web page from connect to a placed order.
• Quick Start: a Bot: a Node script with its own key.
• Core Concepts: the connection, prepared calls, units, prices, errors, what is cached. Read this before going further.

The Keeper: what it does, setting one up, its configuration, jobs and budgets, running it in production, and the keeper as a library.

Frontends & Bots: connecting, markets, accounts, live prices and live updates; sending transactions, collateral and permits, placing and managing orders, previews and errors; gasless trading and smart accounts; history; insurance, termination, listings and governance; building a bot and the low-level building blocks.

Reference: the API index, units and constants, security notes for integrators, and development of the packages themselves.

Installation

This page covers what the SDK needs, how to install it (from npm once it is published, from the repository until then), how it fits a project that already uses viem or wagmi (or neither), the TypeScript settings it expects, and how to install the keeper.

Requirements

ES modules only. The package is "type": "module" and its exports map has only an import condition. Import it with import; from CommonJS, load it with a dynamic await import("@liberta-labs/bazaar-sdk").

Tree-shaking. The package declares "sideEffects": ["./dist/errors/messages.js"], so a bundler drops every module you do not use. The one module kept for its side effect registers the user-facing error messages; connect() also registers them explicitly (installUserMessages()), so they survive even a bundler that ignores the flag. If you decode errors without ever connecting (a script that only calls decodeError), call installUserMessages() once yourself.

Installing the SDK

Once published:

npm install @liberta-labs/bazaar-sdk

The packages are not on npm yet. Until they are, build them from the repository:

git clone https://github.com/liberta-labs/bazaar-sdk && cd bazaar-sdk && npm install && npm run build

Then either pack the SDK into a tarball and install that in your project, which is what npm will later install:

npm pack -w @liberta-labs/bazaar-sdk          # writes liberta-labs-bazaar-sdk-0.1.0.tgz
cd ../my-app && npm install ../bazaar-sdk/liberta-labs-bazaar-sdk-0.1.0.tgz

or link the built package folder, which picks up rebuilds without reinstalling:

cd ../my-app && npm install ../bazaar-sdk/packages/sdk

Install viem in your project too if you import from it (the samples in these docs do, for types such as Address and for wallet clients). Keep one copy: the same major version the SDK uses.

With viem, wagmi, or Neither

The SDK talks to the chain through a Transport: anything with an EIP-1193 request({ method, params }). Three kinds of object fit, and you pick per project:

// No library at all: the wallet's own EIP-1193 provider in a browser...
const inBrowser = await Bazaar.connect({ transport: window.ethereum, factory: FACTORY });
// ...or a JSON-RPC URL in Node (the SDK's own HTTP client, with rate limiting and retries).
const inNode = await Bazaar.connect({ transport: "https://sepolia-rollup.arbitrum.io/rpc", factory: FACTORY });

• No library at all. In a browser, pass the wallet’s provider (window.ethereum, or the provider an EIP-6963 picker hands you). In Node, pass an RPC URL: the SDK builds its own small HTTP client (JsonRpc), rate limited, retried on transient failures and never printing the URL’s key. Sending then goes through the same wallet with bz.send(wallet, call).
• viem. A viem PublicClient or WalletClient is itself an EIP-1193 transport. Use one for reads and a WalletClient to send, turning each PreparedCall into a transaction request with toTransactionRequest:

// A viem client is an EIP-1193 transport too: reads go through it.
const publicClient = createPublicClient({ chain: arbitrumSepolia, transport: http() });
const bz = await Bazaar.connect({ transport: publicClient, factory: FACTORY });

// Writes come back as PreparedCalls; a viem WalletClient (or wagmi, which wraps one) sends them.
const walletClient = createWalletClient({ chain: arbitrumSepolia, transport: custom(window.ethereum) });
const [user] = await walletClient.requestAddresses();
const eth = await bz.markets.getMarket("ETH/USD");
const call = await bz.trade.claimFees(eth.address, user!);
const sim = await bz.simulate(call);
if (sim.ok) await walletClient.sendTransaction({ ...toTransactionRequest(call), account: user! });

• wagmi. wagmi’s clients are viem clients: pass the connector’s client (from useConnectorClient or getConnectorClient) as the transport, or keep window.ethereum for reads, and send with wagmi’s sendTransaction and toTransactionRequest(call), exactly as with viem above. A connection is bound to a chain, not to an account: connect again when the user switches chain.
• ethers. An ethers provider is not an EIP-1193 object (it has send, not request). Pass the underlying provider (window.ethereum) or an RPC URL to the SDK, and send a call’s to, data and value with an ethers signer if you prefer.

A bot holding its own key uses an RPC URL for reads and a viem WalletClient with a local account to send; Quick Start: a Bot shows it end to end, including the one detail that trips people up (the account field).

TypeScript

The package ships its own declarations (dist/index.d.ts). It is written with strict on and works best in a project that has it on too. The settings that matter:

Every protocol quantity is a bigint, which JSON.stringify refuses: convert to a decimal string (formatUnits18, or String(x)) before putting one in JSON, a URL or framework state that serializes. See Units & Constants.

Installing the Keeper

The keeper is a Node 20+ program with a command-line tool, bazaar. Once published:

npm install -g @liberta-labs/bazaar-keeper
bazaar keeper init

Until then, run it from the repository you built above:

cd bazaar-sdk
npx bazaar keeper init      # asks for the network, RPC, subgraph, price endpoint, wallet, jobs and markets
npx bazaar keeper doctor    # checks every connection, the wallet's ETH, and the jobs

The repository’s Dockerfile builds the same keeper as a container. The whole setup, wallets and configuration are in Setting Up a Keeper; using its engine from your own code is in The Keeper as a Library.

Next

• Quick Start: a Frontend or Quick Start: a Bot.
• Core Concepts, before building anything larger.
• Connecting, for every connection option.

Quick Start: a Frontend

This walkthrough builds a working trading page with no framework: it connects the user’s wallet, lists Bazaar’s markets with their prices and status, shows the user’s position on one, deposits collateral, and places a limit order, simulating every transaction before the wallet is asked to sign. At the end the page follows the account live. It is one TypeScript file and one HTML file, about 200 lines in all.

You need a browser wallet (MetaMask, Rabby, …) on Arbitrum Sepolia with a little ETH for gas and some of the deployment’s USDC, the deployment’s factory address (Bazaar’s deployments page), and a way for your page to get Pyth Pro prices without holding the API key: an endpoint of your backend that mints short-lived tokens from it (see Connecting).

1. Create the Page

npm create vite@latest bazaar-demo -- --template vanilla-ts
cd bazaar-demo
npm install @liberta-labs/bazaar-sdk viem

Until the SDK is on npm, install it from the repository instead, as in Installation.

Replace index.html with a page that has a few named elements:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Bazaar demo</title>
  </head>
  <body>
    <button id="connect">Connect wallet</button>
    <select id="market"></select>
    <pre id="position"></pre>

    <form id="deposit">
      <input name="amount" placeholder="USDC to deposit" />
      <button>Deposit</button>
    </form>

    <form id="order">
      <select name="side"><option value="buy">Buy</option><option value="sell">Sell</option></select>
      <input name="size" placeholder="Size" />
      <input name="price" placeholder="Limit price" />
      <button>Place limit order</button>
    </form>

    <p id="status"></p>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

Everything below goes into src/main.ts, in the order shown (delete what Vite put there). The complete file is docs/examples/getting-started/frontend.ts in the SDK’s repository.

2. Configure

const FACTORY: Address = "0x0000000000000000000000000000000000000000"; // from Bazaar's deployments page
const CHAIN_ID = 421614; // Arbitrum Sepolia
const TOKEN_URL = "/api/pyth-token"; // your backend mints short-lived Pyth Pro tokens: never a Pyth key in a bundle
const pythToken = cachedToken(() => fetch(TOKEN_URL).then((r) => r.json())); // answers { token, expiresAt }

The SDK reads everything else (the lens, the terminator, the oracle, USDC, the markets and their feeds) from the factory. The price endpoint serves the signed Pyth updates that order calls carry and the feed symbols the market list labels markets with; never put a Pyth API key in code a browser downloads.

3. Two Helpers

const el = <T extends HTMLElement = HTMLElement>(id: string) => document.getElementById(id) as T;
const status = (text: string) => {
  el("status").textContent = text; // textContent, never innerHTML: chain and subgraph strings are untrusted
};

/** Run a click handler, showing any failure as one sentence for the user. */
function run(task: () => Promise<void>): void {
  task().catch((e: unknown) => {
    console.error(e);
    status(e instanceof UnitError ? "Enter amounts as plain numbers, like 12.5." : errorMessage(e));
  });
}

let bz: Bazaar;
let user: Address;
let market: markets.MarketInfo;

errorMessage(e) turns whatever a step throws (a decoded contract revert, a wallet rejection, an input the SDK refused) into one sentence for the user. Inputs are parsed with parseUnits18, which throws a UnitError for anything that is not a plain decimal number; the helper words that one itself. Text from the chain or the subgraph (market descriptions, for one) is untrusted: the page only ever sets textContent.

4. Connect

async function connect(): Promise<void> {
  const accounts = (await window.ethereum.request({ method: "eth_requestAccounts" })) as string[];
  user = getAddress(accounts[0]!);
  // Ask the wallet for the right network first: connect() refuses any other chain.
  await window.ethereum.request({ method: "wallet_switchEthereumChain", params: [{ chainId: toHex(CHAIN_ID) }] });
  bz = await Bazaar.connect({ transport: window.ethereum, factory: FACTORY, chainId: CHAIN_ID, prices: { token: pythToken } });
  status(`Connected as ${user}`);
}

eth_requestAccounts asks the wallet for the user’s address. wallet_switchEthereumChain moves the wallet to the right network (it fails with error 4902 when the wallet does not know the chain; add it first with wallet_addEthereumChain). Bazaar.connect then reads the deployment’s wiring from the factory in one batched call and checks the chain: with chainId set, it throws a ConnectError on any other. The result, bz, carries every area of the SDK with this connection bound (bz.markets, bz.account, bz.trade, …). All options are on Connecting.

5. List the Markets

async function showMarkets(): Promise<void> {
  const list = await bz.markets.listMarkets(); // every market the factory deployed, labelled; cached
  const snaps = await bz.markets.marketSnapshots(list); // their live state, read in one batch
  const select = el<HTMLSelectElement>("market");
  select.replaceChildren(
    ...list.map((m) => {
      const s = snaps.get(m.address);
      const price = s ? formatUnits18(s.price.spot, 2) : "?";
      return new Option(`${m.label}  ${price}  ${s?.status ?? ""}  (${m.hours})`, m.address);
    }),
  );
  market = list[0]!;
}

listMarkets() returns every market the factory has deployed, in the factory’s order, with its static facts: label (“ETH/USD”, from the feed’s Pyth symbol), address, hours (“24/7” or “trading-hours”), its feeds. It is cached on the connection, so later calls cost nothing. marketSnapshots(list) reads every market’s live state at one block in two batched calls; here the page shows the pair’s stored price and its status (live, adl, limbo, settling, terminated). Every field is on Markets.

6. Show the Position

async function showPosition(): Promise<void> {
  render(await bz.account.accountSnapshot(market, user)); // one market, one account, two batched reads
}

function render(me: account.AccountSnapshot): void {
  const p = me.position;
  const lines = [
    `${market.label}: ${me.status}`,
    `Collateral: ${formatUnits18(p.collateral, 2)} USDC (withdrawable now: ${formatUnits18(me.maxWithdrawable, 2)})`,
  ];
  if (me.hasPosition && me.health) {
    lines.push(
      `Position: ${p.isLong ? "long" : "short"} ${formatUnits18(p.size)} at ${formatUnits18(p.entryPrice, 2)}`,
      `PnL: ${formatUnits18(me.health.totalPnl, 2)} at ${formatUnits18(me.health.price, 2)}, margin ratio ${me.health.marginRatio.toFixed(2)}`,
    );
  } else {
    lines.push("No position");
  }
  for (const o of me.orders) {
    lines.push(`Order #${o.orderId}: ${o.typeName} ${o.isLong ? "buy" : "sell"} ${formatUnits18(o.remaining)} at ${formatUnits18(o.limitPrice, 2)}`);
  }
  if (me.withdrawalBlocked) lines.push(me.withdrawalBlocked);
  el("position").textContent = lines.join("\n");
}

accountSnapshot(market, user) reads the user’s position on one market and values it at the live price: the position bucket (size, entryPrice, collateral), health (PnL, equity, the margin ratio, below 1 of which anyone may liquidate), the live orders, maxWithdrawable, and withdrawalBlocked, the reason a withdrawal would be refused right now. Amounts are 18-decimal bigints; formatUnits18(x, 2) prints one with two decimals. Every field is on Accounts & Portfolios.

7. Simulate, Then Send

Every write the SDK builds is a PreparedCall: a target, calldata, an ETH value, the account it acts for and a one-line summary. The page runs each one through the same function:

/** Simulate as the user, then let the wallet sign and send, then wait for the receipt. */
async function simulateAndSend(call: PreparedCall): Promise<void> {
  const sim = await bz.simulate(call);
  if (!sim.ok) throw new CallError(sim.error!.message, sim.error); // errorMessage() shows its sentence
  status(`Confirm in your wallet: ${call.summary}`);
  const hash = await bz.send(window.ethereum, call);
  status(`Waiting for ${hash}...`);
  await bz.waitForReceipt(hash); // throws CallError if it reverted
  status(`Done: ${call.summary}`);
}

bz.simulate(call) runs the call as the user with eth_call and estimates its gas. If it would revert, the revert comes back decoded (sim.error.name is the contract’s custom error, and sim.error.message a sentence for the user), and the wallet is never asked. Otherwise bz.send hands the call to the wallet (eth_sendTransaction), and bz.waitForReceipt polls for the receipt, throwing a CallError if the transaction reverted after all. See Sending Transactions.

8. Deposit Collateral

Collateral is per market: each market (each pair contract) holds its own, and pulls the USDC from the wallet itself, so the wallet must allow that pair to take it.

async function deposit(amountText: string): Promise<void> {
  const amount = parseUnits18(amountText); // dollars, 18 decimals
  const funding = await bz.allowance.usdcFunding(user, market.address, amount);
  if (!funding.enoughBalance) {
    const has = allowance.formatUsdcUnits(funding.balance); // USDC's own units: 6 decimals
    return status(`This wallet holds ${has} USDC; the deposit needs ${allowance.formatUsdcUnits(funding.needUsdc)}.`);
  }
  // Each market pulls its own collateral: approve exactly what this deposit needs, if the allowance is short.
  if (funding.approveUsdc > 0n) await simulateAndSend(await bz.allowance.approveUsdc(user, market.address, funding.approveUsdc));
  await simulateAndSend(await bz.trade.depositCollateral(market.address, user, amount));
}

usdcFunding reads the wallet’s USDC balance and its allowance to the pair, and says how much to approve (approveUsdc, in USDC’s own 6-decimal units). approveUsdc builds an approval for exactly that amount; depositCollateral then builds the deposit (at least 5 USDC). A deposit can instead carry a USDC permit, a signature in place of the approval transaction: see Collateral, Approvals & Permits.

9. Place a Limit Order

async function placeLimitOrder(side: string, sizeText: string, priceText: string): Promise<void> {
  const order = {
    orderType: OrderType.Limit,
    isLong: side === "buy",
    size: parseUnits18(sizeText),
    limitPrice: parseUnits18(priceText),
    expirationBlock: (await bz.ctx.chain.blockNumber()) + orders.blocksIn(24 * 3600), // a day of L2 blocks
  };
  // createOrder checks the order as the pair will, and attaches a Pyth print the pair accepts for
  // 3 s: build it right before the wallet prompt, and rebuild it if simulating took too long.
  let call = await bz.trade.createOrder(market.address, user, order);
  const sim = await bz.simulate(call);
  if (!sim.ok) throw new CallError(sim.error!.message, sim.error);
  if (Date.now() / 1000 - (call.priceTime ?? 0) > 2) call = await bz.trade.createOrder(market.address, user, order);
  status(`Confirm in your wallet: ${call.summary}`);
  await bz.waitForReceipt(await bz.send(window.ethereum, call));
  status(`Placed: ${call.summary}`);
}

createOrder checks the order exactly as the pair will (a size and price, a limit within 50% of the market price, at least $5 of notional, an expiry at least about a minute away, the per-user order caps) and throws an InputError naming the field otherwise. It then finds the order’s place in the book and attaches a fresh signed Pyth price, which every order call carries.

That price is the catch: the pair accepts a print at most 3 seconds from the block’s time. The page builds the call right before the wallet prompt and rebuilds it if simulating took long enough that the print is more than 2 seconds old (call.priceTime is its publish time). A user who takes longer than that to approve in the wallet can still see the transaction revert on a quiet market; on an active one, another trade has usually refreshed the pair’s price within the window. Production apps either offer a retry with a freshly built call or trade gasless, where the relayer attaches the price when it submits (Gasless Trading & Relayers). The details are in The 3-Second Price Window.

expirationBlock counts Arbitrum blocks, about four a second: orders.blocksIn(seconds) converts. Every option of every order type is on Placing Orders.

10. Wire the Buttons

const form = (id: string) => new FormData(el<HTMLFormElement>(id));

el("connect").addEventListener("click", () =>
  run(async () => {
    await connect();
    await showMarkets();
    await showPosition();
    follow();
  }),
);
el<HTMLSelectElement>("market").addEventListener("change", (e) =>
  run(async () => {
    market = await bz.markets.getMarket((e.target as HTMLSelectElement).value as Address);
    await showPosition();
    follow();
  }),
);
el<HTMLFormElement>("deposit").addEventListener("submit", (e) => {
  e.preventDefault();
  run(async () => {
    await deposit(String(form("deposit").get("amount")));
    await showPosition();
  });
});
el<HTMLFormElement>("order").addEventListener("submit", (e) => {
  e.preventDefault();
  const f = form("order");
  run(async () => {
    await placeLimitOrder(String(f.get("side")), String(f.get("size")), String(f.get("price")));
    await showPosition();
  });
});

11. Keep It Current

// Keep the position current. Events for this account (fills, orders, collateral) and a
// timer refresh both re-read the snapshot; call stop() when the view goes away.
let watch: { stop(): void } | null = null;
function follow(): void {
  watch?.stop();
  watch = bz.live.watchAccount(user, [market], (u) => {
    if (u.type === "account") render(u.snapshot);
    if (u.type === "error") console.warn("live updates:", u.error);
  });
}

watchAccount follows the chain (on new-head notifications where the wallet’s provider pushes them, otherwise polling the head about once a second) and delivers the account’s own events and a refreshed AccountSnapshot for each market an event touched, plus one every 15 seconds as funding accrues and clocks run. The page re-renders from the snapshot it is handed, with no read of its own. See Live Updates.

12. Run It

npm run dev

Open the page, connect, deposit 20 USDC, and place a buy a little under the market price. The order appears in the position view as soon as the transaction lands.

What Can Go Wrong

Next

• Core Concepts: what is behind each step above.
• Live Prices, to show a streaming price next to each market.
• Previews, to show the fees, margin and liquidation price of an order before it is placed.
• Managing Orders, to amend and cancel.

Quick Start: a Bot

This walkthrough writes a Node script that trades with its own key: it connects over an RPC URL, reads a market and its own account, tops up its collateral with a USDC permit, rests a post-only limit order and cancels it. Transactions are signed in the script with a viem WalletClient; the SDK builds and checks them, and never sees the key.

It is the skeleton every Bazaar bot starts from. Building a Bot goes further: live prices, events, nonces, many orders at once.

What You Need

• Node 20 or later, and a project with the SDK and viem installed (Installation).
• A private key for the bot, holding ETH for gas (and the Pyth fee that order calls send) and USDC on the deployment’s network.
• An RPC URL. Any JSON-RPC provider works; a key inside the URL (Alchemy’s /v2/<key>, a ?key= query) is never printed by the SDK.
• A Pyth Pro API key, for signed Pyth prices. A server may hold the key itself.
• Node 22 or later if the bot streams prices (the stream runs over the global WebSocket); on Node 20 give the price client a WebSocket constructor, such as the ws package’s.
• The deployment’s factory address, from Bazaar’s deployments page.

The script reads them from the environment:

RPC_URL=https://arb-sepolia.g.alchemy.com/v2/...
BAZAAR_FACTORY=0x...
PYTH_PRO_API_KEY=...
BOT_PRIVATE_KEY=0x...
MARKET=ETH/USD                # optional

Keep them in a .env file that is never committed, and load it with node --env-file=.env (Node 20.6+) or your process manager.

The complete script is docs/examples/getting-started/bot.ts in the SDK’s repository, with the wallet helper in local-wallet.ts beside it. Compile it with tsc, or run it with a TypeScript runner.

1. The Key and the Environment

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`set ${name} in the environment`);
  return value;
}

const RPC_URL = env("RPC_URL"); // any JSON-RPC provider; a key in the URL never appears in errors
const account = privateKeyToAccount(env("BOT_PRIVATE_KEY") as Hex); // the key stays in this process
const me = account.address;

privateKeyToAccount makes a viem local account: it signs in this process, and nothing about the key leaves it.

2. Connect

const bz = await Bazaar.connect({
  transport: RPC_URL, // reads through the SDK's own JSON-RPC client (rate limited, retried)
  factory: env("BAZAAR_FACTORY") as Address,
  prices: { token: env("PYTH_PRO_API_KEY") }, // Pyth Pro: a server may hold the API key itself
});

const chain = [arbitrum, arbitrumSepolia, anvil].find((c) => c.id === bz.chainId);
if (!chain) throw new Error(`no viem chain for chain id ${bz.chainId}`);
const wallet = createWalletClient({ account, chain, transport: http(RPC_URL) }); // signs locally

With a URL as its transport, the SDK reads through its own JSON-RPC client: 25 requests a second at most, a 30-second timeout, and up to three retries with doubling delays on transient failures (never on a send). prices holds the Pyth Pro token; on a server it can be the API key itself, sent as Authorization: Bearer <key>. Connecting has every option, and how to change those defaults with a JsonRpc of your own.

The WalletClient is what signs and sends. It needs the chain object for the network (viem/chains has Arbitrum One, Arbitrum Sepolia and Anvil); the script picks it from the chain id the connection found.

3. Send a PreparedCall

Every write the SDK builds is a PreparedCall (to, data, value, from, summary, …). The bot sends each one the same way:

/** Simulate as the bot, send with the WalletClient, wait for the receipt. */
async function send(call: PreparedCall): Promise<Receipt> {
  const sim = await bz.simulate(call);
  if (!sim.ok) throw new CallError(`${call.summary}: ${sim.error!.message}`, sim.error);
  const hash = await wallet.sendTransaction({
    ...toTransactionRequest(call), // to, data, value (the Pyth fee, if any)
    account, // the local account itself: given only its address, viem would ask the node to sign
    ...(sim.gas !== null ? { gas: (sim.gas * 12n) / 10n } : {}), // the simulation's estimate, plus 20%
  });
  const receipt = await bz.waitForReceipt(hash); // throws CallError if it reverted
  console.log(`${call.summary}: ${hash} (block ${receipt.blockNumber})`);
  return receipt;
}

/**
 * For calls that carry a Pyth print (orders, amendments, withdrawals with a position): the pair
 * takes a print at most 3 s from the block's time, so build, simulate and send in one go, and
 * rebuild when the print is already more than 2 s old.
 */
async function sendPriced(build: () => Promise<PreparedCall>): Promise<Receipt> {
  for (let attempt = 1; ; attempt++) {
    const call = await build();
    if (attempt < 3 && Date.now() / 1000 - (call.priceTime ?? 0) > 2) continue;
    return send(call);
  }
}

• Simulate first. bz.simulate(call) runs the call as the bot with eth_call and, when it passes, estimates its gas. A revert comes back as sim.error: the contract’s custom error, decoded, with a sentence saying what happened. Nothing is sent, and no gas is spent.
• Then send with the WalletClient. toTransactionRequest(call) gives viem’s to, data and value (the ETH a call with a price update must send for Pyth’s fee), and account, set to the call’s from address. Override account with the local account object. viem treats an account given as a bare address as a JSON-RPC account and asks the node to sign with eth_sendTransaction, which a hosted RPC refuses; given the local account, it signs here and sends the raw transaction. Passing the simulation’s gas estimate (with some headroom) saves viem a second estimate.
• Wait for the receipt. bz.waitForReceipt(hash) polls every 500 ms for up to two minutes and throws a CallError if the transaction reverted or never landed.

Calls that carry a price. Order creation, amendments, trigger executions and some withdrawals attach a signed Pyth print, and the pair accepts a print at most 3 seconds from the block’s time. sendPriced builds such a call, and rebuilds it (twice at most) when the print it got is already more than 2 seconds old; a bot signs locally, so the whole build, simulate, sign and send takes well under a second after that. See The 3-Second Price Window.

4. Read the Market and the Account

async function readState(label: string) {
  const market = await bz.markets.getMarket(label); // a label, a pair address or a pair id
  const snap = await bz.markets.marketSnapshot(market);
  console.log(
    `${market.label} is ${snap.status}: stored price ${formatUnits18(snap.price.spot, 2)} (${snap.price.age} s old),` +
      ` funding ${formatUnits18(snap.funding.currentRatePerHour * 100n, 4)}%/h, max leverage ${snap.margin.maxLeverage ?? "-"}x`,
  );
  if (snap.marketOrdersDisabled) console.log(snap.reasons.marketOrdersDisabled);

  const mine = await bz.account.accountSnapshot(market, me);
  console.log(
    `collateral ${formatUnits18(mine.position.collateral, 2)} USDC, wallet ${formatUnits18(fromUsdcUnits(mine.wallet.usdcBalance), 2)} USDC,` +
      ` ${mine.hasPosition ? `position ${formatUnits18(mine.position.size)}` : "flat"}, ${mine.orders.length} open orders`,
  );
  return { market, snap, mine };
}

getMarket accepts a label, a pair address or a pair id. marketSnapshot reads the market’s state at one block: its status, the pair’s stored price and its age, funding, margin rates, open interest, insurance, and flags such as marketOrdersDisabled with the reason for each. accountSnapshot reads the bot’s position, collateral, orders, what it can withdraw, its claimable fees and its wallet’s USDC balance (in USDC’s own 6-decimal units, hence fromUsdcUnits before printing). The fields are on Markets and Accounts & Portfolios.

5. Top Up Collateral With a Permit

Collateral is per market, and the market pulls it from the wallet, so the wallet must allow it. An approval is a transaction of its own; a USDC permit (ERC-2612) is a signature the deposit carries instead:

async function topUp(pair: Address, collateral: bigint): Promise<void> {
  const target = parseUnits18("50"); // keep $50 of collateral on this market
  if (collateral >= parseUnits18("20")) return;
  const amount = target - collateral;
  // A USDC permit instead of an approve transaction: a signature the deposit carries.
  const permit = await bz.permits.signPermit(localWallet(account), { owner: me, spender: pair, value: toUsdcUnitsCeil(amount) });
  await send(await bz.trade.depositCollateral(pair, me, amount, { permitData: permit.permitData }));
}

permits.signPermit builds the permit’s typed data and asks a wallet to sign it with eth_signTypedData_v4, as it would ask a browser wallet. A viem WalletClient would forward that request to the RPC node, which cannot sign, and the SDK has no local-key wallet of its own, so the bot uses a few lines that answer the request with the local account:

/**
 * Answers the two requests the SDK's signing helpers make, eth_accounts and eth_signTypedData_v4,
 * by signing with `account`'s key in this process. Everything else is refused with EIP-1193's
 * "unsupported method" (4200): send transactions with a viem WalletClient.
 */
export function localWallet(account: LocalAccount): Transport {
  return {
    async request({ method, params = [] }) {
      if (method === "eth_accounts" || method === "eth_requestAccounts") return [account.address];
      if (method === "eth_signTypedData_v4") {
        const [signer, typedData] = params as [string, string]; // the address, then the typed data as JSON
        if (getAddress(signer) !== account.address) {
          throw Object.assign(new Error(`this wallet signs only as ${account.address}`), { code: 4100 });
        }
        return account.signTypedData(JSON.parse(typedData));
      }
      throw Object.assign(new Error(`${method} is not supported by this wallet`), { code: 4200 });
    },
  };
}

The SDK checks every signature it gets back: it must recover to the signer, as a 65-byte low-s ECDSA signature. The same helper signs gasless requests (relay.signRelayed); see Gasless Trading & Relayers.

The permit covers toUsdcUnitsCeil(amount): the deposit is in 18 decimals, USDC counts in 6, and a permit must cover the pull rounded up. The minimum deposit is 5 USDC.

6. Place an Order and Cancel It

async function placeOrder(pair: Address): Promise<bigint | null> {
  const { price } = await bz.trade.livePairPrice(pair); // the composed Pyth price the pair will see
  const limitPrice = (price.spot * 98n) / 100n; // 2% under the market: it rests rather than fills
  const size = (parseUnits18("20") * BAZAAR_SCALE) / limitPrice; // about $20 of notional (the minimum is $5)
  const expirationBlock = (await bz.ctx.chain.blockNumber()) + orders.blocksIn(3600); // an hour of L2 blocks

  const receipt = await sendPriced(() =>
    bz.trade.createOrder(pair, me, { orderType: OrderType.Limit, isLong: true, size, limitPrice, expirationBlock, isPostOnly: true }),
  );
  // The new order's id is in its OrderUpdated event (action 0: created).
  for (const log of receipt.logs) {
    const e = live.decodeLiveLog(log);
    if (e?.source === "pair" && e.name === "OrderUpdated" && e.args.owner === me && e.args.payload.action === 0) return e.args.orderId;
  }
  return null;
}

async function cancel(pair: Address, orderId: bigint): Promise<void> {
  await send(await bz.trade.cancelOrders(pair, me, [orderId])); // any bounty returns to claimable fees
}

trade.livePairPrice fetches the signed update and composes the price the pair itself will compute from it (spot, and the confidence band). The order is a post-only limit 2% under it, so it rests in the book as a maker; a post-only order that would cross is canceled instead of filling. Its size is about $20 of notional (size × price / 1e18; the minimum is $5), and it expires in an hour of Arbitrum blocks (orders.blocksIn(3600), about four blocks a second).

The pair numbers orders itself; the new order’s id is in the OrderUpdated event of the receipt, which live.decodeLiveLog turns into a typed event (payload.action 0 is “created”). Canceling takes a list of up to 200 ids. Every order option is on Placing Orders, canceling and amending on Managing Orders.

7. Run It

async function main(): Promise<void> {
  const { market, mine } = await readState(process.env.MARKET ?? "ETH/USD");
  await topUp(market.address, mine.position.collateral);
  const orderId = await placeOrder(market.address);
  if (orderId === null) throw new Error("the order did not rest (a post-only order that would cross is canceled)");
  console.log(`order #${orderId} is resting`);
  await cancel(market.address, orderId);
  await readState(market.label);
}

main().catch((e: unknown) => {
  // The SDK's errors say what happened in their message (with any URL's key masked). A user-facing
  // app would show errorMessage(e) instead; an operator wants the detail.
  console.error(e instanceof Error ? `${e.name}: ${e.message}` : e);
  process.exitCode = 1;
});

A run prints the market and the account, then one line per transaction:

ETH/USD is live: stored price 3012.41 (2 s old), funding 0.0012%/h, max leverage 20x
collateral 0 USDC, wallet 250 USDC, flat, 0 open orders
Deposit 50 USDC as collateral: 0x5c1d... (block 98211873)
Buy 0.006774722395125601 at 2952.16378 (limit, GTC, post-only): 0x8e02... (block 98211881)
order #4182 is resting
Cancel order #4182: 0x1f7a... (block 98211889)
...

(The figures are illustrative.) A summary prints every amount exactly, never rounded: it is what the transaction does.

If anything fails, the script prints the error’s name and message and exits with code 1. The SDK’s messages are written to be read: a refused input names its field, a decoded revert says what happened, and a URL is printed with its key masked. A user-facing app shows errorMessage(e) instead (see Errors & Messages).

What Can Go Wrong

Next

• Core Concepts.
• Building a Bot: live prices and events, nonce handling, quoting many orders.
• Live Updates, to react to fills instead of polling.
• Errors & Messages.

Core Concepts

The SDK is built around a handful of ideas that every page after this one assumes: a connection bound to one deployment, functions grouped by area, writes returned as prepared calls, one rule for units, a price window, errors written for users, and a short list of things it caches. This page explains each.

The Connection

A connection is a BazaarContext: one chain, one Bazaar deployment, and the optional services some functions need. Bazaar.connect(options) creates one (see Connecting); it is bz.ctx.

Nothing in a context changes after it is made. A connection is bound to a chain, not to a user: every function takes the user’s address as an argument, so one connection serves any number of accounts. When the wallet switches chain, connect again.

The Facade and the Namespaces

Each area of the SDK is a module of plain functions that take the context first: markets.getMarket(ctx, "ETH/USD"), trade.createOrder(ctx, pair, user, order). The Bazaar object binds the context into every one of them, so the same calls read bz.markets.getMarket("ETH/USD") and bz.trade.createOrder(pair, user, order).

// The facade: one object, the connection bound into every function.
const bz = await Bazaar.connect({ transport: window.ethereum, factory: FACTORY });
const eth = await bz.markets.getMarket("ETH/USD");

// The same functions per area, taking the context first: what a library or a tree-shaken bundle uses.
const ctx = await connect({ transport: window.ethereum, factory: FACTORY });
const same = await markets.getMarket(ctx, "ETH/USD");

// Moving between them: bz.ctx is the context, and Bazaar.from wraps one.
const again = Bazaar.from(ctx);
console.log(bz.ctx.lens, again.deployment.usdc, same.label);

// Pure helpers, which need no connection, live only on the namespaces.
const expiry = (await bz.ctx.chain.blockNumber()) + orders.blocksIn(3600);

Use the facade in an application: it is shorter and cannot pass the wrong context. Use the namespaces in a library that takes a context from its caller, and for the pure helpers (packing, validation, formatting, type strings), which need no connection and are therefore not on bz: orders.blocksIn, orders.buildOrderSpec, format.formatUsd. Importing Bazaar brings every area into the bundle; an app that imports only a few namespace functions lets the bundler drop the rest. The facade also has bz.simulate, bz.send, bz.waitForReceipt, bz.livePrices, bz.chainId and bz.deployment.

The most used names (Bazaar, connect, errorMessage, the unit helpers, the constants, the error classes, the low-level chain and price clients) are exported flat from the package. The full list is in the API Index.

Prepared Calls: Simulate, Then Send

The SDK never sends anything and never holds a key. Every builder (trade.createOrder, trade.depositCollateral, allowance.approveUsdc, insurance.depositToInsurance, …) returns a PreparedCall, for any contract:

const call = await trade.createOrder(ctx, eth.address, user, {
  orderType: OrderType.Limit, isLong: false, size: parseUnits18("1"), limitPrice: parseUnits18("3100"), expirationBlock: expiry,
});
call.action; // "createOrder"
call.to; // the pair
call.data; // the calldata
call.value; // ETH for the Pyth update fee (wei)
call.from; // the user it acts for
call.summary; // "Sell 1 at 3100 (limit, GTC)"
call.priceTime; // the attached print's publish time (unix seconds)
call.pullsUsdc; // USDC it takes from the wallet (18 decimals): a trigger order's bounty, a deposit

const sim = await bz.simulate(call); // eth_call as `from`, then eth_estimateGas
if (sim.ok) console.log(`gas ${sim.gas}`);
else console.log(sim.error!.name, sim.error!.message); // the decoded custom error, and a sentence for the user

The flow is the same for every write:

1. Build. The builder checks its inputs against what it can read (the account’s orders and position, the book, the live price) and throws an InputError naming the field for anything the contract would refuse. Before naming a market it asks the factory whether that address is one of its pairs (requirePair), so an address from a link cannot pass off another contract as a market.
2. Simulate, as the user: bz.simulate(call) runs it with eth_call and estimates its gas. A revert comes back decoded, with a sentence for the user, before the wallet is asked anything.
3. Show the summary, and what the call costs: value, pullsUsdc.
4. Send with the user’s wallet: bz.send(wallet, call) over any EIP-1193 provider, or toTransactionRequest(call) for a viem or wagmi client, or a bot’s own key.
5. Wait: bz.waitForReceipt(hash) throws a CallError if the transaction reverted.

Signatures follow the same principle: gasless requests and USDC permits are typed data the SDK asks the wallet to sign with eth_signTypedData_v4, so the wallet shows the user every field, and the SDK checks that the signature recovers to the signer before it uses it. See Sending Transactions and Gasless Trading & Relayers.

Units

One rule covers the whole SDK:

• Protocol quantities are bigint: prices, sizes, notionals, collateral, fees, rewards, funding indices and rates, scores, basis-point rates.
• Amounts are in 18 decimals (“BAZAAR precision”): 1e18 is $1, or one unit of the traded asset. parseUnits18("12.5") and formatUnits18(x, 2) convert to and from text.
• USDC’s own calls are in 6 decimals, as the token counts: wallet balances and allowances (wallet.usdcBalance, usdcFunding, approveUsdc) and permits. The pair floors what it moves to whole micro-USDC. Convert with toUsdcUnits, toUsdcUnitsCeil (for an allowance that must cover a pull) and fromUsdcUnits. A name says USDC when it is in 6 decimals.
• Times, blocks, counts and enum values are number: Unix seconds, block numbers, order types. The one exception is an order spec’s expirationBlock, a bigint because a take-profit or stop-loss carries 2^64 − 1 (“never”), which a number cannot hold. Order inputs accept either.
• Ratios for display are number: a margin ratio, a leverage, a confidence in basis points.

const size = parseUnits18("0.25"); // 250000000000000000n: 0.25 ETH
const price = parseUnits18("3012.5"); // $3,012.50
const notional = (size * price) / 10n ** 18n; // $753.125, still 18 decimals
formatUnits18(notional, 2); // "753.12" (rounded toward zero)
toUsdcUnits(notional); // 753125000n: what USDC's own calls count (6 decimals), floored
fromUsdcUnits(1_000_000n); // 1000000000000000000n: one USDC back in 18 decimals

Every conversion and constant is on Units & Constants.

Price Updates and the 3-Second Window

Bazaar prices every market from Pyth. A call that needs the price (creating or amending an order, firing a trigger, a withdrawal with a position, an insurance exit, liquidations) carries a signed Pyth Pro update in its calldata, and the pair accepts a price generated at most 3 seconds from the block’s time (MAX_PRICE_STALENESS). The pair has the attached update verified and uses its price; a call that carries none runs on the pair’s own stored price while that is at most 3 seconds old, and otherwise reverts (or, on a market with trading hours, runs on its stored price where that call allows it). See Oracle.

What this means in code:

• Builders that attach a price need a price source on the connection (prices); without one they throw a ConnectError.
• call.value is the fee Pyth charges to verify the update; the pair refunds what it does not spend.
• call.priceTime is the print’s publish time. The clock starts when the call is built: build right before sending, and rebuild a call whose print is more than a second or two old.
• A human approving in a wallet can be slower than 3 seconds; on a quiet market such a call may revert on chain. Gasless calls avoid this: the relayer attaches the price when it submits.

Reads are different: they never need a print to be fresh. A market snapshot reports the pair’s stored price and its age; an account snapshot values the position at the freshest price it can get (the caller’s, a live stream’s, one Pyth Pro request, or the stored one) and says which (price.source). Live Prices streams the composed price of every market with a fresh flag.

User-Facing Errors

Failures come in a few shapes, and errorMessage(e) turns any of them into one sentence for the user:

try {
  const c = await bz.trade.createOrder(eth.address, user, { orderType: OrderType.Market, isLong: true, size: parseUnits18("2") });
  const s = await bz.simulate(c);
  if (!s.ok) throw new CallError(s.error!.message, s.error);
  await bz.waitForReceipt(await bz.send(window.ethereum, c));
} catch (e) {
  if (e instanceof InputError) console.log(`field ${e.field} was refused before anything was built`);
  console.log(errorMessage(e)); // here: "maxSlippageBp: Set a slippage limit between 0.01% and 10%."
}

errorMessage falls back to “Something went wrong. Please try again.” for anything it does not recognize (a ConnectError, an endpoint failure, a UnitError from parsing a number), and never shows a raw URL. Log the error itself for the detail. See Errors & Messages.

Browser Safety

The SDK is written to run in a page an attacker can link to and feed data:

• No secrets in the bundle. A Pyth Pro API key or a subgraph key in browser code is public. Give prices short-lived tokens your backend mints from the key (see Connecting), or leave prices to a relayer.
• Only Pyth’s signature counts. Prices are read from the signed update itself, and a connection refuses updates not signed by a signer the deployment’s Pyth verifier trusts.
• Keys are masked. Every error and display string built from an RPC, price or subgraph URL masks the parts that may be a key (redactUrl), and a Pyth Pro token never appears in one.
• Untrusted addresses are checked. Every builder confirms a pair with the factory (requirePair) before building a call, an approval, a permit or a gasless request for it.
• Untrusted text stays text. Market descriptions and proposal texts come from the chain or the subgraph: render them as text, never as HTML. Market labels come from Pyth’s feed symbols, never from a description.
• Approvals are exact unless you ask for unlimited ones explicitly.
• Signatures are checked. A signature that does not recover to the signer (a smart-contract wallet signing through ERC-1271, say) is refused before use, since the pair would act for whatever address it recovers.
• Clocks are checked. Deadlines for permits and gasless requests are counted from the lower of the latest block’s time and this device’s clock, and the SDK refuses to ask for a signature (ClockSkewError) when the two differ by more than two minutes (local development chains excepted).

More in Security Notes for Integrators.

What Is Cached

The SDK reads the chain when you ask and keeps very little. What it keeps, it keeps per connection (per context object), except where noted:

Nothing else is cached. Snapshots, books, portfolios, nonces, balances and allowances are read fresh on every call, at one block, and returned as plain objects your UI can keep. A LivePrices stream holds the latest print per feed in memory, and a watcher holds the last snapshots it delivered; both are released when you stop them.

Next

• Connecting: every connection option.
• Markets and Accounts & Portfolios: what reads return.
• Sending Transactions: the write path in depth.

What the Keeper Does

Bazaar needs someone to do its upkeep: liquidate positions that fall below their maintenance margin, fire stop orders when the price reaches them, sell the insurance vault’s inherited inventory, run ADL auctions, keep quiet markets’ prices fresh, settle terminated markets. None of it is restricted. Anyone may call these functions, and most of them pay the caller a bounty in USDC.

A keeper is a program that does this work for its bounties. @liberta-labs/bazaar-keeper is one: it watches the markets you choose, works out which calls are due, simulates each one against the chain to learn exactly what it would earn, and sends the ones worth sending from your own wallet. It runs as a command-line program (bazaar keeper start), in a container, or inside your own TypeScript service (The Keeper as a Library).

This page explains what the keeper does and what it needs. Setting Up a Keeper takes you from nothing to a running keeper.

The Jobs

Each job is one kind of upkeep. You switch each one on in the config and choose its markets.

Every bounty is credited to your wallet’s claimable balance on the market that paid it, and stays there until it is claimed with claimFees() on that market. The collect job does that for you. Every payout from the insurance fund is capped at the fund’s free capital. The full rules are in Bazaar’s Earning on Bazaar and Parameters.

Besides the jobs, the keeper runs manual operations when you ask for them: terminating a market at its scheduled cutoff or after its oracle died, settling UMA claims and insurer votes, finalizing a termination, and the factory’s listing and identifier-upgrade housekeeping. They pay nothing and are never sent on their own. bazaar keeper opportunities lists the ones available now (Manual Operations).

Relaying signed meta-transactions is not a keeper job. Governance actions that post a bond or vote (termination and listing proposals, insurer votes) are not either: the SDK builds those for a person to sign (Termination & Settlement, Listing Markets).

How the Keeper Decides

The keeper never sends a call on an estimate. For each call it is about to make it does this:

1. Find candidates. It keeps a local index of every open position and live order, built from the subgraph or from the chain’s logs and kept current from each new block’s logs. On each new price print and on each tick (every engine.tickSeconds, 0.5 s by default) every job checks its markets locally: is a position below its requirement at the live price, has a stop’s trigger been reached, does the vault hold inventory. Liquidation and triggers make no RPC request until a position or order crosses at the live price.
2. Re-read from the chain. The index only finds candidates. Before acting, the job re-reads each one from the chain (the position’s bucket, the order record) and drops what no longer qualifies.
3. Simulate through the probe. The call is run with eth_call from a small contract placed at a fixed address by a state override. Rewards accrue to the caller, so the difference in the probe’s claimable balance before and after the call is exactly what the call would earn, with every cap the contracts apply. A call that reverts in simulation is never sent.
4. Price the gas. The gas comes from eth_estimateGas of the real transaction from the real wallet, priced at the current base fee and the live ETH/USD print.
5. Apply the spend policy. A paid call goes out when reward − gas ≥ minProfitUsd and reward ≥ gas × gasSafetyMultiplier. A call that fails that test is sent only if you chose to take losses on that job, within per-call and daily caps. Every call, whatever decided it, must fit the daily spend caps and the fee ceilings. Budgets & Losing Calls has every rule.
6. Send and book. The transaction goes out with priority fee 0 (Arbitrum’s sequencer orders transactions first come, first served). When its receipt arrives, the reward and claim it logged are written with the gas it actually cost to the earnings ledger, which bazaar keeper earnings reads.

A dry run (--dry-run) takes the same path and stops before sending, so what it reports is what a real run would do.

What You Need

How Fast It Is

Liquidations and trigger executions race other keepers, and what makes them due is usually a price move. So besides the tick, these two jobs plan a market the moment a newer print for one of its legs arrives. Each print plans only the markets whose feeds moved, checks every position or order against the live price locally, and makes RPC requests only for real candidates. The package README gives a median of 0.5 ms from print to planned with 200 markets of 2,000 positions each, and the end-to-end test reports the keeper’s latency from a price move to its send.

Prints and the tick share one plan per job and market at a time: a print that arrives during a plan queues one more plan, which then judges by the newest print. While the index is catching up (a sync step 64 or more blocks behind the head, as after a restart), the print path waits, so it never plans from a half-replayed index.

Latency wins races on Arbitrum, not fees. To be fast:

• give the latency-critical jobs (liquidation, triggers) a wallet of their own, so their sends never wait behind another job’s nonce (Wallets & Secrets);
• on Arbitrum One, submit straight to the sequencer with rpc.send: sequencer;
• run close to your RPC and price endpoint.

Related Pages

• Setting Up a Keeper: install, configure, check, fund, start.
• The Jobs: each job in depth.
• Budgets & Losing Calls: the spend policy.
• Configuration Reference: every option.

Setting Up a Keeper

This page takes you from nothing to a running keeper: install it, answer the setup wizard, check every connection with doctor, fund the wallet, start it, and read what it is doing. It assumes Arbitrum Sepolia; the steps are the same on Arbitrum One. To try everything on a local chain first, see Testing Locally with Anvil.

Before you start, have at hand:

• an Arbitrum RPC URL that supports eth_call state overrides (most hosted providers’ URLs carry your API key; the wizard keeps them out of the config file);
• a Pyth Pro access token (from Pyth; a Pyth Core or Hermes key does not work), or the URL of another Pyth Pro compatible price service;
• the factory address of the Bazaar deployment you want to keep (the network presets carry no official address yet);
• a little ETH on that network for gas.

1. Install

The keeper needs Node 20 or later. Once the packages are published:

npm install -g @liberta-labs/bazaar-keeper
bazaar --help

Until then, install from the repository and run the built CLI with Node:

git clone https://github.com/liberta-labs/bazaar-sdk && cd bazaar-sdk
npm install && npm run build
alias bazaar="node $PWD/packages/keeper/dist/cli/main.js"
bazaar --help

The rest of this guide writes bazaar. Installation covers the SDK package as well. To run in a container instead, see Running in Production: the wizard runs inside the container the same way.

Make a directory for the keeper and work in it. Everything the keeper keeps (its config, .env, keystore and state) ends up there:

mkdir -p ~/keeper && cd ~/keeper

2. Answer the Wizard: bazaar keeper init

bazaar keeper init

The wizard asks what it cannot discover, checks each answer as you give it, and writes two files: bazaar-keeper.yaml (or the path given with -c) and a .env beside it. Secrets and every URL you type go to .env only; the YAML refers to them as ${NAME}. It needs an interactive terminal: run without one, it stops with init needs an interactive terminal (copy bazaar-keeper.example.yaml and edit it instead). Ctrl-C at any question cancels and writes no config.

If the config file already exists, the first question is whether to replace it (default no; answering no leaves everything as it was).

Network

Factory Address

Asked for a custom network, and for any preset without an official factory (at present all of them). It must be an address; it is written as factory: "0x…". Everything else (the lens, the terminator, the oracle, the markets and their feeds) is read from the factory.

For a custom network the wizard then asks the factory’s deployment block. Leave it empty and the keeper finds the block on chain when it needs it (a first start without a subgraph); give it and it is written as startBlock. See Configuration Reference.

RPC URL

Your node’s HTTPS URL (on Anvil the default is http://127.0.0.1:8545). The wizard calls eth_chainId and asks again until the URL answers with the network’s chain id, printing what went wrong (✘ that RPC is on chain 1, not 421614). It writes rpc.http: ${RPC_HTTP_URL} and puts the URL in .env as RPC_HTTP_URL.

On Arbitrum One, which has a sequencer endpoint preset, it then asks whether to submit transactions straight to the sequencer (default yes), which writes rpc.send: sequencer.

Subgraph

The subgraph only makes the first start faster. Without one, the first start replays every Bazaar log from the factory’s deployment block; later starts resume from the snapshot either way.

Price Endpoint

It then reads an ETH/USD print (Pyth Pro feed 2) from the request API to check the endpoint and the token: ✔ ETH/USD print 3,012.45, or a warning (⚠ could not read a print yet: …) that does not stop the wizard. The channel is left at its default, fixed_rate@200ms; set prices.channel to change it (Configuration).

Keeper Wallet

A new keystore prints its address: ✔ 0x14dC…9955 encrypted at /home/me/keeper/keys/default.json. Fund it with a little ETH for gas. The config gets:

wallets:
  default:
    type: keystore
    path: /home/me/keeper/keys/default.json

Then it asks whether to store the keystore password in .env (default yes). Yes adds password: ${KEEPER_KEYSTORE_PASSWORD} and puts the password in .env; for an existing keystore it asks for the password first (it does not check it: doctor will). No means the keeper asks for the password at every start, which only works in a terminal: a service or a detached container cannot answer. See Wallets & Secrets.

Jobs

A checklist of the eight jobs, each with what it pays. All are checked except sweepExpired, which pays nothing. If you pick any job besides collect, the wizard lists the factory’s markets.

Losses

If you picked a job that can lose money (anything but collect and sweepExpired), it asks whether any job should also send calls that cost more than they earn. Default no. Yes asks which jobs, the largest loss per call (default 0.05 USD) and the daily loss budget per job (default 1), and writes allowLoss: true, maxLossUsdPerCall and lossBudgetUsdPerDay under each chosen job. See Budgets & Losing Calls.

Markets for Each Job

For each picked job except collect, once markets were found:

Chosen markets are written by address because labels are not unique: a market relisted after a termination keeps its label, and a composite is labelled after its base. If the markets could not be listed, the wizard warns and every job runs on all markets.

Collect

If you picked collect: the balance at which a market is claimed (default 5 USD, written as thresholdUsd), and optionally an address to forward collected USDC to (forwardTo).

What It Writes

The config ends with state.dir set to state/ beside it, so the snapshot, the earnings ledger and the status file live in the same directory. Paths are written absolute, so the keeper can be started from anywhere. A typical result:

# Written by bazaar keeper init. Secrets live in .env next to this file.

network: arbitrum-sepolia
factory: "0x0000000000000000000000000000000000000000"

rpc:
  http: ${RPC_HTTP_URL}

subgraph:
  url: none

prices:
  endpoint: pyth
  token: ${PYTH_PRO_TOKEN}

wallets:
  default:
    type: keystore
    path: /home/me/keeper/keys/default.json
    password: ${KEEPER_KEYSTORE_PASSWORD}

jobs:
  liquidation:
    markets: all
  triggers:
    markets: all
  unload:
    markets: all
  adl:
    markets: all
  refresh:
    markets: all
  terminalSettlement:
    markets: all
  collect:
    thresholdUsd: 5

# The snapshot, the earnings ledger and the status file, so a restart resumes where it stopped.
state:
  dir: /home/me/keeper/state

and the .env beside it, owner-only (mode 0600) where the file system has POSIX permissions:

RPC_HTTP_URL=https://arb-sepolia.g.alchemy.com/v2/your-key
PYTH_PRO_TOKEN=your-pyth-pro-token
KEEPER_KEYSTORE_PASSWORD=your-password

Running init again over an existing .env keeps the NAME=value lines already there (comments are dropped) and replaces or adds the new ones. A job with nothing under it is written as job: {}: a job key with an empty value reads as null, which turns the job off.

The wizard ends with Next: bazaar keeper doctor, then bazaar keeper start.

3. Check Everything: bazaar keeper doctor

bazaar keeper doctor

doctor loads the config and the wallets (a keystore without a stored password is asked for here), then checks everything start relies on, one line each. It exits 0 when nothing failed (warnings allowed) and 1 otherwise. A config file that does not load (invalid YAML, a secret written into it, an unknown key) prints one line and exits 2. URLs and keys are masked in everything it prints.

✔ RPC            chain 421614, latency 84 ms, eth_call state overrides supported
✔ Factory        0x0000000000000000000000000000000000000000 not an official deployment, 3 market(s)
✔ Wiring         lens and terminator both point back at this factory
⚠ Subgraph       none configured: the first start indexes from chain logs
✔ Prices         3/3 markets have a print
✔ Prices         the fixed_rate@200ms stream is delivering
✔ Wallet default 0x14dC79964da2C08b23698B3D3cc7Ca32193d9955, 0.02000 ETH (roughly 3,333 calls at today's base fee)
✔ Jobs           liquidation, triggers, unload, adl, refresh, collect, terminalSettlement

Fix every ✘ before starting; Troubleshooting has each message and its fix.

4. Fund the Wallet

Send ETH on the keeper’s network to the wallet address doctor printed. No keeper call needs USDC or a token approval: gas and Pyth’s small update fee are paid in ETH, and bounties accrue to the wallet’s claimable balance on each market.

How much: Arbitrum gas is cheap, and the keeper never spends more than budget.maxSpendUsdPerDay (and budget.maxSpendEthPerDay) in a day. Keep comfortably more than budget.minEthBalance (0.002 ETH by default): below it, the keeper stops sending until the wallet is funded again. bazaar wallet list shows each wallet’s ETH and what it can claim.

5. Start

bazaar keeper start

The first start connects, checks the chain and the factory’s wiring, and builds its index: from the subgraph if one is configured, or by replaying the chain’s logs from the factory’s deployment block. Without startBlock, it first finds that block with about 30 historical eth_getCode reads. The log shows each step:

12:00:01 INFO    found the factory's deployment block, 123456789 (set startBlock: 123456789 in the config to skip the search)
12:00:01 INFO    indexing from chain logs, blocks 123456789 to 123987654
12:00:41 WARNING factory 0x0000000000000000000000000000000000000000 is not an official deployment
12:00:41 INFO    keeper running on arbitrum-sepolia (3 markets, jobs: liquidation, triggers, unload, adl, refresh, collect, terminalSettlement)

From then on it logs each sent call and its result, and each distinct skip reason at most every five minutes (the rest at debug level):

12:03:17 INFO    liquidation ETH/USD: sent 0x5c1e…a9 (earns $0.1000 for $0.0021 of gas)
12:03:18 INFO    liquidation ETH/USD: liquidate 2 account(s), $4,100 notional confirmed, earned $0.1000 for $0.0019
12:05:00 INFO    refresh BTC/USD: skipped refresh a quiet market's price: below the profit rule: earns $0.1000 for $0.1100 of gas, needs ×1.25 and $0.001 net (allowLoss is off)

To try it without sending anything, start with --dry-run: every call is planned and simulated, and logged as it would be sent. --only liquidation,triggers runs just those jobs.

The first Ctrl-C (or SIGTERM) stops cleanly: in-flight transactions get their receipts, collect claims your balances if its onShutdown is on (the default), and the snapshot is saved. A second Ctrl-C leaves at once. The next start resumes from the snapshot, replaying only the blocks it missed.

6. Read the Status

From another terminal, in the same directory (or with the same -c):

bazaar keeper status

Bazaar keeper · arbitrum-sepolia · block 123,987,700 · indexed 123,987,699 · prices live · running
factory 0x0000000000000000000000000000000000000000 is not an official deployment
 JOB                 MARKETS  LAST ACTION                                                  TODAY EARNED    GAS    NET
 liquidation               3  ETH/USD liquidate 2 account(s), $4,100 notional (confirmed)         $0.10  $0.00  $0.10
 triggers                  3  -                                                                   $0.00  $0.00  $0.00
 refresh                   3  -                                                                   $0.00  $0.00  $0.00
 collect                 all  -                                                                   $0.00  $0.00  $0.00
 WALLET   ADDRESS
 default  0x14dC79964da2C08b23698B3D3cc7Ca32193d9955

status reads the status.json the running keeper rewrites every 5 seconds; it does not connect to anything. The header shows the network, the chain’s head and the last block indexed, whether prices are live (or prices down: with the endpoint’s last error), and running, or not running (last seen N min ago) when the file is more than 30 seconds old. A red line under it means sending is halted (a wallet below budget.minEthBalance). Each job’s row counts the markets it covers (all for collect), its last sent call, and the last 24 hours from the ledger.

For longer periods, bazaar keeper earnings --since 7d sums the ledger by job or by market (Commands).

Next

• Configuration Reference for everything the wizard did not ask.
• Running in Production to run it around the clock.
• Budgets & Losing Calls before raising any cap.

Wallets & Secrets

The keeper signs its transactions with wallets you configure under wallets:, each under a name of your choosing. Jobs send from the wallet named default unless their wallet key names another. This page covers every wallet type, the bazaar wallet commands, and the rules that keep keys, passwords and API keys out of the config file.

Wallet Types

wallets:
  default:
    type: keystore                  # keystore | privateKey | mnemonic | remote
    path: ~/.bazaar/keys/default.json
    password: ${KEEPER_KEYSTORE_PASSWORD}

A wallet missing what its type needs is a config error (wallets.default: a keystore wallet needs path). With no wallets section at all, the keeper is watch-only: it plans and simulates every call, logs what it would send, and sends nothing.

Keystore

path may start with ~/, which is your home directory. The keystore is decrypted once, when the keeper starts (Keeper.create in the library), so a wrong password fails at once with wallet default: wrong keystore password.

password is the keystore’s password, as a ${NAME} reference to .env or the environment. Left out, the keeper asks for it at start (Password for wallet default (default.json):) when it runs in a terminal. Without a terminal (a service, a detached container) it cannot ask, and stops with:

wallet default (default.json) needs a password: set wallets.default.password: ${KEEPER_KEYSTORE_PASSWORD} in the config and KEEPER_KEYSTORE_PASSWORD in .env or the environment, or start the keeper in a terminal to be asked for it

Private Key

wallets:
  fast:
    type: privateKey
    key: ${KEEPER_FAST_KEY}

The key must be 32 bytes of hex within the secp256k1 range. An invalid key fails with wallet fast: not a valid private key: …, which never quotes the key.

Mnemonic

wallets:
  second:
    type: mnemonic
    phrase: ${KEEPER_MNEMONIC}
    index: 1

The phrase is checked as eth-account checks it: 12, 15, 18, 21 or 24 words, every word from one BIP39 word list (English, Czech, French, Italian, Japanese, Korean, Portuguese, Spanish, simplified or traditional Chinese), and a matching checksum. Errors name the word’s position, never the word. index picks the account: 0 is the first address a wallet app shows for that phrase. BIP39 passphrases are not supported.

Remote Signer

wallets:
  default:
    type: remote
    url: ${SIGNER_URL}
    address: "0x14dC79964da2C08b23698B3D3cc7Ca32193d9955"

For each transaction the keeper posts one JSON-RPC request, eth_signTransaction, with an EIP-1559 transaction (type: 0x2, chainId, nonce, to, value, data, gas, maxFeePerGas, maxPriorityFeePerGas, from), and expects the signed raw transaction as result (a hex string, or an object with a raw field). It waits 15 seconds. The keeper then parses what came back and refuses it, sending nothing, unless it is exactly the transaction asked for (every field the same, no access list) and recovers to the configured address. The URL is masked in every message.

The bazaar wallet Commands

bazaar wallet new

Creates a random key and saves it as an encrypted keystore. It asks for a password twice.

bazaar wallet new                      # ~/.bazaar/keys/default.json
bazaar wallet new --name fast          # ~/.bazaar/keys/fast.json
bazaar wallet new --path ./keys/fast.json

✔ 0x14dC79964da2C08b23698B3D3cc7Ca32193d9955 saved encrypted at /home/me/.bazaar/keys/fast.json
Fund it with a little ETH for gas. No keeper call needs USDC or an approval.
In bazaar-keeper.yaml:
  wallets:
    fast:
      type: keystore
      path: /home/me/.bazaar/keys/fast.json
      password: ${KEEPER_KEYSTORE_PASSWORD}   # in .env, or leave out to be asked at start

It never overwrites a file (… already exists). Cancelling at a prompt writes nothing.

bazaar wallet import

The same, for a private key you paste (hidden as you type). A bad key fails before you choose a password.

bazaar wallet import --name fast

bazaar wallet list

Reads the config, loads every wallet (prompting for keystore passwords that are not stored), and prints each one’s ETH balance and what it can claim across the markets:

bazaar wallet list -c ~/keeper/bazaar-keeper.yaml

 WALLET   ADDRESS                                         ETH  CLAIMABLE
 default  0x14dC79964da2C08b23698B3D3cc7Ca32193d9955  0.02000  $12.40 across 2 market(s)
 fast     0x23618e81E3f5cdF7f54C3d65f7FBc0aBf5B21E8f  0.01000  $3.15 across 1 market(s)

list connects like start does, so with no snapshot yet it builds the index first.

Keystore Compatibility

Keystores are Ethereum’s JSON keystore, version 3, as geth and eth-account read and write them:

• Reading: scrypt or PBKDF2 (HMAC-SHA256 or HMAC-SHA512) key derivation, AES-128-CTR, the MAC checked in constant time before anything is decrypted. Key names are matched without case, so old geth files with "Crypto" load too.
• Writing: scrypt with n = 2^18, r = 8, p = 1, a 16-byte salt and a random 16-byte IV, in eth-account’s field order, written owner-only (0600) and never over an existing file.

So a version 3 keystore from geth, Foundry (cast wallet new) or the Python keeper opens here, and one written here opens in any tool that reads version 3 keystores.

Passwords and .env

The keeper reads .env from the config file’s directory before it reads the config. Variables already in the environment win over .env. bazaar keeper init writes .env owner-only (0600) and asks before putting the keystore password there.

A hot wallet holds only what it needs: a little ETH for gas, and the bounties it earned until collect claims them. Use collect.forwardTo to move claimed USDC to a cold address (The Jobs).

The Secrets Rules

The config file is meant to be shareable: you can commit it, paste it into an issue, or show it on screen. So the loader refuses to read a config that holds a secret, and says how to fix it.

Secret Keys

The values of these keys, wherever they appear, must be a single ${NAME} reference (or be left out):

prices.token holds a secret written into the file (a ${NAME:-default} default counts). Put it in .env as a variable and write token: ${NAME} here instead

URLs That Carry Keys

Hosted RPCs, indexers and price services often put the API key inside the URL: Alchemy’s /v2/<key>, Infura’s /v3/<id>, QuickNode’s /<token>/, a ?key= query, user:password@ before the host. The loader refuses any URL written into the file that may carry a credential, under any key. It judges by structure, not by what a key looks like: a URL passes only when every part of it is known to be public (short host labels or lowercase words joined by -; path segments that are well-known words such as rpc, api or stream, versions, short numbers, or lowercase words joined by - or _; the values of a few public query parameters). Everything else counts as a possible key.

rpc.http is a URL with a key in its path, written into the file. Put the URL in .env as a variable and write ${NAME} here instead, …

Two fixes:

rpc:
  http: ${RPC_HTTP_URL}                                        # the whole URL in .env
  # http: https://arb-mainnet.g.alchemy.com/v2/${ALCHEMY_KEY}  # or only the key in .env

The check runs on the text as written, with each reference’s default in its place, so https://arb-mainnet.g.alchemy.com/v2/${ALCHEMY_KEY} passes (the key is a reference) while a default holding the key does not. When in doubt, put the whole URL in .env, as init does for every URL you type.

${NAME} and ${NAME:-default}

Any string value in the config may hold references, filled from the environment (after .env is loaded):

A default is text in the file like any other, so a secret key’s value may use ${NAME:-} (empty when unset; an empty subgraph.apiKey sends no key, while an empty prices.token is refused: leave the line out for an endpoint that needs no token) but never ${NAME:-the-secret}. Names are letters, digits and _, not starting with a digit. References are filled in values only, never in keys.

Headers

prices.headers values go to the price endpoint with every request and usually carry its key, so each one is held to the same rule: a ${NAME} reference, optionally after an auth scheme.

prices:
  endpoint: ${PRICE_ENDPOINT_URL}
  headers:
    x-api-key: ${PRICE_HEADER_KEY}
    Authorization: Bearer ${PRICE_TOKEN}

prices.token is the shorter way to send Authorization: Bearer <token>. Neither the token nor the headers go to the symbols registry, which needs no credentials.

What the Keeper Prints

Keys, passwords and phrases never appear in an error or a log line. Every URL the CLI prints passes through the same structural redaction first (https://arb-sepolia.g.alchemy.com/v2/***), and doctor also masks the configured API keys and bot token wherever an error might quote them. Errors print one line; --debug adds the stack trace, also redacted. An address field that receives something the length of a private key says so without echoing it.

Several Wallets

Each wallet is its own nonce sequence: a send takes the wallet’s lock only to assign a nonce and sign, so two jobs on different wallets never wait for each other. Liquidations and trigger executions race other keepers; give them their own wallet so they never queue behind a collect, a sweep or a settlement:

wallets:
  default:
    type: keystore
    path: /home/me/keeper/keys/default.json
    password: ${KEEPER_KEYSTORE_PASSWORD}
  fast:
    type: keystore
    path: /home/me/keeper/keys/fast.json
    password: ${KEEPER_FAST_PASSWORD}

jobs:
  liquidation:
    wallet: fast
  triggers:
    wallet: fast
  unload: {}
  refresh: {}
  collect: {}

A job naming a wallet that is not under wallets is a config error (job liquidation uses wallet 'fast', which is not under wallets).

What every wallet shares:

• The low-balance halt. The keeper checks every wallet’s ETH once a minute. If any one is below budget.minEthBalance, all sending stops until it is funded. Fund every wallet.
• The budgets. Daily spend and loss caps count every wallet’s transactions together.
• Collect. collect claims every wallet’s balances, each from the wallet that earned it, and forwardTo forwards from each wallet.
• Manual operations send from default, or from the first wallet configured when there is no default.

Your own positions are never liquidated or settled by your keeper: every configured wallet’s address is skipped.

One process per set of wallets. Two keepers signing with the same wallet would fight over its nonces (each would see the other’s transactions take “its” nonce). The keeper recovers from a taken nonce by re-reading it and retrying once, which makes an occasional one-shot bazaar keeper run beside a running keeper workable, but two long-running processes on one wallet are not.

Related Pages

• Configuration Reference for every wallet key.
• Running in Production for backing up keystores.
• Troubleshooting for password prompts in containers.

Configuration Reference

The keeper reads one YAML file, bazaar-keeper.yaml by default (-c <path> names another). This page lists every section and every key, with its type, its default and what it does. Defaults are the schema’s (packages/keeper/src/config/schema.ts): a key you leave out takes its default, and so does a whole section.

bazaar keeper init writes a working file for you (Setting Up a Keeper); the repository’s bazaar-keeper.example.yaml shows the common options with comments. A complete annotated example is at the end of this page.

How the File Is Read

1. The .env file in the config’s directory is loaded into the environment. Variables already set in the environment win.
2. The YAML is parsed. It must be a mapping.
3. The secrets rules are checked on the text as written: secret keys must be ${NAME} references, URLs that may carry a key must come from the environment, and prices.headers values must be references.
4. Every ${NAME} and ${NAME:-default} in a string value is filled from the environment.
5. The result is validated against the schema. Unknown keys are refused everywhere, so a typo is an error, not a silently ignored setting. Every problem is listed at once:

the config is not valid:
  rpc: Unrecognized key(s) in object: 'chunk'
  wallets.default: a keystore wallet needs path
  config: job liquidation uses wallet 'fast', which is not under wallets

The library’s parseConfig(object) does step 5 only (The Keeper as a Library).

Three YAML details matter here:

• Quote addresses. YAML reads an unquoted 0x… as a hexadecimal number. Write factory: "0x3Aa5ebB10DC797CAC828524e59A333d0A371443c".
• An empty job turns it off. liquidation: with nothing under it is null, and a null job is disabled. Write liquidation: {} to enable a job with its defaults.
• Use block style for references. ${NAME} inside a flow mapping ({ botToken: ${TG_BOT_TOKEN} }) does not parse; write the mapping on separate lines, or quote the value.

Where

The keeper reads everything else from the factory: the lens, the terminator, the oracle, USDC, every market and its price feeds. It refuses to start if the lens or the terminator belongs to a different factory. A factory that is not a network’s official one is used all the same, with a warning (factory 0x… is not an official deployment) in the log, doctor and status.

startBlock left out. Nothing of Bazaar’s emits a log before its factory exists, so the scan can start at the factory’s deployment block. When startBlock is left out (and no official preset gives it), a first start without a subgraph finds that block on chain: a binary search on eth_getCode at historical blocks, about 30 reads on Arbitrum One. It logs found the factory's deployment block, N (set startBlock: N in the config to skip the search). The search needs an RPC that keeps historical state (hosted providers do). A node that has pruned it cannot answer, and the keeper refuses to start rather than scan from block 0:

could not find the factory's deployment block (…). Set startBlock in the config to the block the factory was deployed in, use an RPC that keeps historical state, or configure a subgraph

startBlock matters only for the first start without a subgraph (or after the state directory is emptied): later starts resume from the snapshot.

rpc

The node must support eth_call state overrides for rewards to be measured (What the Keeper Does). A log range it refuses (too many blocks or logs) is halved and asked for again, down to one block, and widened again after eight successes in a row; a lower logChunk avoids the refused requests. Rate-limit answers (HTTP 429), timeouts and connection failures are not refusals: the sync step fails and the next tick resumes after the last chunk applied.

subgraph

The subgraph only finds accounts and orders for the first start: the keeper reads its _meta block, pages through open positions and live or bounty-holding orders pinned to that block, and tails the chain’s logs from the next block. Every decision is made from chain state. If the subgraph fails for any reason, the first start indexes from chain logs instead. The opportunities scan also uses it to find open termination claims, insurer votes and listings.

prices

Prices come from Pyth Pro: signed updates the keeper attaches to its calls and the pair’s oracle has verified on chain. Pyth Pro needs an access token, which you get from Pyth.

The endpoint. pyth is three stream endpoints (wss://pyth-lazer-0.dourolabs.app/v1/stream, and -1 and -2), the request API at https://pyth-lazer.dourolabs.app and the symbols registry at https://pyth.dourolabs.app. A base URL names a service that answers the request API and the symbols registry at that URL and streams at its /v1/stream over ws or wss: http://127.0.0.1:8787 (where bazaar mock-prices listens) means the request API and the registry there and the stream at ws://127.0.0.1:8787/v1/stream. streamUrls, restUrl and symbolsUrl each replace one of the three, over a preset or a base URL. A URL that carries a key is a secret like any other: write it as ${NAME} (the secrets rules).

Plain http and ws. A token or a header sent over plain http or ws can be read by anyone on the path, so the keeper refuses to start when one would go that way to another machine: prices: the price request URL uses http://, which would send the price token and headers unencrypted to another machine: …. The same holds for a user name, a password or a query inside a URL, token or no token (prices: a price stream URL holds a user name, a password or a query and uses ws://, …); no message quotes the URL. Use https and wss. Set allowInsecure: true only for an endpoint on a network you trust end to end (a proxy beside the keeper, say). This machine is exactly localhost, an address in 127.0.0.0/8, or [::1]: a name under .localhost is resolved like any other name, so it counts as another machine. bazaar mock-prices on the same machine needs neither a token nor this.

A compatible service must serve POST /v1/latest_price, POST /v1/price (the one-second channel’s update for a past second, which terminate-scheduled settles with), GET /v1/symbols (feed symbols, for market labels; asked without the token) and the WebSocket stream.

The stream. Updates are judged against the chain’s clock, as their prices are: one stamped more than a minute ahead of it drops the endpoint that sent it. The keeper opens one subscription per watched market, for that market’s feeds together, plus one for ETH/USD (Pyth Pro feed 2, for pricing gas). The signed update a call attaches therefore carries exactly its pair’s feeds, both legs of a composite in one update, and costs one verification fee. The same subscriptions run on every stream endpoint and each update is taken once, from whichever endpoint brings it first; an endpoint that drops is reconnected while the others keep delivering. Three failures in a row mark prices unhealthy and switch a stream to polling for a minute. Each newer print wakes the liquidation and trigger planners. The stream runs on the ws package, on every supported Node version, bounded so an endpoint cannot make the keeper buffer more than it reads: no compression, no redirects, a 10 s handshake timeout, and a frame larger than 3 MiB ends the connection unread (the endpoint is reconnected like any that drops).

The channel. A faster channel shows a move sooner and brings more updates to read. A print is as old as its price, not as the update that carries it: a quiet feed’s updates carry its last price forward, and those read as stale. A feed Pyth does not serve on the chosen channel, or that the token does not cover, gets no print; the keeper warns once per feed and its markets get no price.

checkSigners. Once the deployment is read, the keeper asks its Pyth verifier whether it trusts the signer of each update (isValidSigner, each answer kept for a minute) and takes no price from an update signed by anyone else: a stream endpoint that sends one is dropped and reconnected while the others keep delivering, and a request API response that carries one is refused whole. The chain verifies every update a call carries either way; the ETH/USD print that prices gas reaches no contract, so this is the only check on it, and with it off the keeper warns at start (bazaar keeper doctor says so too). It costs one signature recovery per update taken, which adds up with many markets on a fast channel: turn it off, or pick a slower channel, if the keeper falls behind the stream.

wallets

A map from a name of your choosing to a wallet. Jobs use default unless they name another. Left out, the keeper is watch-only. Wallets & Secrets explains each type.

jobs

Each job is switched on by being present (liquidation: {} or with settings), and off by being left out, null, or enabled: false. Every job takes the common keys; most also have their own. The Jobs explains what each one does with them.

Common Keys

Naming markets. An address names one market and must be one of the factory’s (0x… is not a market of this factory). A label such as BTC/USD names every market carrying it: labels are not unique, since a market relisted after a termination keeps its label and a composite is labelled after its base. Such a label covers all of them, each job acting only on those in a market state it runs in, and the keeper logs a warning naming their addresses. A name no market carries stops the start with no market called 'X'. Markets: …. bazaar keeper markets lists every market with its label and address.

liquidation

triggers

unload

adl

refresh

terminalSettlement

collect

sweepExpired

profit

Each job can override both. Budgets & Losing Calls.

gas

budget

Budgets & Losing Calls explains how they combine.

safety

A revert on chain means the state changed between the simulation and the block (usually another keeper got there first). A success resets the count.

alerts

Running in Production describes each kind.

state

So one state directory can hold several keepers (different networks or factories) side by side. init sets it to state/ beside the config.

log

engine

A Complete Example

Every section, with the defaults written out where they are worth seeing. Secrets come from .env beside the file.

# ---- Where ----
network: arbitrum-one
factory: "0x0000000000000000000000000000000000000000"  # quoted: YAML reads bare 0x… as a number
startBlock: 123456789            # the factory's deployment block; leave out to have it found on chain

rpc:
  http: ${RPC_HTTP_URL}          # the provider's URL holds its key: it lives in .env
  send: sequencer                # Arbitrum One: submit straight to the sequencer
  maxRequestsPerSecond: 25
  logChunk: 2000                 # blocks per eth_getLogs; refused ranges are halved automatically

subgraph:
  url: ${SUBGRAPH_URL:-none}     # a Bazaar subgraph if SUBGRAPH_URL is set, else index from logs

prices:
  endpoint: pyth                 # Pyth Pro; or ${PRICE_ENDPOINT_URL} for another Pyth Pro compatible service
  token: ${PYTH_PRO_TOKEN}       # your Pyth Pro access token
  channel: fixed_rate@200ms
  checkSigners: true             # only updates signed by a signer the deployment's Pyth verifier trusts
  stream: true
  streamIdleTimeoutSeconds: 10
  sendMarginSeconds: 1.0

# ---- Who ----
wallets:
  default:                       # collect, refresh, unload, settlement, manual operations
    type: keystore
    path: /srv/keeper/keys/default.json
    password: ${KEEPER_KEYSTORE_PASSWORD}
  fast:                          # its own nonce queue for the jobs that race
    type: keystore
    path: /srv/keeper/keys/fast.json
    password: ${KEEPER_FAST_PASSWORD}

# ---- What ----
jobs:
  liquidation:
    wallet: fast
    markets: all
    allowLoss: true              # liquidate even at a small loss: it keeps the market solvent
    maxLossUsdPerCall: 0.10
    lossBudgetUsdPerDay: 2
  triggers:
    wallet: fast
    minBountyUsd: 0.02
  unload: {}                     # {} enables a job with its defaults; an empty key would disable it
  adl: {}
  refresh:
    exclude: ["0x0000000000000000000000000000000000000001"]   # a market's address: never refresh it
    healthPokes: true            # pay for refreshes that open or end an ADL window
    healthPokeMaxCostUsd: 0.10
  terminalSettlement:
    finalize: true               # unpaid, but it releases everyone's payout
    finalizeMaxCostUsd: 0.5
  collect:
    thresholdUsd: 10
    maxAgeDays: 7
    forwardTo: "0x0000000000000000000000000000000000000002"   # a cold wallet
    forwardMinUsd: 100
  sweepExpired:                  # unpaid public service, within its daily budget
    lossBudgetUsdPerDay: 0.25
    minBatch: 10

# ---- How much ----
profit:
  minProfitUsd: 0.001
  gasSafetyMultiplier: 1.25
gas:
  maxFeeGwei: 1                  # never pay more than 1 gwei per gas
  backgroundMaxFeeGwei: 0.1      # collect, sweeps, finalize and forwarding wait for a quiet chain
  feeMultiplier: 2.0
  ethUsdFallback: 3000
  ethUsdFloor: 1000
  ethUsdMaxAgeSeconds: 60
budget:
  maxSpendUsdPerDay: 20
  maxSpendEthPerDay: 0.02        # the same cap in ETH, which no price feed can lift
  maxLossUsdPerDay: 5
  minEthBalance: 0.005
safety:
  pauseAfterReverts: 3
  pauseMinutes: 15

# ---- Around it ----
alerts:
  telegram:
    botToken: ${TG_BOT_TOKEN}
    chatId: "123456789"
  notify: [lowBalance, jobPaused, endpointDown, opportunity, dailySummary]
state:
  dir: /srv/keeper/state
log:
  level: info
  format: json                   # one JSON object per line, for a log collector
engine:
  tickSeconds: 0.5
  simCooldownSeconds: 2.0
  idleRefreshSeconds: 5.0
  snapshotSeconds: 60

Related Pages

• Wallets & Secrets: wallet types and the secrets rules.
• The Jobs: what each job’s keys change.
• Budgets & Losing Calls: profit, gas and budget together.
• Troubleshooting: every config error.

The Jobs

This page describes each automatic job in depth: when it plans, what it calls, how it is paid, the keys that change it, the market states it runs in, and its edge cases. Configuration Reference lists every key with its type and default; Budgets & Losing Calls explains the rule that decides whether a planned call is sent.

How Jobs Run

Every engine.tickSeconds (0.5 s) the keeper reads the head, applies the new blocks’ logs to its index, re-reads the state of the markets those logs touched (and of the others every engine.idleRefreshSeconds), and lets every enabled job plan. A plan returns calls; each one goes to the executor on its own, which simulates it, prices it, applies the spend policy and sends it.

• In-flight keys. Each call carries keys (a position, an order, a market) and is not dispatched while any of them is already in flight, so the tick and the print path never send the same candidate twice. A send with no receipt after 90 seconds keeps its keys for 5 more minutes, in case it still lands.
• Cooldowns. A candidate the chain refused (a revert in simulation, or a call the policy skipped) waits before it is simulated again: engine.simCooldownSeconds for most jobs, longer for some (each job says below). Nothing brings it back sooner.
• Pauses. safety.pauseAfterReverts on-chain reverts in a row pause a job on a market for safety.pauseMinutes. Pauses are kept by market label, so markets sharing a label pause together.
• Your own positions are never liquidated or settled by your keeper.

Market States

A market’s state, read from the chain, gates which jobs plan on it:

A one-shot bazaar keeper run on a market in another state is skipped with the market is settling; this job runs while it is live.

Prices

A price-touching call judged at a fresh print carries that print’s signed Pyth Pro update: the update the market’s own subscription delivers, which carries exactly those feeds (both legs of a composite in one), so the call pays one verification fee. A call carries a print only while it is fresh enough to send: its price generated within the pair’s 3 s limit less prices.sendMarginSeconds, with confidence within the pair’s cap. The oracle’s fee for the update is sent as the call’s ETH value (and counts as its cost).

Nothing on chain holds a price but the pair itself. An update a call carries is verified and must be fresh: one that is stale or that Pyth’s verifier refuses reverts the call, so the keeper never attaches one it would not send. A call without an update runs on the pair’s stored price while that is at most 3 s old.

Planning, the simulation and the wallet’s queue all take time, so the price a call relies on (the print’s, or the stored price it is judged at) is checked once more just before the call is signed, against the chain’s time: one older than the pair’s 3 s limit less prices.sendMarginSeconds is not sent. Nothing refused the candidate, so it does not cool down: the next print plans it again.

A market with trading hours gets no fresh print while its venue is closed: Pyth’s updates keep arriving, but they carry the last price forward, and a price is as old as when it was generated. So only the jobs that work without a fresh print still act there: liquidation (judging by the stored price), sweepExpired, terminal settlement and collect.

A print without a confidence is never attached. The oracle reads a zero confidence as a missing one and reverts the call, so a market whose feed reports none is planned as one without a fresh print, and no confidence is made up for it.

The Price a Call Is Judged At

A pair stores the price a call carries only when that price was generated in a later second than the price it holds (for a composite, when its older leg was). Otherwise it judges the call at the price it holds: within one second, the first price stored stands.

The planners judge the same way. While a market’s stored price is from the print’s second or a later one, liquidation, triggers and ADL judge at the stored price:

• a candidate that crosses only at the newer print is left for the next second’s print, with no simulation and no cooldown spent on it;
• a candidate that crosses at the stored price is planned even though the print has moved back.

Such a call carries no update. The chain’s stored price is at least as new as the one the keeper read, and it never goes back, so the pair could never store that print: attaching it would only cost its fee, and revert the call once the print aged past the pair’s limit, where the call without it still runs on the stored price. No refresh bounty is planned in that second, since the pair would store nothing.

Liquidation

Plans on every newer print for one of the market’s legs, and on every tick. For each open position in the index it computes equity at the price the call would be judged at and the market’s projected funding index, against the effective maintenance rate (the lower of the market’s MMR and its non-zero 24-hour-lagged MMR). This runs on every position on every print and allocates nothing, so a print costs no RPC requests until a position crosses.

Re-reads each crossing account’s position bucket from the chain (alongside the update fee), updates the index, and keeps the accounts still below their requirement. A bucket found empty is dropped from the index.

Calls liquidate(accounts, priceUpdate), every confirmed account in one batch of up to maxAccountsPerCall (40), more batches for more accounts.

Is paid by the insurance fund: $0.05 per position seized, or max($0.05, 2 bp of the notional it retires) for a seizure that nets the vault’s two buckets, plus whatever 2 bp of the call’s inline unload exceeds that; an account worth less than $5 pays at most its own equity; capped at the fund’s free capital. Batching earns the same as splitting, for less gas. The probe measures the exact amount.

Runs in live and adl.

Edge cases

• Closed sessions. With no fresh print, a market with trading hours is judged at its stored price if that price is less than 9.5 minutes old (the pair accepts one up to 10 minutes old), and the call carries no update. Older than that, nothing is planned until the market reopens.
• A refused account cools for engine.simCooldownSeconds (2 s).

Triggers

Plans on every newer print and on every tick. A candidate is a StopLimit, StopLoss or TakeProfit order that the index knows, that is not finished and not resting in the book, is unexpired at the next block, holds at least minBountyUsd of bounty (or none, with includeUnbountied), and whose trigger the live price reached (inclusive at the trigger; stops fire on a rise for buys and a fall for sells, take-profits the other way).

Re-reads each candidate’s order record. It drops orders that are cancelled, filled, now in the book or expired, and orders that rested in the current block: an execution in the block a stale-price creation left the order waiting in pays the bounty to the owner, not to you.

Calls executeTriggeredOrders(execs, priceUpdate) with up to 20 orders, highest bounty first. Each StopLimit gets a findPredecessor hint for where its limit rests once fired.

Is paid by the order’s owner, through the bounty escrowed at creation: in proportion to the size your call fills out of what remained, and the whole remainder once the order completes or rests.

Runs in live. A stale price can neither arm a stop nor bound its fill, so a closed market gets no trigger executions.

Edge cases: a refused batch cools for engine.simCooldownSeconds; a fired StopLimit the book could not finish stays live and is worth its unpaid remainder.

Unload

Plans on a market whose vault holds inventory in either bucket, at most every recheckSeconds (15 s), and sooner when the logs show the book changed or a liquidation happened on that market.

Calls unloadVault(maxSteps, priceUpdate), simulated first and sent only if it sells something (the book has nothing the vault may sell into at this price otherwise).

Is paid by the insurance fund: 2 bp of what it sells, raised to a $0.25 floor when one call sells $1,250 or more or clears the inventory.

Runs in live, with a fresh print (against a stale stored price the walk sells nothing and pays nothing).

Edge case: the floor slide. Bids within min(5%, MMR) of the oracle fill at once. A bid beyond that edge but above the estates’ bankruptcy price fills only once the vault’s floor has slid down to it, which takes up to 3 minutes from the bucket’s seizure stamp. So while a bucket is inside its slide, the job also re-checks one second after the slide completes, even if nothing else changed.

ADL

Plans while the market’s ADL window is open, on every tick, with a fresh print. It scores the positions that would close: shorts against the vault’s long bucket (while it holds inventory) and longs against the short bucket (likewise), counting only positions in profit at the live price. Each score is PnL over collateral less this window’s tagged deposit (read from the chain), floored at 1.

Keeps candidates whose score is at least the auction’s Dutch threshold, which falls quadratically from 25 to 1 over the 10-minute auction: 1 + 25e18 × (D − t)² / D² with D = 600 s and t the time since the auction started.

Calls executeAdl(longBucketWinners, shortBucketWinners, priceUpdate) with the top maxWinnersPerSide (25) of each list; the pair ranks and sorts each list itself at the price the call stores, so a newer tick re-ranks but never reverts the batch.

Is paid by the insurance fund: 2 bp at the mark of every unit a batch closes, or 0.1% of the bad debt that close averts where larger, plus 2 bp of the overlap the batch’s netting retires; capped at free capital.

Runs in adl only. ADL refuses the stored price, so it needs a fresh print. A refused batch cools for engine.simCooldownSeconds. Bazaar’s ADL page explains the auction.

Refresh

Plans on every tick, with a fresh print, when the refresh bounty would pay. The bounty’s gates (RiskParamsLib.payRefreshBounty, copied into the SDK for scheduling; the probe still decides):

• the print’s price was generated in a later second than the stored price;
• the stored price is older than 5 minutes while the vault holds at least $1,250 of inventory and the fund more than $5,000 of free capital, or older than 1 day otherwise;
• the fund’s free capital exceeds $1,000.

Calls refreshPrice(priceUpdate). Is paid $0.10 by the insurance fund.

Why it matters beyond the bounty. A pair whose stored price is more than 21 days old can be ended by anyone at that price (terminate-stale), and one refresh with a fresh update restarts the count. On a quiet market this job is what keeps a pair on a live feed out of reach. Where no bounty pays (a fund with $1,000 or less of free capital) the job plans nothing; bazaar keeper run refresh-price --market … --force sends one refresh regardless of the profit rule.

Health pokes. A refresh also judges the vault’s health: on a book too thin to trade, it is what opens an ADL window (and starts its 24-hour clock) once inherited inventory drifts past the trigger, and what ends a timed-out window by fixing the settlement price. Those refreshes may pay nothing. With healthPokes: true, on a market holding inventory, every healthPokeIntervalSeconds (60 s) the job simulates an unpaid refresh and sends it only if the probe shows it would open the ADL window (it was not pending before) or fix the settlement price. Turning health pokes on is consent to pay for them: each within healthPokeMaxCostUsd (0.10) and the job’s lossBudgetUsdPerDay, and the global budget.maxLossUsdPerDay. Otherwise it is skipped with the refresh would not change the vault's health state.

Runs in live and adl. A refused refresh cools for 10 s.

Terminal Settlement

Plans on every tick on a market whose settlement price is fixed (settling or terminated).

1. Settle. Every open position in the index, except your own wallets’ (their owner settles them by withdrawing), is re-read from the chain; the ones still open are settled with liquidate(accounts, []), which in settlement mode needs no price update and carries no ETH. One batch of up to maxAccountsPerCall (100) per tick; the next tick takes the rest.
2. Finalize. With finalize: true (the default), once nothing is left to settle and the market is not yet terminated, and either both sides’ open interest is zero or 14 days have passed since the settlement price was fixed (the escape hatch), it calls finalizeTermination().

Is paid $0.05 per position settled for someone else, from the position’s remaining collateral; the insurance fund tops up only positions worth at least $5 at the settlement price, so a smaller one pays what its collateral covers. Settling is a paid call under the profit rule. Finalize pays nothing: finalize: true is consent to pay for it, within finalizeMaxCostUsd (0.50), the job’s lossBudgetUsdPerDay and budget.maxLossUsdPerDay. It is background work, so it also waits while the base fee is above gas.backgroundMaxFeeGwei.

Runs in settling and terminated. A refused call cools for 30 s. Finalizing releases everyone’s payout; Bazaar’s Termination page explains the sequence. Terminating a market in the first place is a manual operation.

Sweep Expired

Plans on every tick on live markets, from the index:

• expired orders: Limit and StopLimit orders, not finished, whose expiry block has passed;
• refunds (with includeBountyRefunds): finished orders still holding a bounty, which the sweep returns to their owner.

It sends when there is any refund, or when expired orders number at least minBatch (10). It re-reads the orders first, drops what changed, and sweeps up to maxOrdersPerCall (100) with sweepExpired(orderIds).

Pays nothing: it is a public service that keeps books short and returns stranded bounties. So the job ships with allowLoss: true and a $0.25 lossBudgetUsdPerDay, each call within maxLossUsdPerCall (0.05), and it is background work under gas.backgroundMaxFeeGwei. It runs only if you enable it (init leaves it unchecked).

Runs in live. A sweep that was not sent waits 5 minutes before the next.

Collect

Bounties accrue to each wallet’s claimable balance on the market that paid them. collect claims them.

Plans every intervalSeconds (600 s), and 5 seconds after the logs show one of your wallets’ claimable balances changed. It reads every wallet’s claimable balances across the markets and plans a claimFees() on each market in its scope where a wallet holds a balance, sent from the wallet that holds it.

Decides by its own rule, not the profit rule (claiming earns nothing new):

• a balance of at least thresholdUsd (5) that covers the claim’s gas × gasSafetyMultiplier is claimed;
• a balance first seen more than maxAgeDays (7) ago is claimed whenever it covers its gas, however small. The age counts from when this process first saw the balance, so a restart starts it again;
• on a clean stop with onShutdown: true (the default), every balance that covers its gas is claimed.

Claims are simulated from the wallet itself (claimFees pays msg.sender), so a watch-only keeper cannot collect. Except on shutdown they are background work under gas.backgroundMaxFeeGwei.

Forwarding. With forwardTo set, each wallet whose USDC balance reaches forwardMinUsd (50) transfers its whole USDC balance to that address. Note that this moves any USDC in the wallet, not only claimed bounties. Forwarding is background work, recorded in the ledger as job forward, and fits the spend caps like any call.

Runs in every state: claiming works on a terminated market too.

Related Pages

• Budgets & Losing Calls: what decides whether a planned call is sent.
• Manual Operations: one-shot runs of each job, and the operations no job runs.
• Configuration Reference: every job key.

Budgets & Losing Calls

Every call the keeper plans is simulated, priced and then judged by the spend policy: the rules that decide whether it is sent. This page gives every rule, in the order the keeper applies them, and the settings that change each one. The short version: by default only profitable calls are sent; taking losses is something you switch on per job, within caps you set; and every call, however it was decided, must fit the daily spend caps and the fee ceilings.

What a Call Earns and Costs

For each call the executor knows:

• R, the reward in USD: exactly what the call would add to the wallet’s claimable balance on the market, measured by the probe simulation. Without eth_call state overrides it cannot be measured and counts as 0.
• C, the cost in USD: the gas from eth_estimateGas of the real transaction from the real wallet, times the current base fee, plus the ETH the call carries (Pyth’s update fee), priced at ETH/USD.
• the same cost in wei, for the ETH cap.

The policy then decides as follows.

1. The Daily Spend Caps

Every call must fit both caps, whoever decided it should go (the profit rule, a loss you allowed, a job’s own rule, --force, a manual operation):

The ETH cap is counted in wei, so no ETH/USD price can lift it: a feed reporting ETH at $1 would make gas look free in USD, but not in wei. Set maxSpendEthPerDay yourself to decouple it from the floor.

A call that does not fit is skipped: daily gas budget reached ($9.98 of $10.00 spent) or daily ETH spend cap reached (0.00998 of 0.01 ETH spent; budget.maxSpendEthPerDay). The window slides: a call sent 24 hours ago stops counting. A call whose cost cannot be priced (not a finite number) is refused outright.

2. The Profit Rule

A paid call (one that earns a bounty) is sent when both hold:

R − C ≥ minProfitUsd          (default 0.001)
R ≥ C × gasSafetyMultiplier   (default 1.25)

Otherwise it is skipped: below the profit rule: earns $0.0400 for $0.0500 of gas, needs ×1.25 and $0.001 net (allowLoss is off), unless the job takes losses.

3. Losing Calls

A keeper may want to send calls that cost more than they earn: liquidating a position before it turns into bad debt, opening an ADL window, or cleaning up books as a public service. That is your choice, per job, and always capped. A call that fails the profit rule is sent only with consent:

• allowLoss: true on the job, or
• an unpaid duty switched on by name: terminalSettlement.finalize (default on) or refresh.healthPokes (default off). Turning one on is consent to pay for that call.

jobs:
  liquidation:
    allowLoss: true            # also send calls that cost more than they earn
    maxLossUsdPerCall: 0.10    # never lose more than this on one call
    lossBudgetUsdPerDay: 2     # nor more than this per day for this job
budget:
  maxLossUsdPerDay: 5          # and never more than this across all jobs

The loss, C − R, must then fit three caps:

Each refusal says which cap: would lose $0.1200, above the $0.1000 per-call cap, liquidation's daily loss budget is spent ($1.98 of $2.00), the global daily loss budget is spent ($2.00 of $2.00). A call that pays nothing and has no consent is skipped with pays nothing, and this job does not take losses (allowLoss is off).

sweepExpired pays nothing ever, so it ships with allowLoss: true and a $0.25 daily budget, and runs only if you enable the job. includeUnbountied trigger orders pay nothing too, so they send only with allowLoss.

Only calls the policy sent as losses count against the loss budgets (their ledger kind is loss or unpaid). A profitable call that turned out to lose on chain (the receipt’s gas higher than the estimate) counts toward the spend caps, not the loss budgets.

4. Collect and Forwarding

collect replaces the profit rule with its own (claiming earns nothing new): claim a balance once it reaches thresholdUsd and covers the gas × gasSafetyMultiplier; claim a balance older than maxAgeDays, or anything on shutdown, whenever it covers the gas. Forwarding sends whenever the wallet’s USDC reaches forwardMinUsd. Both still fit the spend caps and the fee ceilings. The Jobs.

5. The Fee Ceilings

Arbitrum’s sequencer orders transactions first come, first served, so a priority fee buys nothing. The keeper sends with priority fee 0 and maxFeePerGas = base fee × gas.feeMultiplier (2.0), and caps it:

While the base fee is above the ceiling, the call waits: base fee 0.1500 gwei is above the 0.1 gwei ceiling. --force and manual operations keep the ceilings. The gas limit is the estimate × gas.gasLimitMultiplier (1.25) + 10,000.

6. The Low-Balance Halt

The keeper reads every wallet’s ETH balance once a minute (and before the first send of a one-shot run). While any wallet holds less than budget.minEthBalance (0.002 ETH), all sending stops, on every wallet, with a lowBalance alert:

sending paused: fast (0x23618e81E3f5cdF7f54C3d65f7FBc0aBf5B21E8f) holds 0.00140 ETH, below budget.minEthBalance

It resumes on its own once every wallet is funded. Forced calls and manual operations stop too. When a send needs a fresh balance check (the first send, and one-shot runs) and the balances cannot be read, that call is not sent: could not read the wallets' balances, so nothing is sent: ….

Pricing Gas in USD

The USD budgets depend on the ETH/USD price, which never goes on chain, so nothing verifies it. The keeper guards it:

So the price used is the fresh, plausible print, else the fallback, and never below the floor. Each call uses one price for its decision and its ledger entry. doctor warns when no fresh, plausible ETH/USD print is available.

What --force Skips and Keeps

bazaar keeper run <operation> --force (and { force: true } in the library) is for one-shot calls you want sent even when the policy would not:

A forced call is booked with kind forced and does not count against the loss budgets; it counts against the spend caps. Manual operations are always sent this way (they pay nothing and run because you asked). For collect, --force means something else: claim every balance that covers its gas, as on shutdown.

Reservations Under Concurrency

Each call is planned and sent in its own task, so many may be deciding at once. The moment a call is decided, its cost (and its loss, if it was sent as one) is reserved in the ledger, with no wait between the decision and the reservation. Every later decision sees it, so concurrent sends cannot together overshoot a budget. When the receipt arrives the reservation becomes the ledger entry, at the actual gas cost; a send that never went out releases it.

A send that got no answer and shows no receipt within 90 seconds is booked as unknown at its estimated cost: it may still land, so it keeps counting, and its candidate stays locked for 5 more minutes.

The Ledger and earnings

Every transaction the keeper sends becomes one line in ledger.jsonl in the state directory (<state.dir>/keeper/<chainId>-<factory>/ledger.jsonl), appended when its receipt arrives:

{"ts": 1762600998.12, "job": "liquidation", "market": "ETH/USD", "wallet": "0x23618e81E3f5cdF7f54C3d65f7FBc0aBf5B21E8f", "tx": "0x5c1e…", "status": "confirmed", "kind": "profit", "cost_usd": 0.0019, "reward_usd": 0.1, "expected_reward_usd": 0.1, "claimed_usd": 0, "gas_used": 412345, "summary": "liquidate 2 account(s), $4,100 notional", "extra": {"cost_wei": "1900000000000"}}

The daily budgets are read from the ledger, so they survive restarts. Only sent transactions are written; skips and dry runs are not. The format is the Python keeper’s, so either reads the other’s ledger.

bazaar keeper earnings sums it:

bazaar keeper earnings --since 24h
bazaar keeper earnings --since 30d --by market

 JOB                 CALLS  REVERTED   EARNED      GAS      NET  CLAIMED
 collect                 2         0  $0.0000  $0.0004  $-0.0004   $12.40
 liquidation            14         1  $1.4000  $0.0310  $1.3690    $0.00
 triggers               31         3  $2.1700  $0.0620  $2.1080    $0.00

EARNED is what the calls accrued to your claimable balances, NET that less gas, and CLAIMED what collect moved to your wallet. --since takes 30m, 24h, 7d (a bare number is days; default 7d); --by is job (default) or market.

Choosing Your Numbers

• Start with the defaults and start --dry-run for a while: the log shows what would be sent and why each skip was skipped.
• Raise maxSpendUsdPerDay (and maxSpendEthPerDay) to what you are willing to spend on a bad day, not an average one.
• Turn on allowLoss only for jobs whose work matters to you even unpaid, with small per-call caps.
• Set gas.maxFeeGwei so a gas spike cannot make the keeper bid into it.

Related Pages

• The Jobs: which calls are paid and which are not.
• Configuration Reference: every key.
• Commands: earnings in full.

Running in Production

A keeper earns by being there when a call comes due, so it runs around the clock. This page covers what that takes: how many processes, where the keeper keeps its state and how restarts use it, the Docker image, systemd and pm2 samples, alerts, logs, upgrades, backups and monitoring.

One Process per Set of Wallets

Run one keeper process for each set of wallets. Each wallet is a nonce sequence the process manages itself; two processes signing with the same wallet would take each other’s nonces. To split work across machines, give each process its own wallets (and its own jobs or markets).

One process can run every job on every market. To keep latency-critical sends off the queue of slower work, give liquidation and triggers their own wallet in the same process (Wallets & Secrets).

The State Directory and Restarts

The keeper keeps three files under state.dir (~/.bazaar by default; state/ beside the config when init wrote it), in keeper/<chainId>-<first 8 hex digits of the factory>/:

Restarts. A restart loads the snapshot and replays every block since it, from the chain’s logs (the subgraph is not asked again), so nothing is missed while the keeper was down. A snapshot for another chain, another factory or another snapshot format is ignored, and the keeper builds its index afresh. Deleting the snapshot forces that too. While the replay is 64 or more blocks behind the head, the price-driven planners wait for it to finish.

Stopping. SIGINT or SIGTERM stops cleanly: no new call is dispatched, in-flight sends get their receipts (up to 60 s), collect claims every balance that covers its gas if onShutdown is on, and the snapshot is saved. A second signal leaves at once (exit code 130). Give your process manager at least 90 seconds before it kills the process.

Exit codes. bazaar keeper start exits 0 after a clean stop, 2 for a configuration or wallet problem (fix the config; restarting will not help), and 1 for anything else (an RPC that cannot be reached at start, say).

Docker

The repository’s Dockerfile builds an image that runs the keeper as an unprivileged user, with everything it keeps in the directory mounted at /config:

git clone https://github.com/liberta-labs/bazaar-sdk && cd bazaar-sdk
docker build -t bazaar-keeper .

The image’s entry point is the bazaar command, and its default command is keeper start. Its working directory is /config, so the default config path, bazaar-keeper.yaml, is /config/bazaar-keeper.yaml. HOME is /config as well, so any ~/ path (the default state.dir, ~/.bazaar; bazaar wallet new’s ~/.bazaar/keys) also lands on the mount.

Set it up once, interactively, then run it detached:

mkdir -p keeper
# once: the wizard, inside the container
docker run --rm -it --user "$(id -u):$(id -g)" -v "$PWD/keeper:/config" bazaar-keeper keeper init
# check it
docker run --rm -it --user "$(id -u):$(id -g)" -v "$PWD/keeper:/config" bazaar-keeper keeper doctor
# run it
docker run -d --name keeper --restart unless-stopped --user "$(id -u):$(id -g)" \
  -v "$PWD/keeper:/config" bazaar-keeper

init run this way writes /config/bazaar-keeper.yaml and /config/.env, a new keystore under /config/keys/, and state.dir: /config/state: all of it in ./keeper on the host.

• --user "$(id -u):$(id -g)" runs the keeper as you, so it can write to the mounted directory and you own what it writes. Without it, the container runs as uid 10001, and the directory must be writable by that user.
• Store the keystore password in .env when init asks. A detached container has no terminal to ask for it, and stops with wallet default (default.json) needs a password: ….
• docker stop keeper sends SIGTERM, which stops the keeper cleanly. Docker waits 10 seconds by default before killing; give it longer: docker stop -t 90 keeper (or --stop-timeout 90 on docker run).
• Other commands run the same way: docker exec keeper node /app/packages/keeper/dist/cli/main.js keeper status, or docker run --rm --user … -v … bazaar-keeper keeper earnings --since 7d.
• Logs: docker logs -f keeper. Set log.format: json for a log collector.

systemd

A unit for a keeper installed from the repository in /opt/bazaar-sdk, with its directory at /srv/keeper, running as a dedicated keeper user:

# /etc/systemd/system/bazaar-keeper.service
[Unit]
Description=Bazaar keeper
After=network-online.target
Wants=network-online.target

[Service]
User=keeper
Group=keeper
WorkingDirectory=/srv/keeper
ExecStart=/usr/bin/node /opt/bazaar-sdk/packages/keeper/dist/cli/main.js keeper start -c /srv/keeper/bazaar-keeper.yaml
# SIGTERM stops cleanly; give in-flight sends and the shutdown collect time to finish.
KillSignal=SIGTERM
TimeoutStopSec=90
Restart=on-failure
RestartSec=10
# A config or wallet error exits 2: restarting will not fix it.
RestartPreventExitStatus=2
# The keeper writes only its state directory (state.dir must be under /srv/keeper, as init sets it).
NoNewPrivileges=true
ProtectSystem=strict
ReadWritePaths=/srv/keeper
PrivateTmp=true

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now bazaar-keeper
journalctl -u bazaar-keeper -f

The keystore password must come from .env (or an EnvironmentFile= the unit reads): a service cannot answer a prompt. With a global npm install, ExecStart=/usr/bin/env bazaar keeper start -c ….

pm2

// ecosystem.config.cjs
module.exports = {
  apps: [
    {
      name: "bazaar-keeper",
      script: "/opt/bazaar-sdk/packages/keeper/dist/cli/main.js",
      args: "keeper start -c /srv/keeper/bazaar-keeper.yaml",
      cwd: "/srv/keeper",
      // pm2 sends SIGINT, then kills after kill_timeout ms: leave time for a clean stop.
      kill_timeout: 90000,
      autorestart: true,
      restart_delay: 10000,
    },
  ],
};

pm2 start ecosystem.config.cjs
pm2 logs bazaar-keeper

Alerts

The keeper can send alerts to Telegram, Discord and any webhook. Each channel is its own request, so one that is down does not hold back the others. Every alert is also logged as a warning (alert (lowBalance): …), configured channels or not.

alerts:
  telegram:
    botToken: ${TG_BOT_TOKEN}
    chatId: "123456789"
  discord:
    webhook: ${DISCORD_WEBHOOK_URL}
  webhook:
    url: ${ALERT_WEBHOOK_URL}
  notify: [lowBalance, jobPaused, endpointDown, opportunity, dailySummary]

The bot token and the Discord webhook URL are secret keys, and a generic webhook URL usually carries its own token in its path: put all three in .env (the secrets rules). Messages are prefixed Bazaar keeper: and stripped of control characters.

notify chooses the kinds. Only the kinds listed are sent or logged.

A price endpoint that is down shows in the log (price endpoint: …) and in status (prices down: …), not as an alert; watch status.json for it (below).

Logs

The CLI logs to standard output. log.level is debug, info (default), warning or error; log.format is pretty (default) or json:

12:03:17 INFO    liquidation ETH/USD: sent 0x5c1e…a9 (earns $0.1000 for $0.0021 of gas)

{"ts":1762600997.512,"level":"info","logger":"bazaar_sdk.exec","msg":"liquidation ETH/USD: sent 0x5c1e…a9 (earns $0.1000 for $0.0021 of gas)"}

A JSON line carries exc with the stack trace when there is one. At info the keeper logs each sent call and its result, each distinct skip reason at most every five minutes (repeats at debug), new listings, reorgs, catch-ups and warnings. Repeated failures (a planning error, a failing engine step) are logged at most every 30 to 60 seconds. URLs and keys are never logged.

Upgrades

1. Stop the keeper cleanly (SIGTERM, and wait for it to exit).
2. Upgrade: npm install -g @liberta-labs/bazaar-keeper@latest once published; from the repository, git pull && npm install && npm run build; with Docker, rebuild the image.
3. Run bazaar keeper doctor (a new version may refuse a key it no longer knows, or need a new one).
4. Start it again. It resumes from the snapshot. If the new version uses another snapshot format, it ignores the old snapshot and builds its index afresh (from the subgraph or the logs), which takes as long as a first start.

The ledger keeps its format across versions, so earnings and the daily budgets carry over.

Backups

The snapshot needs no backup: the keeper rebuilds it. A wallet’s unclaimed bounties stay on chain on each market’s claimable balance whatever happens to the machine; restoring the keystore anywhere lets you claim them (bazaar keeper run collect).

Monitoring

status.json in the state directory is rewritten every 5 seconds while the keeper runs, so it is the simplest thing to watch. bazaar keeper status renders it; a script can read it directly:

A watchdog in TypeScript that exits non-zero when the keeper is unwell, for cron or a monitoring agent:

// The same directory the keeper writes to: <state.dir>/keeper/<chainId>-<first 8 hex digits of the factory>.
const cfg = loadConfig("/srv/keeper/bazaar-keeper.yaml");
const path = join(stateDirFor(cfg), "status.json");

const problems: string[] = [];
let s: KeeperStatus | null = null;
try {
  s = JSON.parse(readFileSync(path, "utf8")) as KeeperStatus;
} catch (e) {
  problems.push(`no readable status at ${path}: ${e instanceof Error ? e.message : String(e)}`);
}
if (s) {
  const age = Date.now() / 1000 - s.updated; // the keeper rewrites the file every 5 s
  if (age > 30) problems.push(`status is ${Math.round(age)} s old: the keeper is not running`);
  if (!s.prices.healthy) problems.push(`prices down: ${s.prices.error || "no print yet"}`);
  if (s.halted) problems.push(s.halted); // e.g. a wallet below budget.minEthBalance
  if (s.block - s.indexed > 64) problems.push(`the index is ${s.block - s.indexed} blocks behind the head`);
  // Not a problem in itself, but worth a look: positions close to their maintenance requirement.
  for (const m of s.markets) if (m.atRisk) console.log(`${m.label} (${m.address}): ${m.atRisk} position(s) near liquidation`);
}
for (const p of problems) console.error(p);
process.exitCode = problems.length ? 1 : 0;

Or in a shell, with jq:

S=/srv/keeper/state/keeper/42161-*/status.json
jq -e --argjson now "$(date +%s)" '($now - .updated) < 30 and .prices.healthy and (.halted == "")' $S >/dev/null \
  || echo "keeper unwell"

For metrics, run the keeper as a library and feed its action events to your metrics system, or serve keeper.statusDict() over HTTP (The Keeper as a Library).

Related Pages

• Setting Up a Keeper: the first run.
• Wallets & Secrets: keystores and passwords.
• Troubleshooting: what each warning means.

Commands

Everything the bazaar command does. bazaar keeper <command> runs the keeper; bazaar wallet and bazaar mock-prices are shared tools. Every command has --help.

Common Options

Errors print one readable line, with URLs and keys masked. Exit codes:

keeper init

bazaar keeper init [-c bazaar-keeper.yaml]

Asks for the network, factory, RPC, subgraph, price endpoint, wallet, jobs and markets, checking each answer, and writes the config and a .env beside it (secrets and URLs only in .env), a new keystore in keys/ beside them, and state.dir as state/ beside them. Needs a terminal. Every question is explained in Setting Up a Keeper.

keeper doctor

bazaar keeper doctor [-c bazaar-keeper.yaml]

Checks everything start relies on. Exits 0 when nothing failed, 1 otherwise.

✔ RPC            chain 42161, latency 61 ms, eth_call state overrides supported
✔ Factory        0x0000000000000000000000000000000000000000 not an official deployment, 12 market(s)
✔ Wiring         lens and terminator both point back at this factory
✔ Subgraph       synced to block 271,402,118 (14 blocks behind)
✔ Prices         12/12 markets have a print; 4 not fresh right now (AAPL/USD, TSLA/USD, NVDA/USD, SPY/USD)
✔ Prices         the fixed_rate@200ms stream is delivering
✔ Wallet default 0x14dC79964da2C08b23698B3D3cc7Ca32193d9955, 0.05000 ETH (roughly 8,333 calls at today's base fee)
✔ Wallet fast    0x23618e81E3f5cdF7f54C3d65f7FBc0aBf5B21E8f, 0.03000 ETH (roughly 5,000 calls at today's base fee)
⚠ Jobs           liquidation takes losses: up to $0.1 a call, $2 a day
✔ Jobs           liquidation, triggers, unload, adl, refresh, collect, terminalSettlement

“Not fresh right now” is normal for markets with trading hours outside them. The first Prices line is one request to the request API; the second opens the price stream for ETH/USD and waits up to 5 seconds for a print (skipped when prices.stream is off). Each line is explained in Setting Up a Keeper; each failure in Troubleshooting.

keeper start

bazaar keeper start [-c bazaar-keeper.yaml] [--dry-run] [--only <jobs>]

Runs until Ctrl-C or SIGTERM. The first signal stops cleanly (in-flight transactions finish, collect runs if its onShutdown is set, the snapshot is saved); a second leaves at once.

bazaar keeper start --dry-run --only liquidation,triggers

keeper status

bazaar keeper status [-c bazaar-keeper.yaml]

Reads the status.json of the keeper running with this config (it connects to nothing), so it works from any terminal on the same machine:

Bazaar keeper · arbitrum-one · block 271,402,140 · indexed 271,402,139 · prices live · running
factory 0x0000000000000000000000000000000000000000 is not an official deployment
 JOB                 MARKETS  LAST ACTION                                                  TODAY EARNED    GAS     NET
 liquidation              12  ETH/USD liquidate 1 account(s), $2,050 notional (confirmed)         $0.35  $0.01   $0.34
 triggers                 12  BTC/USD execute 2 trigger order(s), up to $0.40 of bounty (confirmed)  $1.20  $0.02   $1.18
 unload                   12  -                                                                   $0.00  $0.00   $0.00
 collect                 all  ETH/USD claim $5.12 (confirmed)                                     $0.00  $0.00  $-0.00
 WALLET   ADDRESS
 default  0x14dC79964da2C08b23698B3D3cc7Ca32193d9955
 fast     0x23618e81E3f5cdF7f54C3d65f7FBc0aBf5B21E8f

With no status file yet: No keeper has run with this config yet. Start one with bazaar keeper start. A file more than 30 seconds old shows not running (last seen N min ago). A red line under the header says sending is halted. Monitoring lists every field of the file.

keeper markets

bazaar keeper markets [-c bazaar-keeper.yaml]

Every market of the factory, sorted by label. It connects without loading wallets; with no snapshot yet it builds the index first, which takes as long as a first start.

 MARKET    ADDRESS                                     STATUS      HOURS    POSITIONS  LIVE ORDERS  INVENTORY
 AAPL/USD  0x5FbDB2315678afecb367f032d93F642f64180aa3  live        session         41           63          0
 BTC/USD   0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512  live        24/7           388          912      0.012
 ETH/USD   0x9fE46736679d2D9a65F0992F2272dE9f3c7fa6e0  live        24/7           521         1204          0
 ETH/USD   0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9  terminated  24/7             0            0          0

STATUS is live, adl, limbo, settling or terminated; HOURS is 24/7 or session (a market with trading hours); INVENTORY is the vault’s inherited position, in units. Two rows with one label are two markets (here a terminated one and its relisting): name them by address.

keeper earnings

bazaar keeper earnings [-c bazaar-keeper.yaml] [--since 7d] [--by job|market]

 MARKET    CALLS  REVERTED   EARNED      GAS      NET  CLAIMED
 -             1         0  $0.0000  $0.0002  $-0.0002    $0.00
 BTC/USD      22         2  $3.4100  $0.0410  $3.3690    $0.00
 ETH/USD      19         1  $1.9500  $0.0380  $1.9120   $12.40

Reads ledger.jsonl only: it works whether or not the keeper is running. No transactions in that period. when there are none. The Ledger explains the columns.

keeper opportunities

bazaar keeper opportunities [-c bazaar-keeper.yaml]

Lists the manual operations a dry run shows would go through now, or that a “too early” revert shows will open later, each with the command that runs it (naming the market by address):

finalizeTermination ETH/USD: every position is settled, or the escape hatch has opened (ready now) — bazaar keeper run finalize --market 0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9
terminateScheduledPair TSLA/USD: its scheduled cutoff has passed (opens at 2026-11-09 14:30 UTC) — bazaar keeper run terminate-scheduled --market 0x5FC8d32690cc91D4c39d9d3abcBD16989F875707

Or Nothing is waiting for a manual call. Manual Operations lists what it looks for.

keeper run

bazaar keeper run <operation> [--market <m>] [options]

Runs one operation now. Every call is simulated first; nothing that reverts in simulation is sent.

The automatic operations (the first eight) keep their job’s profit and loss rules unless --force. The manual ones show what would happen and ask Send it? (default no) before sending; without a terminal they print Not sent: pass --yes to send without confirming. A missing required option is a usage error (liquidate needs --market, exit 2).

Each result prints as a status, the job, the market and a summary, then its reason, what it earned or would earn, its transaction, and when a “too early” call opens:

$ bazaar keeper run liquidate --market ETH/USD --dry-run
simulated  liquidation  ETH/USD  liquidate 1 account(s), $2,050 notional
   earns $0.0500 for $0.0019 of gas
   would earn $0.0500 for about $0.0019 of gas

$ bazaar keeper run refresh-price --market BTC/USD
skipped  refresh  BTC/USD  refresh price
   below the profit rule: earns $0.0000 for $0.0021 of gas, needs ×1.25 and $0.001 net (allowLoss is off)

$ bazaar keeper run finalize --market 0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9
simulated  finalizeTermination  ETH/USD  finalize ETH/USD
   sent on request (profit and loss rules skipped)
   would earn $0.0000 for about $0.0031 of gas
? Send it? Yes
confirmed  finalizeTermination  ETH/USD  finalize ETH/USD
   sent on request (profit and loss rules skipped)
   earned $0.0000, gas $0.0029
   tx 0x8a3f…

The statuses: simulated (a dry run, or a preview), skipped (not sent, with why), confirmed, reverted (on chain), unknown (no receipt). Manual Operations covers each operation.

wallet

bazaar wallet new    [--name default] [--path <file>]
bazaar wallet import [--name default] [--path <file>]
bazaar wallet list   [-c bazaar-keeper.yaml]

new creates a key and saves it as an encrypted keystore; import encrypts a private key you paste; both ask for a password twice and print the YAML to add. list loads the config’s wallets and prints each one’s ETH and claimable earnings. Wallets & Secrets.

mock-prices

bazaar mock-prices [--rpc http://127.0.0.1:8545] [--price <FEED_ID=USD>]... \
  [--host 127.0.0.1] [--port 8787] [--token-env <NAME>]

Serves a mock Pyth Pro endpoint until Ctrl-C: the price stream, the request API and the symbols registry. Its updates are signed with the public test key that only a local deployment’s mock verifier trusts, and stamped with the chain’s time. For local testing only: Testing Locally with Anvil.

mock Pyth Pro on http://127.0.0.1:8787 (stream ws://127.0.0.1:8787/v1/stream), on the clock of http://127.0.0.1:8545; feeds: 2

Manual Operations

bazaar keeper run <operation> runs one operation now, on a market you name. It covers two kinds of operation:

• the automatic jobs, once: the same planning, simulation and spend policy the running keeper uses, on one market, when you want to act without waiting (or to see what the keeper would do);
• manual operations: calls no job makes on its own because they end markets or settle governance, pay nothing, and should happen only when someone decides they should. The keeper builds and checks them; you send them.

bazaar keeper opportunities tells you when a manual operation is available. The same calls are keeper.run.* in the library (The Keeper as a Library).

How a Run Works

1. The config is loaded and the wallets are unlocked (a keystore without a stored password is asked for).
2. The keeper connects: it checks the chain and the factory’s wiring, loads the snapshot in the state directory (or, with none, builds the index as a first start does), and replays the blocks since.
3. The market is resolved. --market takes a label (ETH/USD), a description, an address or a pair id. A label several markets carry is refused ('ETH/USD' matches several markets (0x…, 0x…); use an address); bazaar keeper markets shows the addresses.
4. The market’s state is read and fresh prints are fetched for its legs.
5. The call is planned, simulated, priced and judged; then sent, or (for a manual operation) shown and confirmed first.

Nothing that reverts in simulation is ever sent, and the daily spend caps, the low-balance halt and the fee ceilings apply to every run (Budgets & Losing Calls).

A one-shot run is a separate process from a running keeper. If it signs with a wallet the running keeper also uses, their nonces can collide: the run re-reads the nonce and retries once, so an occasional run works, but prefer running manual operations when the keeper is idle, or from a wallet of their own (they use default, see below).

Options

The Automatic Operations

Each uses the job’s settings from the config, or the job’s defaults when the config leaves the job off, sending from the job’s wallet (or, for a job not configured, default or the first wallet). The job’s market states apply: on a market in another state the run is skipped with the market is settling; this job runs while it is live. Planning finds nothing: skipped … no position is below its maintenance margin.

With an explicit list the planner’s filters are skipped (the chain still decides in simulation), so --accounts can name an account the index does not know about. liquidate --accounts on a closed market uses the stored price when it is at most 9.5 minutes old (the pair accepts one up to 10). execute-triggers --orders and execute-adl need a fresh print.

For collect, --force means “claim every balance that covers its gas, as on shutdown” rather than skipping the rules.

bazaar keeper run liquidate --market ETH/USD --dry-run
bazaar keeper run execute-triggers --market 0x9fE46736679d2D9a65F0992F2272dE9f3c7fa6e0 --orders 1042,1043
bazaar keeper run sweep-expired --market BTC/USD --force
bazaar keeper run collect --market ETH/USD,BTC/USD

The Manual Operations

Manual operations pay the caller nothing. They are sent from the wallet named default, or the first wallet configured when there is none by that name, as forced calls: no profit rule, but the spend caps, the fee ceilings and the low-balance halt apply. Each run first simulates (simulated, with what it would cost), then asks Send it? (default no), or sends at once with --yes. Without a terminal and without --yes, it prints Not sent: pass --yes to send without confirming. A preview that would revert or cannot be sent is printed and nothing is asked.

The contracts decide each condition; the simulation shows their answer. A call made too early comes back with when it opens (opens at 2026-11-09 14:30:00 UTC) where the revert says so. Bazaar’s Termination and Listing pages explain what each call does to the market.

finalize shares its in-flight key with the terminal-settlement job, so a run and a running keeper in the same process never finalize twice.

$ bazaar keeper run terminate-stale --market 0x5FC8d32690cc91D4c39d9d3abcBD16989F875707
simulated  terminateStalePair  GME/USD  end GME/USD (dead oracle)
   sent on request (profit and loss rules skipped)
   would earn $0.0000 for about $0.0042 of gas
? Send it? (y/N)

Terminate Scheduled

A market with a scheduled cutoff (from a UMA claim upheld or an insurer vote) is ended by terminateScheduledPair, which must carry archived Pyth Pro updates that prove the settlement price. All of them come from Pyth’s one-second channel (fixed_rate@1000ms), which issues one update per second, stamped on the second; the keeper asks the price endpoint’s request API (POST /v1/price) for the update stamped on each second it needs, so the token must cover that channel. The keeper builds the call with the SDK’s termination.terminateScheduledPair, which reads settlementRule(pair) from the terminator and fetches what the rule needs:

Before offering a set, the builder has the pair’s own oracle verify it exactly as the terminator will (fetchPriceAtTick for UMA’s rule, fetchChainedMedian for the chain rule, the same arguments, the update fee as value, from the sending wallet), and the summary names the price that call returns:

simulated  terminateScheduledPair  TSLA/USD  terminate TSLA/USD at its cutoff under the chain rule (the median of five chained prices), settling at 251.37
   sent on request (profit and loss rules skipped)
   would earn $0.0000 for about $0.0088 of gas

This matters because past the grace or the last resort the terminator catches a refused set and settles at the stored price instead, so simulating terminateScheduledPair alone would pass either way and label a stored-price settlement as a proven one. The keeper never sends a set the oracle refused as a proven settlement; the result’s reason says why, for example under the chain rule (the median of five chained prices): The oracle would not verify these updates (…). The stored-price fallback is open, so a call carrying them would settle at the market's stored price (250.1) instead: they are not offered as a proven settlement.

When nothing can be sent yet, the run is skipped with the reasons, such as Under UMA's rule (the one-second update stamped at the cutoff): Pyth's archive has no one-second update for feed … at second … yet. The stored-price fallback opens after …. A feed that carries no price at the cutoff (one listed after it, say) builds no chain: the market waits for its last resort like any other that cannot be proven. A run before the cutoff, or on a market without one, is skipped with the terminator’s own reason.

The Last Resort

Past lastResortTs, a call with no updates settles at the stored price: for good, at a price no Pyth update proves. The keeper plans that call as --stored-price allows:

Withheld, the run is skipped with why and what would change it: … The stored-price fallback is open but not offered: a proven settlement may still exist (…): try again later, or run with --stored-price always to settle at the stored price anyway. Planned, the preview says what it fixes, and the call is sent only with --accept-stored-price (and then --yes, or a yes at the prompt):

$ bazaar keeper run terminate-scheduled --market TSLA/USD --yes
simulated  terminateScheduledPair  TSLA/USD  terminate TSLA/USD at its cutoff at its stored price, 250.1 (the last resort is open)
   sent on request (profit and loss rules skipped); this settles the market irreversibly at its stored price, 250.1, stored 22 d 0 h ago (2026-10-18 14:30:00 UTC): no Pyth update proves it; under UMA's rule (…): …
   would earn $0.0000 for about $0.0061 of gas
Not sent: this settles the market at its stored price, which no Pyth update proves. Pass --accept-stored-price to send it.

In the library, keeper.run.terminateScheduledPair takes storedPrice and sends such a call only with acceptStoredPrice: true.

What Is Sent Is What Was Shown

The run previews the call, asks, and then builds the plan again just before sending: when the rule, the settlement price or the call differs from the preview’s (an archive that answered for the preview and not since, a verdict recorded in between), nothing is sent: the settlement changed since the preview (…): nothing was sent; run the command again.

Opportunities

bazaar keeper opportunities

Dry-runs every manual operation that might be due and lists the ones that would go through now (ready now), or that a “too early” revert shows will open later (opens at …), each with the command that runs it. Commands name markets by address, and only ids checked to be ids go into them.

Without a subgraph, claims, votes and listings are not found (their ids are not in the keeper’s index); the market and factory checks still run.

A running keeper scans the same way every 5 minutes and sends each finding as an opportunity alert (at most once a day each), when an alert channel is configured and opportunity is in alerts.notify (Running in Production).

Related Pages

• Commands: every run option.
• Budgets & Losing Calls: what applies to forced calls.
• Termination & Settlement: building the governance calls that schedule a termination.

The Keeper as a Library

Everything the bazaar command does is available from TypeScript in @liberta-labs/bazaar-keeper: build a keeper from the same config, listen to what it does, run one call, or run it all inside your own service. Use the library when the keeper is part of something larger (a trading system that also keeps its markets, a service with its own health checks and metrics), or to script one-off operations.

The package runs in Node 20 or later (it reads files, holds keys and opens sockets: it is not for browsers). Install it as in Setting Up a Keeper; the samples import from @liberta-labs/bazaar-keeper and @liberta-labs/bazaar-sdk.

Creating a Keeper

// Reads bazaar-keeper.yaml, the .env beside it and the environment, with the same rules as the CLI.
const cfg = loadConfig("bazaar-keeper.yaml");

// The CLI configures logging itself; a program does it once, before the keeper logs anything.
setupLogging(cfg.log.level, cfg.log.format);

let keeper: Keeper;
try {
  // Loads the wallets now: a keystore without a password in the config asks for it on a terminal.
  keeper = await Keeper.create(cfg);
} catch (e) {
  if (e instanceof ConfigError || e instanceof WalletError) {
    console.error(e.message); // one readable line, never a key or a password
    process.exit(2);
  }
  throw e;
}

ConfigError and WalletError messages are written for the person fixing the problem and never contain a key or a password. new Keeper(cfg) builds a keeper without loading its wallets yet; they load on the first connect() (and so on start() or any run.* call).

Configuring in Code

parseConfig takes the same keys as the YAML file. It does not read .env, fill ${NAME} references or apply the file’s secrets rules: the object is used as given, so take secrets from the environment or a secret store yourself.

// The same schema as the YAML file, with the same defaults and the same refusal of unknown keys.
// parseConfig does not read .env, fill ${NAME} references or apply the file's secrets rule: the
// object is used as given, so take secrets from the environment (or a secret store) yourself.
const cfg = parseConfig({
  network: "arbitrum-sepolia",
  factory: "0x0000000000000000000000000000000000000000",
  rpc: { http: env("RPC_HTTP_URL") },
  subgraph: { url: "none" },
  prices: { endpoint: "pyth", token: env("PYTH_PRO_TOKEN") }, // channel defaults to fixed_rate@200ms
  wallets: {
    default: { type: "keystore", path: "/srv/keeper/keys/default.json", password: env("KEEPER_KEYSTORE_PASSWORD") },
    fast: { type: "privateKey", key: env("KEEPER_FAST_KEY") },
  },
  jobs: {
    liquidation: { wallet: "fast" }, // {} or an object turns a job on; leaving it out keeps it off
    triggers: { wallet: "fast", minBountyUsd: 0.05 },
    unload: {},
    refresh: {},
    collect: { thresholdUsd: 10 },
  },
  budget: { maxSpendUsdPerDay: 20, minEthBalance: 0.005 },
  state: { dir: "/srv/keeper/state" },
  log: { level: "info", format: "json" },
});

Events

// A sent transaction's result, once its receipt is in.
const offAction = keeper.on("action", (r) => {
  console.log(`${r.job} ${r.market}: ${r.status}, earned $${r.rewardUsd.toFixed(4)} for $${r.costUsd.toFixed(4)} (${r.txHash})`);
});
// The moment a transaction is submitted, before its receipt.
keeper.on("sent", ([action, txHash]) => console.log(`sent ${action.job} ${action.summary}: ${txHash}`));
// lowBalance, jobPaused and endpointDown, whether or not an alert channel is configured.
keeper.on("alert", ([kind, message]) => console.warn(`alert ${kind}: ${message}`));
// Each `on` returns the function that unsubscribes.
offAction();

on(event, handler) returns a function that unsubscribes. A handler that throws or rejects is logged and never breaks the keeper. Skipped calls are not events (they repeat every tick); they are logged.

An ActionResult has:

One-Shot Runs

keeper.run holds every automatic job once and every manual operation, each naming its market on the call (a label, an address or a pair id). Each connects and syncs first when needed, so it works on a keeper that is not running as well as on one that is. Manual Operations explains what each does.

// One call, the market named on the call. A dry run simulates and reports, and sends nothing.
for (const r of await keeper.run.liquidate("ETH/USD", { dryRun: true })) {
  console.log(r.status, r.summary, r.reason);
  if (r.status === "simulated" && r.wouldSend) {
    console.log(`would earn $${r.expectedRewardUsd.toFixed(4)} for about $${r.costUsd.toFixed(4)} of gas`);
  }
}

// A manual operation returns one result. Reverts in simulation come back decoded.
const fin = await keeper.run.finalizeTermination("0x0000000000000000000000000000000000000000", { dryRun: true });
if (fin.error) console.log(`would revert: ${fin.error.toString()}`);
if (fin.opensAt) console.log(`opens at ${new Date(fin.opensAt * 1000).toISOString()}`);

The automatic jobs return ActionResult[] (one per call planned, or one skipped result saying why nothing was planned) and take { dryRun?, force? }; the list-taking ones accept the list either as an argument or in the options:

The manual operations return one ActionResult and take { dryRun? }: finalizeTermination(market), terminateStalePair(market), terminateScheduledPair(market), settleTerminationProposal(assertionId), executeInsurerTermination(market, proposalId), and under run.factory: settleDeploymentProposal(assertionId), expireStuckDeploymentProposal(pairId), settleIdentifierUpgradeProposal(assertionId), expireStuckIdentifierUpgradeProposal(), activateIdentifierUpgrade(). Ids are 32-byte hex strings (with or without 0x) or bytes.

// Automatic jobs, once. Each keeps its job's profit and loss rules unless force is set.
for (const r of await keeper.run.executeTriggers(MARKET, { dryRun: true })) show(r);
for (const r of await keeper.run.liquidate(MARKET, ["0x0000000000000000000000000000000000000001"], { force: true })) show(r);
for (const r of await keeper.run.sweepExpired(MARKET, [12n, 13n], { dryRun: true })) show(r);
for (const r of await keeper.run.collect("all")) show(r);

A manual operation sends at once unless dryRun is set, so preview it first, as the CLI does:

// Manual operations: simulate first, look at the result, then send.
const preview = await keeper.run.terminateScheduledPair(MARKET, { dryRun: true });
show(preview);
if (preview.status === "simulated" && preview.wouldSend) {
  show(await keeper.run.terminateScheduledPair(MARKET));
}

// The factory's operations sit under run.factory.
show(await keeper.run.factory.settleDeploymentProposal(ASSERTION, { dryRun: true }));

findOpportunities(keeper) returns what bazaar keeper opportunities prints: each Opportunity has operation, market (a label, for people), detail, command (the CLI command, naming the market by address), ready and opensAt, and describe() for one line.

// Every manual operation that a dry run shows would go through now, or that opens later.
for (const o of await findOpportunities(keeper)) {
  console.log(o.describe());
  if (o.ready) console.log(`   bazaar keeper ${o.command}`);
}

A one-shot run takes the same in-flight keys as the running keeper’s jobs, so in one process it never sends a call the keeper is already sending (already in flight: the keeper is sending this call; try again once it lands).

Starting and Stopping

// start() connects, then runs until stop(); it resolves once the shutdown is done.
const stopOnce = (): void => {
  // Waits up to 60 s for in-flight sends, claims earnings if jobs.collect.onShutdown, saves the snapshot.
  void keeper.stop({ timeout: 60 });
};
process.once("SIGINT", stopOnce);
process.once("SIGTERM", stopOnce);

try {
  await keeper.start();
} finally {
  await keeper.close(); // releases the price stream, the subgraph and alert clients
}

A keeper runs once: after stop(), start() throws this keeper has already run and stopped; create a new Keeper to start again. Calling start() while it runs throws the keeper is already running.

Status and State

stateDirFor(cfg) gives the state directory without building a keeper, and listMarkets(cfg) lists the factory’s markets with their labels without indexing anything.

Embedding in a Service

A keeper inside a long-running service, with a health endpoint and running totals for metrics:

const keeper = await Keeper.create(cfg);

// Running totals for a metrics system, fed by the "action" event (sent transactions only).
const totals = { sent: 0, reverted: 0, rewardUsd: 0, gasUsd: 0 };
keeper.on("action", (r: ActionResult) => {
  totals.sent += 1;
  if (r.status === "reverted") totals.reverted += 1;
  totals.rewardUsd += r.rewardUsd;
  totals.gasUsd += r.costUsd;
});

// GET /health: 200 while the keeper is running, has live prices and is allowed to send.
// GET /status: what `bazaar keeper status` reads (the same object as status.json).
const server = createServer((req, res) => {
  const s = keeper.statusDict();
  if (req.url === "/status") {
    res.writeHead(200, { "content-type": "application/json" });
    res.end(JSON.stringify({ ...s, totals }));
    return;
  }
  const healthy = keeper.running && s.prices.healthy && !s.halted && s.block - s.indexed < 64;
  res.writeHead(healthy ? 200 : 503, { "content-type": "application/json" });
  res.end(JSON.stringify({ healthy, block: s.block, indexed: s.indexed, prices: s.prices, halted: s.halted }));
});
server.listen(9464, "127.0.0.1");

let stopping: Promise<void> | null = null;
const shutdown = (): void => {
  stopping ??= keeper.stop().finally(() => server.close());
};
process.once("SIGINT", shutdown);
process.once("SIGTERM", shutdown);

try {
  await keeper.start(); // rejects if connecting fails (wrong chain, bad wiring, no deployment block)
} catch (e) {
  console.error(`the keeper could not start: ${e instanceof Error ? e.message : String(e)}`);
  process.exitCode = 1;
  server.close();
} finally {
  await keeper.close();
}

Points to keep in mind:

• One keeper per set of wallets, in one process (Running in Production).
• Handle SIGTERM by calling stop(), and give the process time to finish (up to timeout, plus the shutdown collect).
• Configure logging with setupLogging before creating the keeper; pass write to route lines into your own logger.
• Event handlers run on the keeper’s event loop. Keep them short; hand slow work (a database write, a network call) to a queue rather than awaiting it in the handler.
• The bazaar_sdk.* loggers never log keys or full URLs; your handlers should not either (pass URLs through the SDK’s redactUrl).

Related Pages

• Configuration Reference: every key parseConfig takes.
• Manual Operations: what each run.* call does.
• Testing Locally with Anvil: a keeper and a mock price server in one script.

Testing Locally with Anvil

Before a keeper spends real gas, you can run it against a local chain: a Bazaar deployment on Anvil, prices from a mock Pyth Pro server whose updates the local deployment’s verifier accepts, and every job enabled. You move the price and the clock yourself and watch each job do its work. This page covers the fastest way (the repository’s end-to-end suite), a local deployment of your own, the mock price server, and a keeper config for Anvil.

You need Foundry’s anvil (and cast, for poking the chain) and the repository built from source (Setting Up a Keeper).

The End-to-End Suite

The repository’s end-to-end tests do everything for you: they replay a recorded deployment of Bazaar’s current contracts on a fresh Anvil (no Bazaar checkout and no compiler needed), list an ETH/USD market, build a book, a stop-loss and a leveraged position, then run the real keeper with every job enabled against the mock price server, moving the price and the clock to give each job its work, and check each outcome on chain. It also reports the keeper’s latency from a price move to its send.

# a fresh Anvil with the flags the suite expects
anvil --port 8546 --block-time 1 --base-fee 10000000 --code-size-limit 100000

# in another terminal, from the repository
npx vitest run -c vitest.e2e.config.ts packages/keeper/test/e2e/keeper.e2e.test.ts

BAZAAR_E2E_RPC points the suite at another URL (default http://127.0.0.1:8546); with no Anvil answering there, the suite is skipped. Running all three e2e files (npx vitest run -c vitest.e2e.config.ts) adds a deployment smoke test and a run of the frontend SDK through the same scenario. Each file snapshots the chain first and reverts to the snapshot at the end, so the next file replays on the same Anvil; it also means the deployment is gone afterwards.

The Fixtures

packages/keeper/test/e2e/fixtures/ holds what the suite replays:

The deployment is 21 transactions from Anvil’s first account: twelve libraries through the deterministic CREATE2 deployer, then MockPythLazer (Pyth’s verifier, with no fee) and the call that makes it trust the public test signer, MockUSDC, MockOptimisticOracleV3, BazaarOracle, the BazaarPair implementation, BazaarPairLens, BazaarPairTerminator and BazaarFactory. Replayed on a fresh Anvil they land at the same addresses:

The fixtures’ README.md records the Bazaar commit they come from, and how to regenerate them whenever Bazaar’s contracts change (together with the SDK’s ABIs, npm run sync-abis).

A Local Deployment of Your Own

To keep a deployment running and point your own keeper at it, deploy from a Bazaar checkout:

# in a Bazaar checkout with its lib/ submodules
forge build script/DeployBazaar.s.sol test/mocks/MockArbSys.sol
anvil --port 8546 --block-time 1 --base-fee 10000000 --code-size-limit 100000

# Anvil's first default account (the public test mnemonic): a test key only
forge script script/DeployBazaar.s.sol --rpc-url http://127.0.0.1:8546 --broadcast \
  --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 \
  --code-size-limit 100000

# the pair reads its block number from ArbSys: place the mock at the precompile's address
cast rpc --rpc-url http://127.0.0.1:8546 anvil_setCode 0x0000000000000000000000000000000000000064 \
  "$(jq -r .deployedBytecode.object out/MockArbSys.sol/MockArbSys.json)"

The contracts’ addresses are in broadcast/DeployBazaar.s.sol/31337/run-latest.json. The deployment’s Pyth verifier is MockPythLazer: it charges no fee and trusts one signer, whose key is derived from a public label (keccak256("bazaar.test.pyth-lazer-signer"), the SDK’s lazer.localSignerKey()), so anyone on the chain can sign a price. Only a chain with id 31337 may trust that key: the deployment script refuses, anywhere else, a verifier that trusts it.

A factory with no markets gives the keeper nothing to do, so list one next. The e2e scenario’s Scenario.setup in packages/keeper/test/e2e/chain.ts is a working recipe: it mints MockUSDC to Anvil’s accounts, proposes an ETH/USD listing (Pyth Pro feed 2) with a $5,000 seed (proposePairDeployment), warps 48 hours, settles it (settleDeploymentProposal, which a keeper can also run: bazaar keeper run settle-listing --assertion …), deposits collateral and insurance with updates it signs with the test key, and builds a book, a stop-loss and a position close to liquidation. Listing Markets builds the same listing calls with the SDK.

The Mock Price Server

Bazaar’s pairs have every price update verified by Pyth’s verifier, and on Anvil that is MockPythLazer, which trusts the public test signer. The mock price server is a Pyth Pro endpoint whose updates that key signs, so the keeper (and any SDK client) can use it as prices.endpoint.

bazaar mock-prices --rpc http://127.0.0.1:8546 --price 2=2000

mock Pyth Pro on http://127.0.0.1:8787 (stream ws://127.0.0.1:8787/v1/stream), on the clock of http://127.0.0.1:8546; feeds: 2

It serves what the keeper and the SDK use, each update built by the SDK’s encoder, signed with the test key and stamped with the chain’s time (the latest block’s timestamp plus the time since that block was seen), so Anvil accepts it as fresh whatever you do to the clock:

Feeds are Pyth Pro feed numbers; --price and POST /mock/price also take the bytes32 a pair reports (its baseFeedId). Prices have exponent −8 and a confidence of 0.1% of the price, never less than one unit. ETH/USD (feed 2, which the keeper prices gas with) starts at 2000 unless --price sets it. Only ETH/USD has a symbol from the command line (MockPro in TypeScript takes symbols for the others), so markets on other feeds are labelled by their listing description. A feed serves its starting price for every past second, so the archive answers for any cutoff.

Set a price while it runs:

curl -X POST localhost:8787/mock/price -H 'content-type: application/json' \
  -d '{"id": 2, "price": 1850.5}'

Add "paused": true to stop the feed generating prices, as a market closing for the night would: its updates keep coming and carry its last price forward with the time that price was generated, so they read as stale, as Pyth’s do. "paused": false resumes it. "confidence": 0 makes its updates carry no confidence (the oracle refuses those, and the keeper never attaches them); "confidence": null goes back to the default.

The server is for local testing only. A POST to /mock/price must be JSON (content-type: application/json); it and a stream connection must carry a Host header that names this machine (localhost, an IP address, or the --host it listens on) and come from no web page on another origin, so a site open in a browser can neither set your prices nor read the stream, directly or through DNS rebinding. A name under .localhost does not count as this machine: a resolver that answers for it can point it anywhere. Its updates verify only on a chain whose verifier trusts the public test key.

It listens on this machine only (localhost, 127.0.0.0/8 or ::1) unless it has a token, since anyone who reaches it can set the prices a keeper acts on. To reach it from another machine (a container, say), give it one from the environment and listen on an address that machine reaches:

MOCK_PRICES_TOKEN=made-up-local-token bazaar mock-prices --host 0.0.0.0 --token-env MOCK_PRICES_TOKEN

Every request but the symbols registry must then present it, the price controls included (-H "authorization: Bearer $MOCK_PRICES_TOKEN"). A keeper sends it as prices.token, names the server by its IP address (another name is refused as DNS rebinding, unless it is the --host itself), and needs prices.allowInsecure: true to send the token over plain http to another machine.

In the Same Process

From TypeScript, MockPro and startMockPro run the same server inside your script, and the MockPro object sets prices directly:

// Updates signed with the public test key the local verifier trusts, stamped with the chain's time
// so Anvil accepts them as fresh. ETH/USD is Pyth Pro feed 2.
const mock = new MockPro({ rpc: RPC, prices: { [ETH_USD_FEED]: 2000 }, symbols: { [ETH_USD_FEED]: "Crypto.ETH/USD" } });
const prices = await startMockPro(mock, { port: 0 }); // port 0: any free port
console.log(`mock Pyth Pro at ${prices.url}, streaming at ${prices.streamUrl}`);

new MockPro({ rpc, prices, symbols, confidenceBp, token }) takes the chain whose clock it follows (a URL, an EIP-1193 transport or an SDK Chain; left out, this machine’s clock, or a clock you give), starting prices and symbols by feed, the confidence in basis points (default 10), and a token every request and stream connection must then present. startMockPro(mock, { host?, port? }) resolves once it listens and returns its url, its streamUrl and a close(). mock.setPrice(feed, usd) moves a price, mock.pause(feed) and mock.resume(feed) stop and restart it, and mock.setConfidence(feed, c) fixes its confidence.

A Keeper Config for Anvil

network: anvil
factory: "0xc6e7DF5E7b4f2A278906862b61205850344D4e7d"

rpc:
  http: http://127.0.0.1:8546
  maxRequestsPerSecond: 200

subgraph:
  url: none                      # index from logs: on a fresh chain the scan is short

prices:
  endpoint: http://127.0.0.1:8787  # bazaar mock-prices: no token needed
  sendMarginSeconds: 0.5         # Anvil's one-second blocks land prints quickly

wallets:
  default:
    type: privateKey
    key: ${ANVIL_KEEPER_KEY}     # in .env: one of Anvil's test keys, never a real one

jobs:
  liquidation: {}
  triggers: {}
  unload:
    recheckSeconds: 2
  adl: {}
  refresh: {}
  terminalSettlement:
    finalizeMaxCostUsd: 1
  sweepExpired:
    minBatch: 1
  collect:
    thresholdUsd: 0.01
    intervalSeconds: 3

budget:
  minEthBalance: 0.001

state:
  dir: ./state-anvil             # separate from any real keeper's; relative to where you start it

engine:
  idleRefreshSeconds: 1.5
  simCooldownSeconds: 1

# .env beside it: Anvil's eighth default account, m/44'/60'/0'/0/7 of the public test mnemonic
ANVIL_KEEPER_KEY=0x4bbbf85ce3377467afe5d46f804f221813b2bb87f24d81f60f1fcdbf7cbf4356

The wallet key is a secret key, so even a public test key goes in .env. Anvil’s accounts start with 10,000 ETH. Then:

bazaar keeper doctor -c anvil.yaml
bazaar keeper start -c anvil.yaml

doctor and the log say factory … is not an official deployment: expected on Anvil. With startBlock left out, the first start finds the factory’s deployment block by searching the chain’s history, which Anvil keeps.

The same keeper in one script, with the mock server, moving the price and pausing the feed:

const cfg = parseConfig({
  network: "anvil",
  factory: FACTORY,
  rpc: { http: RPC, maxRequestsPerSecond: 200 },
  subgraph: { url: "none" }, // index from logs; on a fresh Anvil the scan is short
  prices: { endpoint: prices.url, sendMarginSeconds: 0.5 },
  wallets: { default: { type: "privateKey", key: KEEPER_KEY } },
  jobs: {
    liquidation: {},
    triggers: {},
    unload: { recheckSeconds: 2 },
    adl: {},
    refresh: {},
    terminalSettlement: { finalizeMaxCostUsd: 1 },
    sweepExpired: { minBatch: 1 },
    collect: { thresholdUsd: 0.01, intervalSeconds: 3 },
  },
  budget: { minEthBalance: 0.001 },
  state: { dir: mkdtempSync(join(tmpdir(), "bazaar-keeper-")) }, // a fresh index every run
  engine: { idleRefreshSeconds: 1.5, simCooldownSeconds: 1 },
});
setupLogging("info");
const keeper = await Keeper.create(cfg);
keeper.on("action", (r) => console.log(`${r.job}: ${r.status} ${r.summary}`));
const running = keeper.start();

// Move the price; the keeper sees it on the next update (the mock streams every 200 ms by default).
await new Promise((r) => setTimeout(r, 10_000));
mock.setPrice(ETH_USD_FEED, 1500);
// Stop the feed generating prices, as a market closing for the night would: its updates carry the
// last price forward, so the keeper attaches none of them.
mock.pause(ETH_USD_FEED);
await new Promise((r) => setTimeout(r, 10_000));
mock.resume(ETH_USD_FEED);

Moving the Clock

Many jobs wait for time: the refresh bounty for 5 minutes or a day, the unload floor for 3 minutes, an ADL auction for 10, a termination for its cutoff. Anvil lets you jump:

cast rpc --rpc-url http://127.0.0.1:8546 evm_increaseTime 3600   # one hour later…
cast rpc --rpc-url http://127.0.0.1:8546 evm_mine                # …from the next block

The keeper follows the chain’s clock (the latest block’s time), and the mock stamps every update with it, so prices stay fresh across a jump.

Two things to expect:

• One price a second. A pair stores the price a call carries only when it was generated in a later second than the price it holds; within a second the first one stands. A move made in the second of the pair’s last stored price reaches the chain with the next second’s update, for any sender, and the keeper plans it then (The Price a Call Is Judged At). The e2e suite waits for the chain to pass that second before each move.
• The stream’s cadence. The mock streams on the configured channel (fixed_rate@200ms by default), so a move takes up to one interval to reach the keeper before the keeper’s own reaction time.

Related Pages

• Commands: every mock-prices option.
• Configuration Reference: what each Anvil-specific value changes.
• Development: the repository’s other tests.

Troubleshooting

What each doctor failure and each common warning means, and how to fix it. Messages are quoted as the keeper prints them; … stands for the part that varies. Run bazaar keeper doctor first: it checks everything start relies on and names the failing piece. Add --debug before the command (bazaar --debug keeper start) for a full stack trace.

The Config

no config at /home/me/keeper/bazaar-keeper.yaml; run bazaar keeper init to create one No file at the path. Run bazaar keeper init, pass -c <path>, or run from the config’s directory.

the config is not valid: followed by one line per problem The schema refused something. Each line names the key: Unrecognized key(s) in object: 'chunk' is a typo (unknown keys are always refused), a keystore wallet needs path a missing field, Expected number, received string a value of the wrong type. Every key is in Configuration Reference.

… has no official factory address in this release yet; set factory to the deployment you want to keep No network preset carries an official factory address yet. Add factory: "0x…" (quoted).

a custom network needs chainId and factory network: custom needs both.

… holds a secret written into the file (a ${NAME:-default} default counts) … A key, password, phrase, API key, bot token or Discord webhook is written into the YAML. Put the value in .env and write ${NAME} (the secrets rules).

rpc.http is a URL with a key in its path, written into the file … The URL may carry a credential. Put the whole URL in .env (http: ${RPC_HTTP_URL}), or only the key (https://arb-mainnet.g.alchemy.com/v2/${ALCHEMY_KEY}). (The printed suggestion may show the key part masked; write ${NAME} there.) The same applies to subgraph.url, prices.endpoint, alerts.webhook.url and a remote signer’s url.

prices.headers.X-Api-Key holds a value written into the file … Header values must be ${NAME}, or a scheme and a reference: Bearer ${NAME}.

rpc.http: environment variable RPC_HTTP_URL is not set (add it to .env or export it) The .env beside the config lacks the variable, or the keeper runs from a service whose environment does not have it. Check the .env is next to the config file (not the current directory).

… is not valid YAML: … Often a ${NAME} inside a flow mapping ({ botToken: ${TG_BOT_TOKEN} }): write the mapping in block style, one key per line. Or an unquoted value starting with a YAML indicator.

job liquidation uses wallet 'fast', which is not under wallets Add the wallet under wallets, or change the job’s wallet.

A job does not run, and nothing says why A job key with nothing under it (liquidation:) is null, which turns the job off. Write liquidation: {}. doctor’s Jobs line lists the jobs that are on.

prices.endpoint: the 'bazaar' price endpoint has no URLs yet; … bazaar is the default endpoint, and it does not exist yet. Set prices.endpoint: pyth with your own Pyth Pro access token in prices.token, or the URL of a Pyth Pro compatible service.

prices.apiKey is not a setting: the Pyth Pro access token goes in prices.token (a Pyth Core or Hermes key does not work), and prices.endpoint must be pyth or the URL of a Pyth Pro compatible service A config written for Pyth Core. It is reported before any ${NAME} is filled, so an old variable that is gone from .env does not hide it. Replace apiKey with token: ${PYTH_PRO_TOKEN} (a Pyth Pro access token, in .env), and set prices.endpoint to pyth or a Pyth Pro compatible URL.

prices.endpoint names a Hermes (Pyth Core) service, and the keeper sends its Pyth Pro token wherever prices are asked for: … (Or prices.restUrl, prices.streamUrls.) An endpoint left from a Pyth Core setup: the keeper would send its Pyth Pro token there. Set prices.endpoint to pyth, or to the URL of a Pyth Pro compatible service.

prices: the price token (prices.token) holds a line break or another character a request header cannot carry: re-enter it The token in .env was pasted with something around it. Paste it again, on one line.

rpc.send is 'sequencer', but arbitrum-sepolia has no sequencer endpoint preset Only Arbitrum One has one. Remove rpc.send, or give a URL.

The RPC

✘ RPC … unreachable: … The URL is wrong, the provider is down, or the key is invalid. The printed URL is masked; check the value in .env.

✘ RPC chain 1, but network arbitrum-one is chain 42161 (start: the RPC is on chain 1, but network arbitrum-one is chain 42161.) The URL is for another chain. Use the network’s URL, or fix network.

⚠ RPC … no eth_call state overrides: rewards cannot be measured before sending, so paid jobs will skip The node refused (or ignored) an eth_call with a state override, which the keeper needs to place its probe contract and measure rewards. The keeper still runs: calls are simulated directly, reverts are still caught, but every reward reads as 0, so paid calls fail the profit rule and only unpaid duties and jobs with allowLoss send. Use a provider whose eth_call accepts the state-override parameter (Arbitrum Nitro nodes do; some gateways strip it), and run doctor again.

could not find the factory's deployment block (…). Set startBlock in the config … A first start without a subgraph needs the factory’s deployment block, and the RPC could not answer historical eth_getCode reads (the node may not keep historical state). Set startBlock to the block the factory was deployed in (a block explorer shows it), use an RPC that keeps historical state, or configure a subgraph.

the node refused logs for 2000 blocks (…); asking for 1000 at a time. A lower rpc.logChunk avoids the refused requests Logged at info level, once per scan. The provider caps eth_getLogs ranges or results. The keeper halves the range until the node accepts it (down to one block) and widens it again after eight successes, so it keeps working; set rpc.logChunk to what your provider allows (often 500 to 10,000 blocks) to skip the refused requests.

engine step failed: … (at most every 30 s) A tick failed: often a rate limit (HTTP 429) or a timeout. The next tick resumes where it stopped. Persistent: lower rpc.maxRequestsPerSecond, raise engine.idleRefreshSeconds, or use a faster plan.

chain reorganized below block …; re-reading the last 64 blocks The stored head’s hash changed. Nothing to do: the keeper rewinds and re-applies.

The Factory

✘ Factory 0x…: … The factory cannot be read: the address is wrong, has no code on this chain, or is not a Bazaar factory. Check the address against the deployment and the network.

✘ Wiring the lens belongs to a different factory (or the terminator …, … does not report a factory) (start: refusing to start: ….) The factory points at a lens or terminator that does not point back at it. That is not a deployment the keeper will keep; check you have the right factory.

factory 0x… is not an official deployment (a warning) The factory is not a network preset’s official one. At present no preset has one, so every deployment shows this. It changes nothing in how the keeper runs.

The Subgraph

✔ Subgraph synced to block … (N blocks behind) A lagging subgraph is harmless: the keeper bootstraps from the subgraph’s own block and replays the chain’s logs from there, and every decision is made from chain state. A very large lag only makes the first replay longer.

⚠ Subgraph … with indexing errors (start: the subgraph reports indexing errors; chain reads will correct what it misses) The subgraph may be missing accounts or orders. The keeper uses what it has and re-reads every candidate from the chain; to be complete, configure a healthy subgraph or subgraph.url: none.

✘ Subgraph …; the keeper falls back to chain logs (start: subgraph unavailable (…); indexing from chain logs instead) The subgraph cannot be reached or returned something unusable. A first start indexes from logs instead (which needs startBlock or historical state); later starts do not use the subgraph.

Prices

✘ Prices … The price endpoint failed: a bad or missing token (prices.token; price endpoint refused the request (HTTP 401) or 403), a wrong URL, or a service down. A token that does not cover a feed or the channel can be refused the same way.

⚠ Prices the fixed_rate@200ms stream is not delivering (…): the keeper would poll the request API every 1 s instead The request API answered but the WebSocket stream did not: a stream URL is wrong (prices.streamUrls), a proxy or firewall blocks WebSockets, or the token is refused on the stream. The keeper still runs on polls, a step behind the stream.

price stream refused the subscription for feed(s) N on …, or price stream left out feeds it does not serve on … Pyth does not serve those feeds on the configured channel (prices.channel) for your token: a feed whose fastest channel is slower than the one asked for, or a feed the token does not cover. Choose a slower channel, or ask Pyth. Other feeds are unaffected.

price stream went quiet: no new update for 10 s No endpoint brought a new update for prices.streamIdleTimeoutSeconds: every fixed-rate channel sends one per interval whether or not a price changed, so the connections are dropped and reconnected.

a price update is signed by 0x…, which is not a signer Pyth's verifier trusts: refusing it With prices.checkSigners on, the keeper asks the deployment’s verifier whether it trusts each update’s signer, drops the stream endpoint that sent one it does not (it reconnects later), and refuses a request API response that carries one. An endpoint that is not Pyth’s (a proxy, a local mock) must pass Pyth’s signed bytes through unchanged.

prices.checkSigners is off: price updates are used whoever signed them. … At start, and in doctor’s Prices lines. Without the check, a forged update fails only on chain, and the ETH/USD print that prices gas reaches no contract. Turn it back on unless the keeper cannot keep up with the stream.

⚠ Prices N/M markets have a print, or at runtime price endpoint sent no print for feed 0x…: markets on it get no price until it does … The endpoint serves no print for some markets’ feeds: it does not carry that feed, the token does not cover it, Pyth has no price or no confidence for it (the oracle refuses a price without one, so the keeper never attaches it), or the feed is closed (a market with trading hours outside them). Markets on it get no fresh price: liquidation still works from a stored price up to 9.5 minutes old, other price-driven jobs wait. Check the endpoint serves the feed.

… not fresh right now (AAPL/USD, …) Those markets have a print, but not one recent enough to send: usually a session market outside its hours. Normal.

price endpoint: … (repeated), and status shows prices down: … The stream or the polls are failing. After three failures in a row prices are marked unhealthy and a stream falls back to polling for a minute, then tries the stream again. Calls that need a fresh print wait. Fix the endpoint; the keeper recovers on its own.

ignored a print for feed 0x… dated N s ahead of the clock … The endpoint’s print is in the future relative to the chain’s clock: the endpoint is wrong, or (on a local chain) the clock was moved backwards. Prints more than 5 s ahead are ignored.

⚠ Prices no fresh, plausible ETH/USD print: gas is priced at the $3000 fallback (never below gas.ethUsdFloor, $1000) The endpoint serves no ETH/USD print, or one older than gas.ethUsdMaxAgeSeconds, or one outside $100 to $1,000,000. Gas is priced at gas.ethUsdFallback, never below gas.ethUsdFloor. The keeper works, but the USD costs it books are only as good as the fallback: keep it near the real price, or fix the feed.

Wallets

wallet default: wrong keystore password The password in .env (or typed) does not open the keystore.

wallet default: cannot read keystore /…/default.json: No such file or directory The path is wrong, or (in Docker) the file is outside the mounted directory.

no wallet configured: watch-only, nothing will be sent There is no wallets section. Results end with (watch-only: no wallet configured), and collect says needs a wallet to simulate (watch-only).

Keystore Password Prompts in Docker

wallet default (default.json) needs a password: set wallets.default.password: ${KEEPER_KEYSTORE_PASSWORD} in the config and KEEPER_KEYSTORE_PASSWORD in .env or the environment, or start the keeper in a terminal to be asked for it The config has no password for a keystore, and the keeper has no terminal to ask on: a detached container, a systemd service, pm2. Add password: ${KEEPER_KEYSTORE_PASSWORD} under the wallet and KEEPER_KEYSTORE_PASSWORD=… to the .env beside the config (or the service’s environment). In Docker, docker run -it gives the keeper a terminal for a one-off run, but not a detached one; let init store the password when it asks.

Low Balance

✘ Wallet default 0x…, 0.00100 ETH: below budget.minEthBalance; fund it At runtime: a lowBalance alert and, in status, sending paused: default (0x…) holds 0.00100 ETH, below budget.minEthBalance. While any wallet is below budget.minEthBalance, nothing is sent from any wallet. Send ETH to the wallet; sending resumes within a minute. Lower minEthBalance only if you know your calls’ gas.

Markets

Labels Shared by Several Markets

jobs.liquidation.markets: 'ETH/USD' names 2 markets (0x…, 0x…); it covers each of them, in the statuses each job runs in. Write an address to choose one A label is not unique: a market relisted after a termination keeps its predecessor’s label, and a composite is labelled after its base. A job’s label covers every market carrying it; each job acts only on those in a state it runs in (so a live-market job acts on the live one, while terminal settlement and collect still reach the terminated one). To choose one, write its address. bazaar keeper markets lists them.

For a one-shot run a shared label is refused: 'ETH/USD' matches several markets (0x…, 0x…); use an address.

no market called 'XYZ/USD'. Markets: … No market carries that label or description. Check the spelling against bazaar keeper markets.

0x… is not a market of this factory An address under markets or exclude, or in --market, is not one of this factory’s markets.

the jobs' markets were not updated for the new listing: … A new market was listed while the keeper ran, and re-resolving the jobs’ markets failed. Each job keeps the markets it had; fix the config and restart to pick the listing up.

Skips and Pauses

A call that is not sent is logged with its reason (each distinct reason at most every five minutes at info level). The common ones:

Paused Jobs

liquidation paused on ETH/USD for 15 min after repeated reverts (a jobPaused alert) safety.pauseAfterReverts (3) transactions in a row reverted on chain: the state changed between the simulation and the block, usually because a faster keeper took the same work. The job stops on that market for safety.pauseMinutes (15), then resumes. Pauses are kept by label, so other markets sharing the label pause too. Frequent pauses mean you are losing races: give the job its own wallet, use rpc.send: sequencer on Arbitrum One, and run closer to your RPC.

the transaction reverted on chain (state changed after the simulation) One such revert. You paid its gas; the ledger books it as reverted.

no receipt within the timeout; the nonce is re-read before the next send The transaction was sent but no receipt arrived within 90 s. It is booked as unknown at its estimated cost, and its candidate stays locked for 5 minutes in case it lands. Check the hash on an explorer. If the send itself got no answer, an endpointDown alert says so.

send refused: … The node refused the signed transaction (insufficient funds, a fee too low for the node’s minimum). Nothing went out.

Status and Commands

No keeper has run with this config yet. Start one with bazaar keeper start. status found no status.json for this config’s network and factory. Check -c names the same config the running keeper uses (the state directory depends on state.dir, the chain and the factory).

not running (last seen N min ago) The status file is older than 30 seconds: the keeper stopped or hangs. Check its log.

init needs an interactive terminal. Copy bazaar-keeper.example.yaml and edit it instead. Run init in a terminal (in Docker, docker run -it), or write the config by hand.

Not sent: pass --yes to send without confirming. A manual operation without a terminal to confirm on. Add --yes once you have checked the preview.

liquidate needs --market (and the like) The operation needs that option (Commands).

Commands are slow before the first start markets, opportunities, run and wallet list connect as start does: with no snapshot yet they build the index first, and do not save it. Start the keeper once; afterwards they load its snapshot.

Related Pages

• Setting Up a Keeper: what doctor checks.
• Budgets & Losing Calls: every skip rule.
• Running in Production: watching for these in status.json.

Connecting

Every use of the SDK starts with a connection: one chain, one Bazaar deployment, and optionally a price source and Bazaar’s subgraph. This page covers Bazaar.connect and connect() with every option, the transports they accept, price sources (and how to keep a price API key out of a browser), the subgraph, the integrator address, the chain check, checking market addresses, and the errors a connection can raise.

What a connection is, and what the SDK caches on it, is on Core Concepts.

Bazaar.connect

const bz = await Bazaar.connect({
  transport: window.ethereum, // an EIP-1193 provider, a viem client, a JsonRpc, or a JSON-RPC URL
  factory: FACTORY, // the deployment: everything else is read from it
  chainId: 42161, // optional: refuse any other chain
  prices: { token: pythToken }, // optional: Pyth Pro client options, a ProClient, or any source
  subgraph: "https://subgraph.example.com/bazaar", // optional: a URL, { url, apiKey }, or a source
  integrator: MY_FEE_ADDRESS, // optional: named on every order this connection creates
});

bz.chainId; // 42161
bz.deployment; // { factory, lens, terminator, oracle, usdc }
bz.ctx; // the BazaarContext every function runs on

Bazaar.connect(options) does four things:

1. Registers the user-facing error messages (installUserMessages()), so a decoded revert reads as a sentence from then on.
2. Wraps the transport in a Chain: a URL becomes the SDK’s own HTTP client (JsonRpc), anything else is used as given.
3. Reads the chain id and, in one batched call alongside it, the factory’s lens, pairTerminator, oracle and usdc. (The first batch also detects how this node batches; see Transports.)
4. Checks the chain id against chainId, when given, and that the factory answered all four reads.

It returns a Bazaar with the context bound into every area. Nothing else is read until you ask: the market list loads on the first listMarkets (or anything that resolves a market by name).

The returned object has:

connect() and Bazaar.from

connect(options) is what Bazaar.connect calls. It returns the bare BazaarContext, for code that uses the per-area functions (markets.getMarket(ctx, ...)), and takes sources only: its prices must be a PriceUpdateSource and its subgraph a SubgraphSource, not URLs. Bazaar.from(ctx) wraps a context in the facade.

// connect() is what Bazaar.connect calls: it takes sources, not URLs, and returns the bare context.
const ctx = await connect({
  transport: rpc,
  factory: FACTORY,
  chainId: 42161,
  prices: proPriceSource({ token: pythToken }),
  subgraph: history.httpSubgraph("https://subgraph.example.com/bazaar"),
  integrator: null, // zero address: no integrator fee on this connection's orders
});
const wrapped = Bazaar.from(ctx);

The SDK keeps its caches per context object. Two contexts built from the same options (or a copy made with { ...ctx, prices }) each list the markets once.

Transports

A Transport is anything with EIP-1193’s request({ method, params }). Four kinds are common:

// A browser wallet: reads, and the wallet the user signs with.
const viaWallet = await Bazaar.connect({ transport: window.ethereum, factory: FACTORY });

// A viem client (wagmi's clients are viem clients too).
const client = createPublicClient({ chain: arbitrum, transport: http("https://arb1.arbitrum.io/rpc") });
const viaViem = await Bazaar.connect({ transport: client, factory: FACTORY });

// A URL: the SDK builds a JsonRpc with its defaults.
const viaUrl = await Bazaar.connect({ transport: "https://arb1.arbitrum.io/rpc", factory: FACTORY });

// A JsonRpc of your own, to change those defaults.
const rpc = new JsonRpc(`https://arb-mainnet.g.alchemy.com/v2/${process.env.ALCHEMY_KEY}`, {
  perSecond: 10, // requests per second (default 25)
  timeoutMs: 15_000, // per request (default 30 s)
  retries: 5, // after transient failures, doubling from 500 ms (default 3); never for sends
  headers: { "x-client": "my-bot" }, // sent with every request
  maxResponseBytes: 32 * 1024 * 1024, // default 64 MiB
});
const viaJsonRpc = await Bazaar.connect({ transport: rpc, factory: FACTORY });
console.log(rpc.displayUrl); // "https://arb-mainnet.g.alchemy.com/v2/***": safe to log

• A browser wallet’s provider (window.ethereum, or one from an EIP-6963 picker). Reads go through the wallet’s own RPC. The same object is the wallet you send and sign with.
• A viem client. A PublicClient or WalletClient has a matching request; wagmi’s clients are viem clients.
• A URL, http(s)://. The SDK makes a JsonRpc with its defaults.
• A JsonRpc of your own, to change those defaults:

A JsonRpc never puts its URL or a header’s value into an error message: displayUrl is the URL with every part that may be a key masked. Its errors are HttpError (a non-2xx answer, with status), RpcError (the node’s JSON-RPC error, with code and revertData) and ResponseTooLargeError.

What the node needs. Batched reads go through the SDK’s probe contract placed with an eth_call state override where the node honors overrides, through Multicall3 where it is deployed, and as parallel eth_calls otherwise; the SDK detects which once per connection. Any node works. Live updates use eth_getLogs, and wake on eth_subscribe("newHeads") when the transport emits EIP-1193 "message" events (a JsonRpc does not, so a URL connection polls). See Live Updates.

Prices

Calls that need the price (order creation and amendment, trigger execution, a withdrawal with a position, an insurance exit) carry a signed Pyth Pro update, fetched from the connection’s PriceUpdateSource when the call is built. Reads use it too: the market list takes labels from Pyth Pro’s symbols registry, and snapshots ask the source for the price of trading-hours markets to tell whether their venue is open.

Pyth Pro needs a token on every request and every stream connection. There are two kinds: the long-lived API key, and short-lived tokens minted from it (they live at most 15 minutes). A server (a bot, a keeper, a relayer) may hold the key. A browser must not: code in a bundle is public. A frontend therefore either gets short-lived tokens from its own backend (below), or leaves prices out and routes orders through a relayer that attaches the update (Gasless Trading).

prices takes three forms:

• Options for a client: { token }, where token is the API key (servers), or a function that returns a short-lived token and is called for each request and each connection attempt. The other ProClient options go in the same object.
• A ProClient you made, to share it with a live stream.
• A PriceUpdateSource you build: proPriceSource(...), a LivePrices stream, or your own.

// The options form of `prices` builds this source; build it yourself to keep hold of its client.
const prices = proPriceSource({
  token: process.env.PYTH_PRO_API_KEY, // sent as "Authorization: Bearer <key>": the key itself, on servers only
  channel: "fixed_rate@200ms", // the default; also "real_time", "fixed_rate@50ms", "fixed_rate@1000ms"
  timeout: 5, // seconds per request (default 10)
});
const withPrices = await Bazaar.connect({ transport: rpc, factory: FACTORY, prices });

// One ProClient can serve both the calls' updates and a live stream.
const pro = new ProClient({ token: pythToken });
const shared = await Bazaar.connect({ transport: window.ethereum, factory: FACTORY, prices: pro });
const live = await shared.livePrices(); // streams through the same client

// Connecting has the source refuse any update not signed by a signer the deployment's Pyth verifier
// trusts (one cached read per signer). The chain checks every update a call carries either way.
const unchecked = await Bazaar.connect({ transport: rpc, factory: FACTORY, prices: { token: pythToken }, checkSigners: false });

proPriceSource(options | ProClient) and new ProClient(options) take:

The source has latest(feedIds) (one request for exactly those feeds, so the update carries them and nothing else, both legs of a composite in one; and the second the oldest of their prices was generated in), atTick(feedIds, second) (the one-second channel’s update for a past second, which settlement proofs are made of), prints(feedIds) (the parsed prints) and client, its ProClient. Every price is read from the signed update itself, never from the JSON an endpoint sends beside it, so a dishonest endpoint can only withhold prices, not change them, and every update is kept exactly as Pyth’s verifier reads it: bytes an endpoint appends to one never reach a call’s calldata.

The client keeps its credentials out of sight: the token, the headers and the configured URLs are private fields, so printing or serializing a client (or a context, or a PriceService) shows none of them; every message it produces has them masked and every URL in it redacted; and a request carrying a token or headers never follows a redirect.

Whose signature. Pyth signs every update, and the chain accepts one only from a signer its verifier contract trusts. connect gives the source the same test: it reads the verifier from the deployment’s oracle (pythLazer()) and asks it isValidSigner(signer) for each new signer, keeping the answer for a minute. An update signed by anyone else is refused before it becomes a price your page shows or a call carries. Checking costs one signature recovery per update; pass checkSigners: false to leave the source as you gave it. The chain verifies every update a call carries either way.

Feed IDs. A Pyth Pro feed is a number (BTC/USD is 1). The contracts hold it in a bytes32 (0x00…01), and the SDK uses that form everywhere a feed ID appears; feedIdHex(1) and proFeedId(id) convert. A composite market’s ID is a hash, and its two legs are raw feed IDs.

Tokens for a Browser

Your backend exchanges the API key for a short-lived token and hands that to your page:

const KEY = process.env.PYTH_PRO_API_KEY ?? ""; // stays on the server
const ALLOWED_ORIGIN = process.env.ALLOWED_ORIGIN ?? "https://app.example.com";

// One token serves every visitor until a minute before it expires (Pyth's tokens live at most 15 minutes).
let held: MintedToken | null = null;
async function currentToken(): Promise<MintedToken> {
  const now = Date.now() / 1000;
  if (!held || (held.expiresAt ?? 0) - 60 < now) held = await mintProToken(KEY);
  return held;
}

createServer(async (req, res) => {
  res.setHeader("access-control-allow-origin", ALLOWED_ORIGIN);
  if (req.method !== "GET" || req.url !== "/api/pyth-token") {
    res.writeHead(404).end();
    return;
  }
  // Gate this like any endpoint of yours (a session, a rate limit): whoever is handed a token can
  // read prices on your key until it expires.
  try {
    const { token, expiresAt } = await currentToken();
    res.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" });
    res.end(JSON.stringify({ token, expiresAt }));
  } catch (e) {
    console.error(e instanceof Error ? e.message : e); // the SDK's errors never hold the key
    res.writeHead(502).end();
  }
}).listen(8787);

The page asks for one when it needs it, and keeps it until shortly before it expires:

// In a browser: short-lived Pyth Pro tokens from your own backend, which holds the API key. The
// endpoint answers { token, expiresAt }; a new one is fetched a minute before the held one expires.
const pythToken = cachedToken(() => fetch("/api/pyth-token").then((r) => r.json()));

cachedToken(mint, { margin }) calls mint only when it holds no token or the one it holds expires within margin seconds (default 60), and shares one call among concurrent requests. A token whose expiry the endpoint does not give is reused for five minutes. Gate the endpoint like any other of yours: whoever is handed a token can read prices on your key until it expires.

Your Own Source

A PriceUpdateSource is one method, and two optional ones:

A source that is not a proPriceSource gives the SDK no symbols registry and no parsed prints: the market list then takes labels from Pyth’s own registry (PYTH_PRO.symbolsUrl), and snapshots judge a trading-hours venue only from live prices you pass them.

The Subgraph

History (trades, candles, orders and their events, positions, fees, liquidations, insurance, proposals and votes) comes from Bazaar’s subgraph. The market list also takes each market’s listing description from it, when it can; every other read comes from the chain.

const withHistory = await Bazaar.connect({
  transport: rpc,
  factory: FACTORY,
  subgraph: history.httpSubgraph("https://gateway.thegraph.com/api/subgraphs/id/...", process.env.GRAPH_API_KEY, {
    timeoutMs: 10_000, // per query (default 30 s)
  }),
});
const lag = await withHistory.history.subgraphLag(); // how far the index trails the chain

subgraph takes a GraphQL URL, { url, apiKey }, or a SubgraphSource (anything with query(query, variables)). The URL forms build history.httpSubgraph(url, apiKey?, options?), which POSTs { query, variables } and sends the key as Authorization: Bearer <key> (The Graph’s gateway also takes it in the URL path; such a URL is masked in errors). Its options:

The same rule about keys applies as for prices. Without a subgraph, every history function throws a ConnectError; the rest of the SDK is unaffected. See History.

The Integrator Address

An order names an integrator, an address that earns 0.25 bp of each fill’s notional from the side of the fill that carries it (see Bazaar’s integrator guide). The connection’s integrator is written into every order trade.createOrder and trade.prepareOrder build (and so into gasless order requests). It is your users’ surcharge as well as your revenue: leave it unset (the zero address) to charge none. Collect what it earns with trade.claimFees on each market.

Chain Checks

With chainId given, connect throws a ConnectError when the transport is on another chain. Give it in a frontend: a wallet can be on any network, and a factory address means nothing on the wrong one. The SDK does not follow the wallet’s chainChanged events: listen for them yourself and connect again.

Signing (permits, gasless requests) also checks the clocks: deadlines are counted from the lower of the latest block’s time and this device’s clock, and a ClockSkewError refuses to sign when they differ by more than two minutes (except on local development chains, ids 31337 and 1337). Its message tells the user to set their clock to update automatically.

Checking Market Addresses

A market address that reaches your code from a link, a query string or a subgraph row is untrusted. Every builder checks its pair with the factory (factory.isPair) before building anything for it, and requirePair makes the same check for your own code:

// An address from a link or a query string is untrusted: ask the factory before using it.
const fromLink = new URLSearchParams(location.search).get("market") as Address;
const pair = await requirePair(bz.ctx, fromLink); // checksummed, or an InputError on "pair"

requirePair(ctx, address) resolves to the checksummed address, or rejects with an InputError on pair (“… is not a market of this Bazaar deployment, so nothing will be built or signed for it.”). A confirmation is cached per connection; a refusal is not, so a market listed later is accepted. markets.getMarket resolves only the factory’s own markets, so a market found through it needs no further check.

What Can Go Wrong

try {
  await Bazaar.connect({ transport: window.ethereum, factory: FACTORY, chainId: 42161 });
} catch (e) {
  if (e instanceof ConnectError) {
    // "connected to chain 421614, expected 42161", or
    // "0x... does not answer as a Bazaar factory on chain 42161"
    console.error(e.message);
  } else {
    console.error(errorMessage(e)); // the wallet or the RPC failed
  }
}

errorMessage(e) shows these as “Something went wrong. Please try again.” (they are not the user’s doing); log e.message for the detail.

Related Pages

• Core Concepts
• Markets, Accounts & Portfolios
• Live Prices, Live Updates
• Sending Transactions
• Security Notes for Integrators

Markets

This page covers reading markets: discovering them and their labels, a market’s whole live state at one block (its snapshot), the status and flags a UI gates its buttons on, funding for display, and the order book aggregated into price levels.

The samples assume bz connected as in Connecting, with a price source.

Listing Markets

const list = await bz.markets.listMarkets(); // cached per connection after the first call
for (const m of list) {
  console.log(m.label, m.address, m.hours, m.composite ? `composite of ${m.legSymbols.join(" and ")}` : m.legSymbols[0]);
}
const fresh = await bz.markets.listMarkets({ refresh: true }); // only markets listed since are described

const eth = await bz.markets.getMarket("eth/usd"); // a label (any case), a pair address, or a pair id
const byAddress = await bz.markets.getMarket(eth.address);

bz.markets.listMarkets(options?) returns every market the factory has deployed, in the factory’s order (factory.getAllPairs), each with the facts that never change about it. The first call reads the pair list, describes each pair (its pair id, feeds and trading calendar: two batched reads), takes the listing descriptions from the subgraph when the connection has one, and fetches the feeds’ Pyth symbols for the labels. The list is then cached on the connection: later calls make no request.

Each entry is a MarketInfo:

Labels are never taken from descriptions, which anyone listing a market writes and which could name another market.

Finding One Market

bz.markets.getMarket(ref) takes a market’s label (any case), its pair address, its pair id, or a MarketInfo (returned as is). A name the cached list does not know makes one refresh of the pair list, so a market listed since the page loaded is found. It throws an InputError on market for a name that matches nothing (“There is no market called “XYZ/USD”. Markets: BTC/USD, ETH/USD.“) or several markets (”… matches several markets (…); choose one by its address.“). Every function that takes a market accepts any of these forms.

Market Snapshots

const snap = await bz.markets.marketSnapshot(eth); // one block, two batched reads
console.log(`${snap.market.label} at block ${snap.block}: ${snap.status}`);
console.log(`stored ${formatUnits18(snap.price.spot, 2)} (${snap.price.age} s old), mark ${formatUnits18(snap.markPrice, 2)}`);
console.log(`IMR ${snap.margin.imrBp} bp, max leverage ${snap.margin.maxLeverage?.toFixed(1) ?? "-"}x`);
console.log(`OI long ${formatUnits18(snap.openInterest.longNotional, 0)} / short ${formatUnits18(snap.openInterest.shortNotional, 0)} USD`);
console.log(`insurance ${formatUnits18(snap.insurance.fund, 0)} USD, ${formatUnits18(snap.insurance.freeCapital, 0)} free`);

// Many markets at one block, in the same two batched reads.
const all = await bz.markets.marketSnapshots(list);
const live = [...all.values()].filter((s) => s.status === Status.Live);

bz.markets.marketSnapshot(market, options?) reads a market’s live state at one block: the keeper’s own state read and the snapshot’s extra reads (mark price, funding rates, the stored price’s band, ADL clocks, termination figures, the vault’s ledger, the book’s heads), in two batched calls sent together. marketSnapshots(markets, options?) does the same for many markets at once, in the same two calls, and returns a Map from address to snapshot; a market whose core reads fail is left out of the map, where marketSnapshot throws instead.

A snapshot is a plain object: keep it in state and re-render from it. Its time-dependent fields can be re-derived without a read (see Status).

Snapshot Fields

price (StoredPrice):

margin (MarginView), all in basis points of notional:

How these rates are set is in Margin.

openInterest (OpenInterestView): long and short (sizes), longNotional and shortNotional (at the stored spot), and longInventory and shortInventory (liquidated positions the vault holds, by the side they came from).

insurance (InsuranceView):

See Insurance.

adl (AdlView):

termination (TerminationView):

See Termination & Settlement and Termination.

book (BookSummary): bidHead and askHead (the best orders’ ids, 0 for an empty side), and bidCount and askCount (orders resting on each side). For price levels, see The Book.

Status

snapshot.status is one value, judged at the snapshot’s block, in this order of precedence:

The Status constant names them (Status.Live, …). In every status but live, every new order is refused, not only market orders. markets.marketStatusAt(snapshot, time) gives the status at another time without a read (for a countdown to a cutoff), and markets.adlScoreThresholdAt(snapshot, time) the ADL threshold.

Flags

The flags say what the pair refuses right now, each with the reason a UI can show next to a disabled button:

function tradeButtons(s: markets.MarketSnapshot) {
  return {
    marketOrder: { enabled: !s.marketOrdersDisabled, why: s.reasons.marketOrdersDisabled },
    // A position holder is frozen in more cases than a flat account.
    withdraw: (hasPosition: boolean) => {
      const blocked = s.allWithdrawalsPaused || (hasPosition && s.positionWithdrawalsFrozen);
      return { enabled: !blocked, why: s.allWithdrawalsPaused ? s.reasons.allWithdrawalsPaused : s.reasons.positionWithdrawalsFrozen };
    },
    // null: nothing could judge the venue (no live prices, no Pyth Pro source); false on a 24/7 market.
    venueClosed: s.venueClosed,
  };
}

// Countdowns without a new read: the status and the ADL threshold at another time.
const in30s = markets.marketStatusAt(snap, snap.timestamp + 30);
const threshold = markets.adlScoreThresholdAt(snap, snap.timestamp + 30);

snapshot.reasons has one entry per flag, null where the flag is off. An account snapshot applies the flags to the account (withdrawalBlocked). markets.marketFlags(market, state, time, venueClosed) computes them from a state read yourself.

The pair’s rules behind each flag are in Bazaar’s Oracle (closed venues), ADL and Termination chapters.

Funding

const f = snap.funding;
const perHour = Number(f.currentRatePerHour) / 1e16; // percent per hour (1e18 = 100%)
const hoursPerYear = eth.hours === "24/7" ? 8_760 : 1_700; // a trading-hours market accrues only while open
const perYear = markets.annualizedFunding(f.currentRatePerHour, hoursPerYear) * 100; // percent a year
console.log(`${perHour.toFixed(4)}%/h (${perYear.toFixed(2)}% a year), ${f.currentRatePerHour > 0n ? "longs pay shorts" : "shorts pay longs"}`);
console.log(`cap ${formatUnits18(f.maxRatePerHour * 100n)}%/h; next stored price charges ${formatUnits18(f.accruingRatePerHour * 100n, 4)}%/h`);

snapshot.funding (FundingView):

markets.annualizedFunding(ratePerHour, hoursPerYear?) gives a yearly fraction for display (0.0876 is 8.76% a year). A trading-hours market accrues funding only while its venue is open, so pass the hours it actually trades in a year (about 1,700 for a US equity) rather than the default 8,760. See Funding.

The Book

const { bids, asks } = await bz.markets.getBook(eth, 10); // ten levels a side, at one block
for (const l of asks.levels.slice().reverse()) console.log(`  ask ${formatUnits18(l.price, 2)}  ${formatUnits18(l.size, 4)}  (${l.orders})`);
for (const l of bids.levels) console.log(`  bid ${formatUnits18(l.price, 2)}  ${formatUnits18(l.size, 4)}  (${l.orders})`);
if (!bids.complete) console.log("more bids below");

const deep = await bz.markets.getBookDepth(eth, "bids", 100, { pageSize: 200, maxOrders: 5_000 });

bz.markets.getBook(market, levels?, options?) returns { bids, asks }, both sides read at one block. getBookDepth(market, side, levels?, options?) reads one side, "bids" or "asks". Each walks the side from its best order with the lens’s getBookDepth until it has seen enough distinct prices, reads the orders’ sizes in one batch, drops what is no longer live (filled, canceled, or past its expiry block but not yet swept), and sums each price level. Every read is pinned to one block.

A BookDepth has market, side, block, levels (best first: bids from the highest price down, asks from the lowest up) and complete (every level the side has is there). Each DepthLevel has price, size (remaining, 18 decimals), notional (size × price), orders (resting orders at the level) and cumulative (size from the best level through this one).

To keep a book current, re-read it when watchMarket reports bookChanged.

What Can Go Wrong

Related Pages

• Accounts & Portfolios
• Live Prices, Live Updates
• Previews
• History, for candles and trades
• Units & Constants

Accounts & Portfolios

This page covers reading a trader’s state: on one market (accountSnapshot) and across every market where the account holds anything (portfolio). A snapshot has the position and its health at the live price, the live orders, what can be withdrawn now, claimable fees, the meta-transaction nonce, the terminal payout of a market that is winding down, and the wallet’s USDC balance and allowance.

The samples assume bz connected as in Connecting with a price source, user the trader’s address and eth a market from Markets.

One Market

const me = await bz.account.accountSnapshot(eth, user);
console.log(`valued at ${me.price ? formatUnits18(me.price.spot, 2) : "no price"} (${me.price?.source ?? "-"})`);
if (me.hasPosition && me.health) {
  const h = me.health;
  console.log(`${me.position.isLong ? "long" : "short"} ${formatUnits18(me.position.size)} from ${formatUnits18(me.position.entryPrice, 2)}`);
  console.log(`equity ${formatUnits18(h.equity, 2)}, PnL ${formatUnits18(h.unrealizedPnl, 2)} + funding ${formatUnits18(h.fundingPnl, 2)}`);
  console.log(`margin ratio ${h.marginRatio.toFixed(2)} (liquidatable below 1), leverage ${h.leverage?.toFixed(1) ?? "-"}x`);
}

bz.account.accountSnapshot(market, user, options?) reads the account in two batched calls: first the position, its live order ids, the pair’s stored price, the claimable fees and the wallet’s USDC balance; then everything that depends on those (the lens’s solvency and withdrawal figures at the account’s price, the order exposure, the nonce, the terminal entitlement, the allowance, and the orders themselves), sent together with the market’s state read.

The position is valued at the first price available, in this order:

1. options.price, a price you already hold ({ spot, low?, high?, publishTime? });
2. the live price from options.prices, a LivePrices stream;
3. one Pyth Pro request for the market’s feeds, when the connection’s price source is a proPriceSource (and fetchPrices is not false);
4. the pair’s stored price.

snapshot.price.source says which: "given", "live", "pro" or "stored".

Snapshot Fields

position (AccountPosition), 18 decimals: