Predict SDK for TypeScript

https://github.com/predictdotfun/sdk
Admin
A TypeScript SDK designed to help developers interface with the Predict's protocol, enabling...
Tokens:63,317
Snippets:339
Trust Score:7.5
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Create and sign a LIMIT order with OrderBuilder

Source: https://github.com/predictdotfun/sdk/blob/main/README.md

Use this TypeScript example to create and sign a LIMIT strategy buy order. It requires a wallet private key and the @predictdotfun/sdk package. The OrderBuilder is instantiated once per signer, and the example shows setting approvals, calculating order amounts, building the order, generating typed data, signing, and computing the order hash. Note that feeRateBps should be fetched from the GET /markets endpoint, and isNegRisk and isYieldBearing can be fetched via the API.

```TypeScript
import { Wallet } from "ethers";
import { OrderBuilder, ChainId, Side } from "@predictdotfun/sdk";

// Create a wallet for signing orders
const signer = new Wallet(process.env.WALLET_PRIVATE_KEY);

// The main function which initiates the OrderBuilder (only once per signer) and then provides it as dependency to other util functions
async function main() {
  // Create a new instance of the OrderBuilder class. Note: This should only be done once per signer
  const orderBuilder = await OrderBuilder.make(ChainId.BnbMainnet, signer);

  // Call an helper function to create the order and provide the OrderBuilder instance
  await createOrder(orderBuilder);
}

async function createOrder(orderBuilder: OrderBuilder) {
  /**
   * NOTE: You can also call `setApprovals` once per wallet.
   */

  // Set all the approval needed within the protocol (if needed)
  const result = await orderBuilder.setApprovals();

  // Check if the approvals were set successfully
  if (!result.success) {
    throw new Error("Failed to set approvals.");
  }

  // Simple helper function to calculate the amounts for a `LIMIT` order
  const { lastPrice, pricePerShare, makerAmount, takerAmount } = orderBuilder.getLimitOrderAmounts({
    side: Side.BUY,
    pricePerShareWei: 400000000000000000n, // 0.4 USDT (in wei)
    quantityWei: 10000000000000000000n, // 10 shares (in wei)
  });

  // Build a limit order (if you are using a Predict account replace `signer.address` with your deposit address)
  const order = orderBuilder.buildOrder("LIMIT", {
    maker: signer.address,
    signer: signer.address,
    side: Side.BUY, // Equivalent to 0
    tokenId: "OUTCOME_ON_CHAIN_ID", // This can be fetched via the API or on-chain
    makerAmount, // 0.4 USDT * 10 shares (in wei)
    takerAmount, // 10 shares (in wei)
    nonce: 0n,
    feeRateBps: 0, // Should be fetched via the `GET /markets` endpoint
  });

  // Build typed data for the order (isNegRisk and isYieldBearing can be fetched via the API)
  const typedData = orderBuilder.buildTypedData(order, { isNegRisk: true, isYieldBearing: true });

  // Sign the order by providing the typedData of the order
  const signedOrder = await orderBuilder.signTypedDataOrder(typedData);

  // Compute the order's hash
  const hash = orderBuilder.buildTypedDataHash(typedData);

  // Example structure required to create an order via Predict's API
  const createOrderBody = {
    data: {
      order: { ...signedOrder, hash },
      pricePerShare,
      strategy: "LIMIT",
    },
  };
}
```

--------------------------------

### Install Predict SDK with yarn

Source: https://github.com/predictdotfun/sdk/blob/main/README.md

Install the @predictdotfun/sdk package and ethers v6 using yarn. This is the first installation method shown.

```bash
yarn add @predictdotfun/sdk ethers
```

--------------------------------

### Install Predict SDK with npm

Source: https://github.com/predictdotfun/sdk/blob/main/README.md

Install the @predictdotfun/sdk package and ethers v6 using npm. This is the alternative installation method.

```bash
npm install @predictdotfun/sdk ethers
```

--------------------------------

### buildTypedDataHash usage example

Source: https://github.com/predictdotfun/sdk/blob/main/_autodocs/api-reference/order-builder.md

Example of calling buildTypedDataHash to get an order hash and logging it to the console.

```typescript
const hash = builder.buildTypedDataHash(typedData);
console.log("Order hash:", hash);
```

--------------------------------

### setApproval usage examples

Source: https://github.com/predictdotfun/sdk/blob/main/_autodocs/api-reference/order-builder-approvals.md

Examples showing default approval, setting a specific ERC-20 allowance, and revoking approvals.

```typescript
// Approve with defaults
const res = await builder.setApproval(step);
if (!res.success) console.error("Approval failed:", res.cause);

// Non-trivial: cap the ERC-20 allowance / revoke
await builder.setApproval(splitStep, { amount: 500n * 10n ** 18n });
await builder.setApproval(tradeStep, { approved: false }); // revoke both kinds
```

--------------------------------

### checkApproval usage example

Source: https://github.com/predictdotfun/sdk/blob/main/_autodocs/api-reference/order-builder-approvals.md

Example of checking a single step and triggering an approval if not already satisfied.

```typescript
const alreadyApproved = await builder.checkApproval(tradeSteps[0]!);
if (!alreadyApproved) await builder.setApproval(tradeSteps[0]!);
```

--------------------------------

### Typical UI flow and onboarding with runApprovals

Source: https://github.com/predictdotfun/sdk/blob/main/_autodocs/api-reference/order-builder-approvals.md

Shows a typical UI flow: get approval steps for a trade, run them with progress callbacks, and handle failures. Also shows onboarding with all approval steps at once.

```typescript
// Typical UI flow
const steps = builder.getApprovalSteps({ operation: "TRADE", isNegRisk: true, isYieldBearing: false });
const report = await builder.runApprovals(steps, {
  skipSatisfied: true,
  stopOnError: true,
  onProgress: ({ step, status, transaction }) => {
    setStepStatus(step.id, status);
    if (transaction?.success) console.log("confirmed", transaction.receipt?.hash);
  },
});
if (!report.success) {
  const failed = report.steps.filter((s) => s.status === "failed").map((s) => s.step.id);
  throw new Error(`Approvals failed: ${failed.join(", ")}`);
}

// Onboarding: everything at once
const onboard = await builder.runApprovals(builder.getAllApprovalSteps(), {
  onProgress: (p) => renderChecklist(p),
});
```

--------------------------------

### buildOrder usage example with LIMIT and MARKET strategies

Source: https://github.com/predictdotfun/sdk/blob/main/_autodocs/api-reference/order-builder.md

Example showing how to build a LIMIT order, a MARKET order with ignored custom expiry, and error handling for an invalid expiration. The MARKET order forces expiration to now + 300 seconds. The error handling catches InvalidExpirationError and logs its message.

```typescript
const order = builder.buildOrder("LIMIT", {
  side: Side.BUY,
  tokenId: "0x…",
  makerAmount, takerAmount,   // from getLimitOrderAmounts
  nonce: 0n,
  feeRateBps: 0,              // from GET /markets
});

// MARKET strategy with custom expiry is ignored:
const marketOrder = builder.buildOrder("MARKET", { ...same, expiresAt: new Date(Date.now() + 60_000) });
console.log(marketOrder.expiration); // now + 300s

// Error handling
try {
  builder.buildOrder("LIMIT", { side: Side.SELL, tokenId: "1", makerAmount: "1", takerAmount: "1", feeRateBps: 0, expiresAt: new Date(Date.now() - 1000) });
} catch (error) {
  if (error instanceof InvalidExpirationError) console.error(error.message); // "Invalid expiration. Must be in the future."
}
```

--------------------------------

### Check USDT balance with OrderBuilder.balanceOf

Source: https://github.com/predictdotfun/sdk/blob/main/README.md

Use this snippet to check the USDT balance of the connected signer. It initializes the OrderBuilder once per signer and calls balanceOf() to get the balance in wei, then compares it to a threshold. The example assumes a WALLET_PRIVATE_KEY environment variable and uses the BNB Mainnet chain.

```typescript
import { Wallet } from "ethers";
import { OrderBuilder, ChainId } from "@predictdotfun/sdk";

// Initialize the wallet with your private key
const signer = new Wallet(process.env.WALLET_PRIVATE_KEY);

// The main function initiates the OrderBuilder (only once per signer)
// Then provides it as dependency to other functions
async function main() {
  // Create a new instance of the OrderBuilder class. Note: This should only be done once per signer
  const orderBuilder = await OrderBuilder.make(ChainId.BnbMainnet, signer);

  await checkBalance(orderBuilder);
}

async function checkBalance(orderBuilder: OrderBuilder) {
  // Fetch the current account/wallet balance in wei
  const balanceWei = await orderBuilder.balanceOf();

  // Example check
  if (balanceWei >= orderAmountWei) {
    console.log("Enough balance to create the order");
  } else {
    console.error("Not enough balance to create the order");
  }
}
```

--------------------------------

### Set Approvals with OrderBuilder

Source: https://github.com/predictdotfun/sdk/blob/main/README.md

Use this TypeScript example to set all necessary approvals for trading on Predict. It creates a wallet from a private key, initializes the OrderBuilder once per signer, and calls setApprovals to approve the required contracts. The example checks the result and throws an error if approvals fail.

```typescript
import { Wallet, MaxInt256 } from "ethers";
import { OrderBuilder, ChainId, Side } from "@predictdotfun/sdk";

// Create a wallet to send the approvals transactions (must be the orders' `maker`)
const signer = new Wallet(process.env.WALLET_PRIVATE_KEY);

// The main function which initiates the OrderBuilder (only once per signer) and then provides it as dependency to other util functions
async function main() {
  // Create a new instance of the OrderBuilder class. Note: This should only be done once per signer
  const orderBuilder = await OrderBuilder.make(ChainId.BnbMainnet, signer);

  // Call an helper function to set the approvals and provide the OrderBuilder instance.
  await setApprovals(orderBuilder);
}

async function setApprovals(orderBuilder: OrderBuilder) {
  // Set all the approval needed within the protocol
  const result = await orderBuilder.setApprovals();

  // Check if the approvals were set successfully
  if (!result.success) {
    throw new Error("Failed to set approvals.");
  }
}
```

--------------------------------

### checkApprovals usage example

Source: https://github.com/predictdotfun/sdk/blob/main/_autodocs/api-reference/order-builder-approvals.md

Example of iterating through approval checks to update UI row status.

```typescript
const checks = await builder.checkApprovals(tradeSteps);
for (const { step, satisfied } of checks) {
  setRowStatus(step.id, satisfied ? "done" : "pending");
}
```

--------------------------------

### getMarketOrderAmounts usage example

Source: https://github.com/predictdotfun/sdk/blob/main/_autodocs/api-reference/order-builder.md

Example of calling getMarketOrderAmounts for a SELL order with an orderbook, a BUY value-based order with min-amount-out slippage, and error handling for InvalidQuantityError.

```typescript
// Basic SELL with orderbook
const book = { marketId: 1, updateTimestampMs: Date.now(), asks: [], bids: [[0.4, 10], [0.35, 5]] };
const { makerAmount, takerAmount, pricePerShare, slippageBps } = builder.getMarketOrderAmounts(
  { side: Side.SELL, quantityWei: 10000000000000000000n },
  book,
);

// Non-trivial: BUY, value-based, min-amount-out slippage
const valueAmounts = builder.getMarketOrderAmounts(
  { side: Side.BUY, valueWei: 5000000000000000000n, slippageBps: 50n, isMinAmountOut: true },
  book,
);
console.log(valueAmounts.amount, valueAmounts.takerAmount, valueAmounts.slippageBps); // 50n bps applied

// Error handling
try {
  builder.getMarketOrderAmounts({ side: Side.BUY, quantityWei: 10n ** 10n }, book);
} catch (error) {
  if (error instanceof InvalidQuantityError) console.error(error.message);
}
```

--------------------------------

### setNegRiskAdapterApproval usage example

Source: https://github.com/predictdotfun/sdk/blob/main/_autodocs/api-reference/order-builder-approvals.md

Example of calling setNegRiskAdapterApproval and handling the result.

```typescript
const res = await builder.setNegRiskAdapterApproval(false);
if (!res.success) throw new Error("Adapter approval failed");
```

--------------------------------

### getAllApprovalSteps usage

Source: https://github.com/predictdotfun/sdk/blob/main/_autodocs/api-reference/order-builder-approvals.md

Examples of retrieving all approval steps, either for all tracks or filtered by yield-bearing status.

```typescript
const all = builder.getAllApprovalSteps();               // everything
const standardTrack = builder.getAllApprovalSteps({ isYieldBearing: false }); // one track
```

--------------------------------

### convertPositions usage example

Source: https://github.com/predictdotfun/sdk/blob/main/_autodocs/api-reference/order-builder-positions.md

Example converting NO positions for questions 0 and 2, using a bitmask index set. The amount is set to 10^18 wei, and the negRiskOnChainId is a 32-byte hex from GET /categories.

```typescript
// Convert NO positions of questions 0 and 2
const indexSet = [0, 2].reduce((set, i) => set | (1n << BigInt(i)), 0n);
const result = await builder.convertPositions({
  negRiskOnChainId: "0x…", // 32-byte hex from GET /categories
  indexSet,
  amount: 10n ** 18n,
  isYieldBearing: true,
});
if (!result.success) console.error("Convert failed:", result.cause);
```

--------------------------------

### Redeem positions with OrderBuilder

Source: https://github.com/predictdotfun/sdk/blob/main/README.md

Use this TypeScript example to redeem positions on the Predict protocol. It initializes a wallet and OrderBuilder, then calls redeemPositions for standard and NegRisk markets. The conditionId and indexSet are fetched from the GET /positions endpoint.

```typescript
import { Wallet } from "ethers";
import { OrderBuilder, ChainId } from "@predictdotfun/sdk";

// Initialize the wallet with your private key
const signer = new Wallet(process.env.WALLET_PRIVATE_KEY);

// The main function initiates the OrderBuilder (only once per signer)
// Then provides it as dependency to other functions
async function main() {
  // Create a new instance of the OrderBuilder class. Note: This should only be done once per signer
  const orderBuilder = await OrderBuilder.make(ChainId.BnbMainnet, signer);

  // Redeem positions for a standard market
  await redeemStandardPositions(orderBuilder);

  // Redeem positions for a NegRisk market
  await redeemNegRiskPositions(orderBuilder);
}

async function redeemStandardPositions(orderBuilder: OrderBuilder) {
  const conditionId = "CONDITION_ID_FROM_API"; // A hash string
  const indexSet = "INDEX_SET_FROM_API"; // 1 or 2 based on the position you want to redeem

  const result = await orderBuilder.redeemPositions({
    conditionId,
    indexSet,
    isNegRisk: false,
    isYieldBearing: true, // Set based on market type
  });

  if (result.success) {
    console.log("Positions redeemed successfully:", result.receipt);
  } else {
    console.error("Failed to redeem positions:", result.cause);
  }
}

async function redeemNegRiskPositions(orderBuilder: OrderBuilder) {
  const conditionId = "CONDITION_ID_FROM_API"; // A hash string
  const indexSet = "INDEX_SET_FROM_API"; // 1 or 2 based on the position you want to redeem
  const amount = "POSITION_AMOUNT_FROM_API"; // The amount to redeem, usually the max

  const result = await orderBuilder.redeemPositions({
    conditionId,
    indexSet,
    amount,
    isNegRisk: true,
    isYieldBearing: true, // Set based on market type
  });

  if (result.success) {
    console.log("Positions redeemed successfully:", result.receipt);
  } else {
    console.error("Failed to redeem positions:", result.cause);
  }
}
```

--------------------------------

### getApprovalSteps usage and error handling

Source: https://github.com/predictdotfun/sdk/blob/main/_autodocs/api-reference/order-builder-approvals.md

Examples of retrieving approval steps for different operations and handling the InvalidApprovalOperationError.

```typescript
// Signer-less builder is fine for planning
const plan = await OrderBuilder.make(ChainId.BnbMainnet);
const tradeSteps = plan.getApprovalSteps({ operation: "TRADE", isNegRisk: true, isYieldBearing: false });
const buyOnly = plan.getApprovalSteps({ operation: "TRADE", isNegRisk: false, isYieldBearing: true, side: Side.BUY });

// Error case
try {
  plan.getApprovalSteps({ operation: "CONVERT", isNegRisk: false, isYieldBearing: false });
} catch (error) {
  if (error instanceof InvalidApprovalOperationError) console.error(error.message);
}
```

--------------------------------

### setCtfExchangeAllowance usage example

Source: https://github.com/predictdotfun/sdk/blob/main/_autodocs/api-reference/order-builder-approvals.md

Example of setting a standard exchange USDT allowance with a specific cap.

```typescript
// Standard exchange USDT allowance, with a lower cap
const res = await builder.setCtfExchangeAllowance(false, false, 1000n * 10n ** 18n, 1000n * 10n ** 18n);
if (!res.success) console.error(res.cause);
```

--------------------------------

### getLimitOrderAmounts usage example

Source: https://github.com/predictdotfun/sdk/blob/main/_autodocs/api-reference/order-builder.md

Example of calling getLimitOrderAmounts with a BUY limit order, and handling an InvalidQuantityError when quantityWei is below the minimum. The error message is 'Invalid quantityWei. Must be greater than 1e16.'

```typescript
const { lastPrice, pricePerShare, makerAmount, takerAmount } = builder.getLimitOrderAmounts({
  side: Side.BUY,
  pricePerShareWei: 400000000000000000n, // 0.4 USDT
  quantityWei: 10000000000000000000n,    // 10 shares
});

try {
  builder.getLimitOrderAmounts({ side: Side.BUY, pricePerShareWei: 1n, quantityWei: 10n ** 14n });
} catch (error) {
  if (error instanceof InvalidQuantityError) console.error(error.message); // "Invalid quantityWei. Must be greater than 1e16."
}
```

--------------------------------

### Run approvals with progress reporting using runApprovals

Source: https://github.com/predictdotfun/sdk/blob/main/README.md

Builds an OrderBuilder, gets approval steps for a TRADE operation, and runs them with progress reporting. Options include skipSatisfied (default true), stopOnError (default true), and onProgress callback. The returned report contains success and steps with statuses.

```typescript
const builder = await OrderBuilder.make(ChainId.BnbMainnet, signer);
const steps = builder.getApprovalSteps({ operation: "TRADE", isNegRisk: true, isYieldBearing: false });

const report = await builder.runApprovals(steps, {
  skipSatisfied: true, // default
  stopOnError: true, // default
  onProgress: ({ step, status }) => updateUI(step.id, status),
});
```

--------------------------------

### ApprovalStep shape example

Source: https://github.com/predictdotfun/sdk/blob/main/README.md

Shows the plain data structure of an ApprovalStep with stable id, type, spender, token, label, and description. The label and description are English defaults that can be replaced with custom copy keyed off the stable id.

```typescript
{
  id: "ERC1155_APPROVAL:CTF_EXCHANGE", // stable identifier: `${type}:${spenderKey}`
  type: "ERC1155_APPROVAL",            // or "ERC20_ALLOWANCE"
  spender: "0x8BC0...B689",            // the contract being granted permission
  token: "0x22DA...d244",              // the token contract (conditional tokens for ERC-1155, USDT for ERC-20)
  label: "Approve Exchange",           // default copy
  description: "Allows you to interact with the exchange.",
}
```

--------------------------------

### signPredictAccountMessage usage example

Source: https://github.com/predictdotfun/sdk/blob/main/_autodocs/api-reference/order-builder.md

Example of signing a plain string and a raw digest using signPredictAccountMessage. Direct use is shown; usual callers are signTypedDataOrder.

```typescript
// Usual callers: signTypedDataOrder. Direct use:
const sig = await builder.signPredictAccountMessage("hello");
const sigRaw = await builder.signPredictAccountMessage({ raw: ethers.keccak256("0x1234") });
```

--------------------------------

### cancelOrders usage examples

Source: https://github.com/predictdotfun/sdk/blob/main/_autodocs/api-reference/order-builder-positions.md

Examples for cancelOrders: basic call, grouping orders by (isNegRisk, isYieldBearing) combinations, error handling for wrong isNegRisk grouping, and skipping validation with withValidation: false. The grouping example shows all four combos and uses Promise.all.

```typescript
// Basic
const result = await builder.cancelOrders(ordersToCancel, { isNegRisk: true, isYieldBearing: false });
if (!result.success) console.error(result.cause);

// Grouping per market type (all four combos)
const groups = { "00": [], "10": [], "01": [], "11": [] as Order[] };
for (const { order, isNegRisk, isYieldBearing } of apiOrders) {
  groups[`${+isNegRisk}${+isYieldBearing}`].push(order);
}
const results = await Promise.all([
  builder.cancelOrders(groups["00"], { isNegRisk: false, isYieldBearing: false }),
  builder.cancelOrders(groups["10"], { isNegRisk: true, isYieldBearing: false }),
  builder.cancelOrders(groups["01"], { isNegRisk: false, isYieldBearing: true }),
  builder.cancelOrders(groups["11"], { isNegRisk: true, isYieldBearing: true }),
]);

// Error handling: wrong isNegRisk grouping
try {
  await builder.cancelOrders(mixedOrders, { isNegRisk: false, isYieldBearing: false });
} catch (error) {
  if (error instanceof InvalidNegRiskConfig) {
    console.error(error.message); // guidance: re-group by isNegRisk
  }
}
// Skip validation when you have verified the token IDs yourself:
await builder.cancelOrders(verifiedOrders, { isNegRisk: true, isYieldBearing: false, withValidation: false });
```

--------------------------------

### Market order with 1% slippage and value-based order with 0.5% slippage

Source: https://github.com/predictdotfun/sdk/blob/main/README.md

Two examples of using `orderBuilder.getMarketOrderAmounts` to calculate market order amounts with slippage. The first uses `quantityWei` for a 10-share order with 100 bps (1%) slippage, and the second uses `valueWei` for a 5 USDT order with 50 bps (0.5%) slippage. Both set `isMinAmountOut: true` to deflate the `takerAmount`. The code logs the resulting amounts and slippage. Slippage is only applied when `slippageBps` and `isMinAmountOut` are provided when submitting the order to the REST API.

```typescript
// Market order with 1% slippage (100 bps)
const amounts = orderBuilder.getMarketOrderAmounts(
  {
    side: Side.BUY,
    quantityWei: 10000000000000000000n, // 10 shares (in wei)
    slippageBps: 100n, // 1% slippage tolerance
    isMinAmountOut: true,
  },
  book,
);

// makerAmount is the expected cost, takerAmount is deflated by slippage
console.log(`Maker Amount: ${amounts.makerAmount}`); // Expected cost (not inflated)
console.log(`Taker Amount: ${amounts.takerAmount}`); // Deflated by slippage
console.log(`Amount: ${amounts.amount}`); // Original share quantity
console.log(`Price Per Share: ${amounts.pricePerShare}`);
console.log(`Slippage Applied: ${amounts.slippageBps} bps`); // 100n

// Value-based market order with slippage
const valueAmounts = orderBuilder.getMarketOrderAmounts(
  {
    side: Side.BUY,
    valueWei: 5000000000000000000n, // 5 USDT (in wei)
    slippageBps: 50n, // 0.5% slippage tolerance
    isMinAmountOut: true,
  },
  book,
);
```

--------------------------------

### Interact with contracts using OrderBuilder.contracts

Source: https://github.com/predictdotfun/sdk/blob/main/README.md

Use this snippet to call functions on Predict's smart contracts. It requires the signer to be provided during OrderBuilder.make; otherwise, the contracts are not initialized and an error is thrown. The example shows how to access the USDT contract instance and call balanceOf, and also mentions the codec property for encoding/decoding data.

```typescript
import { OrderBuilder, ChainId } from "@predictdotfun/sdk";
import { Wallet } from "ethers";

// Create a wallet to interact with on-chain contracts
const signer = new Wallet(process.env.WALLET_PRIVATE_KEY);

// The main function initiates the OrderBuilder (only once per signer)
// Then provides it as dependency to other functions
async function main() {
  // Create a new instance of the OrderBuilder class. Note: This should only be done once per signer
  const orderBuilder = await OrderBuilder.make(ChainId.BnbMainnet, signer);

  await callContracts(orderBuilder);
}

async function callContracts(orderBuilder: OrderBuilder) {
  // If the signer is not provided within `OrderBuilder.make` the contracts won't be initiated
  if (!orderBuilder.contracts) {
    throw new Error("The signer was not provided during the OrderBuilder init.");
  }

  // You can now call contract functions (the actual contract instance is within `contract`)
  // The `codec` property contains the ethers Interface, useful to encode and decode data
  const balance = await orderBuilder.contracts["USDT"].contract.balanceOf(signer.address);
}
```

--------------------------------

### Cancel orders with OrderBuilder

Source: https://github.com/predictdotfun/sdk/blob/main/README.md

Use this TypeScript example to cancel orders via the PredictDotFun SDK. It creates a wallet and provider, initializes the OrderBuilder once per signer, fetches open orders, groups them by `isNegRisk` and `isYieldBearing`, and calls `cancelOrders` for each group. The example checks the success of all cancellation transactions.

```typescript
import { Wallet } from "ethers";
import { OrderBuilder, ChainId, Side } from "@predictdotfun/sdk";

// Create a new JsonRpcProvider instance
const provider = new JsonRpcProvider(process.env.RPC_PROVIDER_URL);

// Create a wallet to send the cancel transactions on-chain
const signer = new Wallet(process.env.WALLET_PRIVATE_KEY).connect(provider);

// The main function which initiates the OrderBuilder (only once per signer) and then provides it as dependency to other util functions
async function main() {
  // Create a new instance of the OrderBuilder class. Note: This should only be done once per signer
  const orderBuilder = await OrderBuilder.make(ChainId.BnbMainnet, signer);

  // Call a helper function to cancel orders and provide the OrderBuilder instance
  await cancelOrdersHelper(orderBuilder);
}

async function cancelOrdersHelper(orderBuilder: OrderBuilder) {
  // Fetch your open orders from the `GET /orders` endpoint
  const apiResponse = [
    // There are more fields, but for cancellations we only care about `order`, `isNegRisk` and `isYieldBearing`
    { order: {}, isNegRisk: true, isYieldBearing: true },
    { order: {}, isNegRisk: true, isYieldBearing: false },
    { order: {}, isNegRisk: false, isYieldBearing: true },
    { order: {}, isNegRisk: false, isYieldBearing: false },
  ];

  // Determine which orders you want to cancel
  const ordersToCancel = [
    { order: {}, isNegRisk: true, isYieldBearing: true },
    { order: {}, isNegRisk: true, isYieldBearing: false },
    { order: {}, isNegRisk: false, isYieldBearing: true },
    { order: {}, isNegRisk: false, isYieldBearing: false },
  ];

  const regularOrders: Order[] = [];
  const negRiskOrders: Order[] = [];
  const regularYieldBearingOrders: Order[] = [];
  const negRiskYieldBearingOrders: Order[] = [];

  // Group the orders by `isNegRisk` and `isYieldBearing`
  for (const { order, isNegRisk, isYieldBearing } of ordersToCancel) {
    if (isYieldBearing) {
      if (isNegRisk) {
        negRiskYieldBearingOrders.push(order);
      } else {
        regularYieldBearingOrders.push(order);
      }
    } else {
      if (isNegRisk) {
        negRiskOrders.push(order);
      } else {
        regularOrders.push(order);
      }
    }
  }

  // Call the cancel function
  const regResult = await orderBuilder.cancelOrders(regularOrders, { isNegRisk: false, isYieldBearing: false });
  const negRiskResult = await orderBuilder.cancelOrders(negRiskOrders, { isNegRisk: true, isYieldBearing: false });

  const regYieldBearingResult = await orderBuilder.cancelOrders(regularYieldBearingOrders, {
    isNegRisk: false,
    isYieldBearing: true,
  });
  const negRiskYieldBearingResult = await orderBuilder.cancelOrders(negRiskYieldBearingOrders, {
    isNegRisk: true,
    isYieldBearing: true,
  });

  // Check for the transactions success
  const success =
    regResult.success && negRiskResult.success && regYieldBearingResult.success && negRiskYieldBearingResult.success;
}
```

--------------------------------

### Configure provider polling interval for faster confirmations

Source: https://github.com/predictdotfun/sdk/blob/main/README.md

Set the provider's pollingInterval to 300ms to speed up transaction confirmations. The default is 4000ms, which can cause delays. This example creates a JsonRpcProvider and Wallet using environment variables.

```typescript
import { JsonRpcProvider, Wallet } from "ethers";

const provider = new JsonRpcProvider(process.env.RPC_PROVIDER_URL);
provider.pollingInterval = 300; // default is 4000ms

const signer = new Wallet(process.env.WALLET_PRIVATE_KEY, provider);
```

--------------------------------

### Using balanceOf to check USDT balance

Source: https://github.com/predictdotfun/sdk/blob/main/_autodocs/api-reference/order-builder.md

Example usage of `balanceOf`. The first call uses the default token and address, the second overrides the address. The result is in wei and can be compared to an order amount.

```typescript
const balanceWei = await builder.balanceOf();
if (balanceWei < orderAmountWei) console.warn("Insufficient USDT");

// With a predict account, defaults to the account address; explicit override:
const other = await builder.balanceOf("USDT", someAddress);
```

--------------------------------

### splitPositions usage example

Source: https://github.com/predictdotfun/sdk/blob/main/_autodocs/api-reference/order-builder-positions.md

Calls splitPositions with a conditionId, 10^18 wei amount, and non-NegRisk, non-yield-bearing options. Checks result.success and logs an error with result.cause?.message if it fails.

```typescript
const result = await builder.splitPositions({ conditionId, amount: 10n ** 18n, isNegRisk: false, isYieldBearing: false });
if (!result.success) console.error("Split failed:", result.cause?.message);
```

--------------------------------

### Drive approval steps manually with checkApprovals and setApproval

Source: https://github.com/predictdotfun/sdk/blob/main/README.md

Builds an OrderBuilder, gets approval steps for a SPLIT operation, checks which are satisfied via batched multicall, and sets each unsatisfied approval individually. setApproval is a raw send with ERC-20 defaulting to MaxUint256 and ERC-1155 to approved: true; pass { approved: false } to revoke or { amount } to cap.

```typescript
const builder = await OrderBuilder.make(ChainId.BnbMainnet, signer);
const steps = builder.getApprovalSteps({ operation: "SPLIT", isNegRisk: false, isYieldBearing: false });

// Batched pre-check to mark which steps are already done.
const checks = await builder.checkApprovals(steps);

for (const { step, satisfied } of checks) {
  if (satisfied) continue; // already approved
  // setApproval is a raw send: ERC-20 defaults to MaxUint256, ERC-1155 to `approved: true`.
  // Pass `{ approved: false }` to revoke, or `{ amount }` to cap an allowance.
  const result = await builder.setApproval(step);
  if (!result.success) break; // you decide whether to continue
}
```

--------------------------------

### Merge positions with OrderBuilder

Source: https://github.com/predictdotfun/sdk/blob/main/README.md

Use this snippet to merge equal amounts of YES and NO outcome tokens back into USDT. The `conditionId` is obtained from the `GET /positions` endpoint. The `isYieldBearing` flag should be set based on the market type. The `OrderBuilder.make` should only be called once per signer.

```typescript
import { Wallet } from "ethers";
import { OrderBuilder, ChainId } from "@predictdotfun/sdk";

// Initialize the wallet with your private key
const signer = new Wallet(process.env.WALLET_PRIVATE_KEY);

async function main() {
  // Create a new instance of the OrderBuilder class. Note: This should only be done once per signer
  const orderBuilder = await OrderBuilder.make(ChainId.BnbMainnet, signer);

  await mergePositions(orderBuilder);
}

async function mergePositions(orderBuilder: OrderBuilder) {
  const conditionId = "CONDITION_ID_FROM_API";
  const amount = 10000000000000000000n; // 10 tokens (in wei)

  const result = await orderBuilder.mergePositions({
    conditionId,
    amount,
    isNegRisk: false,
    isYieldBearing: true, // Set based on market type
  });

  if (result.success) {
    console.log("Positions merged successfully:", result.receipt);
  } else {
    console.error("Failed to merge positions:", result.cause);
  }
}
```

--------------------------------

### Convert NO positions to YES and collateral with OrderBuilder.convertPositions

Source: https://github.com/predictdotfun/sdk/blob/main/README.md

Initializes a wallet and OrderBuilder, then converts selected NO positions in a NegRisk market. Requires the NegRisk adapter to be approved as an operator with the CONVERT operation. The negRiskOnChainId is a 32-byte hex string from the GET /categories endpoint, and indexSet is a bitmask built from questionIndex values.

```TypeScript
import { Wallet } from "ethers";
import { OrderBuilder, ChainId } from "@predictdotfun/sdk";

// Initialize the wallet with your private key
const signer = new Wallet(process.env.WALLET_PRIVATE_KEY);

async function main() {
  // Create a new instance of the OrderBuilder class. Note: This should only be done once per signer
  const orderBuilder = await OrderBuilder.make(ChainId.BnbMainnet, signer);

  await convertPositions(orderBuilder);
}

async function convertPositions(orderBuilder: OrderBuilder) {
  const negRiskOnChainId = "NEG_RISK_ON_CHAIN_ID_FROM_API"; // 32-byte hex, not the numeric API id

  // Set the bit at each market's `questionIndex` to select its NO position
  const questionIndexes = [0, 2]; // e.g. convert the NO positions of the first and third questions
  const indexSet = questionIndexes.reduce((set, index) => set | (1n << BigInt(index)), 0n);

  const result = await orderBuilder.convertPositions({
    negRiskOnChainId,
    indexSet,
    amount: 10000000000000000000n, // 10 tokens (in wei) of each NO position
    isYieldBearing: true, // Set based on market type
  });

  if (result.success) {
    console.log("Positions converted successfully:", result.receipt);
  } else {
    console.error("Failed to convert positions:", result.cause);
  }
}
```

--------------------------------

### async setApproval(step, opts?)

Source: https://github.com/predictdotfun/sdk/blob/main/_autodocs/api-reference/order-builder-approvals.md

Raw send to set an approval. No pre-check is performed; use `runApprovals` for combined check and send.

```APIDOC
## `async setApproval(step, opts?)`

### Description
Raw send — **no** pre-check (`runApprovals` combines check + send).

### Method
`setApproval`

### Parameters
- **step** (`ApprovalStep`) - Required - Step to execute (from `getApprovalSteps`).
- **opts.approved** (`boolean`) - Optional - Default `true`. ERC-1155: `false` revokes. ERC-20: `false` sets allowance to `0` (revoke).
- **opts.amount** (`bigint`) - Optional - Default `MaxUint256`. ERC-20: allowance value granted.

### Returns
`Promise<TransactionResult>`.

### Throws
`MissingSignerError`; `Error("Unknown approval address: …")` for a step built from a non-protocol address.

### Example
```typescript
// Approve with defaults
const res = await builder.setApproval(step);
if (!res.success) console.error("Approval failed:", res.cause);

// Non-trivial: cap the ERC-20 allowance / revoke
await builder.setApproval(splitStep, { amount: 500n * 10n ** 18n });
await builder.setApproval(tradeStep, { approved: false }); // revoke both kinds
```
```

--------------------------------

### Render live approval checklist with progress updates

Source: https://github.com/predictdotfun/sdk/blob/main/README.md

Builds an approval plan, checks which steps are satisfied via batched multicall, renders a checklist, and runs remaining steps with live progress updates. Uses getApprovalSteps, checkApprovals, and runApprovals.

```typescript
const builder = await OrderBuilder.make(ChainId.BnbMainnet, signer);

// 1. Build the plan.
const steps = builder.getApprovalSteps({ operation: "TRADE", isNegRisk, isYieldBearing });

// 2. Render the checklist, marking which are already satisfied (one batched multicall read).
for (const { step, satisfied } of await builder.checkApprovals(steps)) {
  addRow(step.id, step.label, step.description, satisfied ? "done" : "pending");
}

// 3. Run the remaining steps, updating each row as it progresses.
const report = await builder.runApprovals(steps, {
  onProgress: ({ step, status }) => setRowStatus(step.id, status),
});
```

--------------------------------

### Build approval steps with OrderBuilder

Source: https://github.com/predictdotfun/sdk/blob/main/README.md

Shows how to create an OrderBuilder with a signer and build approval steps for a single operation or all operations. getApprovalSteps and getAllApprovalSteps are pure and can be called without a signer, but a signer is needed for checkApprovals, setApproval, and runApprovals.

```typescript
import { OrderBuilder, ChainId, Side } from "@predictdotfun/sdk";

const builder = await OrderBuilder.make(ChainId.BnbMainnet, signer);

// For a single operation on a market:
const steps = builder.getApprovalSteps({
  operation: "TRADE",
  isNegRisk: true,
  isYieldBearing: false,
  // side: Side.BUY, // optional TRADE narrowing
});

// For onboarding, every approval across both market types (and, by default, both tracks):
const allSteps = builder.getAllApprovalSteps(); // or { isYieldBearing: false } to limit to one track
```

--------------------------------

### getAllApprovalSteps(opts?)

Source: https://github.com/predictdotfun/sdk/blob/main/_autodocs/api-reference/order-builder-approvals.md

Documentation for the getAllApprovalSteps method on the OrderBuilder class.

```APIDOC
## getAllApprovalSteps(opts?)

### Description
Returns every approval step the protocol could need across market types, deduplicated by `id`. Pure method — no signer or network access required.

### Method
Function call

### Signature
`getAllApprovalSteps(opts?: { isYieldBearing?: boolean }): ApprovalStep[]`

### Parameters
- **opts.isYieldBearing** (`boolean`) - Optional - Default: both tracks - `true`/`false` limits to one track; omitted includes standard and yield-bearing.

### Returns
- `ApprovalStep[]` - Superset of `TRADE`, `SPLIT`, `MERGE`, `REDEEM` (+ `CONVERT` for neg-risk) across market types, deduplicated by `id`.

### Example
```typescript
const all = builder.getAllApprovalSteps();               // everything
const standardTrack = builder.getAllApprovalSteps({ isYieldBearing: false }); // one track
```
```

--------------------------------

### Import SDK utilities, ABIs, and types

Source: https://github.com/predictdotfun/sdk/blob/main/README.md

This snippet shows the available exports from the SDK, including chain IDs, addresses, contract interfaces, ABIs, and the OrderBuilder. Use it to import the necessary components for interacting with the SDK's contracts and utilities.

```typescript
import {
  // Supported Chains
  ChainId,

  // Addresses
  AddressesByChainId,

  // Contract Interfaces
  CTFExchange,
  ConditionalTokens,
  YieldBearingConditionalTokens,
  NegRiskAdapter,
  NegRiskCtfExchange,
  ERC20,

  // ABIs
  CTFExchangeAbi,
  NegRiskCtfExchangeAbi,
  NegRiskAdapterAbi,
  ConditionalTokensAbi,
  YieldBearingConditionalTokensAbi,
  ERC20Abi,

  // Order builder
  OrderBuilder,
} from "@predictdotfun/sdk";
```

--------------------------------

### Create and sign an order with Predict account using OrderBuilder

Source: https://github.com/predictdotfun/sdk/blob/main/README.md

Initializes the OrderBuilder with a Predict account, builds a LIMIT order, and signs it. Requires a Privy wallet private key and the predictAccount address. The maker and signer are automatically set to the predictAccount.

```typescript
import { Wallet } from "ethers";
import { OrderBuilder, ChainId, Side } from "@predictdotfun/sdk";

// Create a wallet to send the approvals transactions (must be the orders' `maker`)
const signer = new Wallet(process.env.PRIVY_WALLET_PRIVATE_KEY);

// The main function which initiates the OrderBuilder (only once per signer) and then provides it as dependency to other util functions
async function main() {
  // Create a new instance of the OrderBuilder class with the predictAccount option
  // Note: This should only be done once per signer
  const orderBuilder = await OrderBuilder.make(ChainId.BnbMainnet, signer, {
    predictAccount: "PREDICT_ACCOUNT_ADDRESS", // Your deposit address from account settings
  });

  // Call an helper function to create the order and provide the OrderBuilder instance
  await createOrder(orderBuilder);
}

async function createOrder(orderBuilder: OrderBuilder) {
  // Step 1. Set approvals and define the order params as usual

  // Step 2. Create the order (maker and signer are automatically set to the predictAccount)
  const order = orderBuilder.buildOrder("LIMIT", {
    side: Side.BUY, // Equivalent to 0
    tokenId: "OUTCOME_ON_CHAIN_ID", // This can be fetched via the API or on-chain
    makerAmount, // 0.4 USDT * 10 shares (in wei)
    takerAmount, // 10 shares (in wei)
    nonce: 0n,
    feeRateBps: 0, // Should be fetched via the `GET /markets` endpoint
  });

  // Step 3. Sign and submit the order as usual
}
}
```

--------------------------------

### validateTokenIds usage example

Source: https://github.com/predictdotfun/sdk/blob/main/_autodocs/api-reference/order-builder-positions.md

Example call to validateTokenIds with a single token ID, neg-risk true, and yield-bearing false. Logs a warning if the token is not registered on the neg-risk exchange.

```typescript
const valid = await builder.validateTokenIds([order.tokenId], true, false);
if (!valid) console.warn("Token not registered on the neg-risk exchange");
```
Tokens:
Raw