Predict SDK for Python

https://github.com/predictdotfun/sdk-python
Admin
A Python SDK designed to help developers interface with the Predict.fun protocol, enabling...
Tokens:61,910
Snippets:372
Trust Score:7.5
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example: get_all_approval_steps usage

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

Shows how to get all approval steps for both tracks or only for non-yield-bearing markets.

```python
all_steps = builder.get_all_approval_steps()            # both tracks
onboarding = builder.get_all_approval_steps(is_yield_bearing=False)
```

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

### Reading the current level example

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

Example of creating a Logger with INFO level, logging an info message, asserting the level, and changing it to DEBUG.

```python
logger = Logger(level="INFO")
logger.info("builder ready")
assert logger.level == "INFO"
logger.set_level("DEBUG")

```

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

### Example: market BUY by quantity with slippage

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

Shows how to call get_market_order_amounts with a MarketHelperInput for a BUY order by quantity, including slippage_bps and is_min_amount_out=True. The orderbook is obtained from GET /orderbook/{marketId}. The comment indicates to forward is_min_amount_out, amount, and slippageBps in the REST request body.

```python
from predict_sdk import MarketHelperInput, Side, Book

amounts = builder.get_market_order_amounts(
    MarketHelperInput(side=Side.BUY, quantity_wei=10_000_000_000_000_000_000,
                      slippage_bps=100, is_min_amount_out=True),
    orderbook,  # Book from GET /orderbook/{marketId}
)
# Forward is_min_amount_out, amount, slippageBps in the REST request body
```

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

### Install predict-sdk with pip

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

Install the Predict SDK for Python using pip.

```bash
pip install predict-sdk
```

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

### Standalone use example

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

Example of creating a Logger with DEBUG level, logging messages, and setting level to ERROR to suppress output.

```python
from predict_sdk.logger import Logger

log = Logger("DEBUG")
log.debug("price truncated to %d significant digits", 3)
log.warn("expiresAt for market orders is ignored.")
log.set_level("ERROR")  # suppress info/debug output

```

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

### Example: sign a built order

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

Shows how to build typed data and sign it, printing the 0x-prefixed signature.

```python
builder = OrderBuilder.make(ChainId.BNB_MAINNET, private_key)
typed_data = builder.build_typed_data(order, is_neg_risk=False, is_yield_bearing=False)
signed = builder.sign_typed_data_order(typed_data)
print(signed.signature)  # 0x-prefixed hex
```

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

### balance_of usage example

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

Example usage of balance_of and balance_of_async. The sync call returns the balance in wei; the async call accepts an optional address parameter.

```python
balance = builder.balance_of("USDT")
print(balance)  # wei
await builder.balance_of_async("USDT", address="0x...holder")
```

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

### Example: market BUY by value

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

Shows how to call get_market_order_amounts with a MarketHelperValueInput for a BUY order by value, specifying value_wei. The orderbook is passed as the second argument.

```python
from predict_sdk import MarketHelperValueInput

amounts = builder.get_market_order_amounts(
    MarketHelperValueInput(side=Side.BUY, value_wei=5_000_000_000_000_000_000),
    orderbook,
)
```

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

### Example: get_approval_steps for a neg-risk trade

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

Shows how to retrieve approval steps for a trade on a neg-risk market with side=Side.BUY, then print each step's id, label, and spender.

```python
from predict_sdk import ApprovalScope, Side

steps = builder.get_approval_steps(
    ApprovalScope(operation="TRADE", is_neg_risk=True, is_yield_bearing=False,
                  side=Side.BUY)  # optional narrowing
)
for s in steps:
    print(s.id, s.label, s.spender)
```

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

### Run approvals with live progress and async example

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

Shows how to run approvals with a progress callback that updates the UI, and how to use the async variant with duplicate IDs removed automatically.

```python
steps = builder.get_approval_steps(
    ApprovalScope(operation="TRADE", is_neg_risk=True, is_yield_bearing=False)
)
report = builder.run_approvals(
    steps,
    on_progress=lambda p: update_ui(p.step.id, p.status),
)
if not report.success:
    failed = [s.step.id for s in report.steps if s.status == "failed"]
    raise RuntimeError(f"Approvals failed: {failed}")

# Async inside an event loop:
report = await builder.run_approvals_async(
    [*trade_steps, *split_steps],  # duplicate ids removed automatically
    stop_on_error=False,
)
```

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

### Example: build order from computed amounts

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

Shows how to call build_order with a LIMIT strategy, using a BuildOrderInput with side, token_id, maker_amount, taker_amount, fee_rate_bps, and expires_at. The expires_at must be in the future for LIMIT orders.

```python
from datetime import datetime, timezone
from predict_sdk import BuildOrderInput, Side

order = builder.build_order(
    "LIMIT",
    BuildOrderInput(
        side=Side.BUY,
        token_id="YOUR_TOKEN_ID",
        maker_amount=str(amounts.maker_amount),
        taker_amount=str(amounts.taker_amount),
        fee_rate_bps=100,  # fetch via GET /markets
        expires_at=datetime(2030, 1, 1, tzinfo=timezone.utc),
    ),
)

```

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

### Basic get_limit_order_amounts example

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

Basic usage of get_limit_order_amounts with a BUY order on BNB mainnet. Shows required imports and how to construct LimitHelperInput with side, price_per_share_wei, and quantity_wei.

```python
from predict_sdk import OrderBuilder, ChainId, Side, LimitHelperInput, OrderAmounts

builder = OrderBuilder.make(ChainId.BNB_MAINNET)
amounts: OrderAmounts = builder.get_limit_order_amounts(
    LimitHelperInput(
        side=Side.BUY,
        price_per_share_wei=500_000_000_000_000_000,  # 0.5 USDT/share
        quantity_wei=10_000_000_000_000_000_000,      # 10 shares
    )
)
print(amounts.maker_amount, amounts.taker_amount)
```

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

### Example: approving a single step

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

Shows how to iterate over check results and set approval for unsatisfied steps, printing a revert cause if the transaction fails.

```python
for check in builder.check_approvals(steps):
    if check.satisfied:
        continue
    result = builder.set_approval(check.step)          # MAX_UINT256 / approved=True
    if not result.success:
        print("reverted:", result.cause)
        break
```

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

### redeem_positions usage example

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

Example of calling redeem_positions for standard and NegRisk markets. For NegRisk, amount is required. The result's success and cause are checked.

```python
result = builder.redeem_positions("0x...", index_set=1,
                                  is_neg_risk=False, is_yield_bearing=False)
# NegRisk requires amount:
result = builder.redeem_positions("0x...", index_set=1,
                                  amount=1_000_000_000_000_000_000,
                                  is_neg_risk=True, is_yield_bearing=False)
if not result.success:
    print("redeem failed:", result.cause)
```

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

### Example of MissingSignerError

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

Shows the error raised when no signer or predict_account is configured. The example uses OrderBuilder.make with a private key and catches MissingSignerError.

```python
try:
    OrderBuilder.make(ChainId.BNB_MAINNET, private_key).sign_predict_account_message("hi")
except MissingSignerError:
    print("predict_account must be configured in OrderBuilderOptions")
```

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

### set_ctf_exchange_approval and set_ctf_exchange_allowance usage example

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

Shows how to call set_ctf_exchange_approval and set_ctf_exchange_allowance with various parameters, including revoking approval and setting a custom allowance.

```python
builder.set_ctf_exchange_approval(is_neg_risk=False, is_yield_bearing=False)  # approve
builder.set_ctf_exchange_approval(is_neg_risk=True, is_yield_bearing=False, approved=False)  # revoke
builder.set_ctf_exchange_allowance(is_neg_risk=False, is_yield_bearing=False)  # MAX_UINT256
result = await builder.set_ctf_exchange_allowance_async(
    is_neg_risk=True, is_yield_bearing=True, amount=10**24)
```

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

### set_approvals usage example

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

Shows how to call set_approvals for both tracks and for the yield-bearing track only, and how to check the result for failures.

```python
result = builder.set_approvals()                      # both tracks
if not result.success:
    for tx in result.transactions:
        if not tx.success:
            print("Failed:", tx.cause)
result = builder.set_approvals(is_yield_bearing=True)  # yield-bearing track only
```

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

### Example: errors, sync vs async inside an event loop

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

Demonstrates handling MissingSignerError when no signer is provided, and using the async variant inside an async context.

```python
from predict_sdk import MissingSignerError, FailedOrderSignError

read_only = OrderBuilder.make(ChainId.BNB_MAINNET)          # no signer
try:
    read_only.sign_typed_data_order(typed_data)
except MissingSignerError:
    print("provide a signer to OrderBuilder.make")

# Inside an async context use the _async variant:
signed = await builder.sign_typed_data_order_async(typed_data)
```

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

### cancel_orders usage example

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

Example of calling cancel_orders with two orders and CancelOrdersOptions. Checks the result's success flag and prints the cause on failure.

```python
from predict_sdk import CancelOrdersOptions

result = builder.cancel_orders(
    orders=[order1, order2],
    options=CancelOrdersOptions(is_neg_risk=False, is_yield_bearing=False),
)
if not result.success:
    print("cancel failed:", result.cause)
```

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

### Example: convert NO positions of questions 0 and 2

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

Builds an index_set bitmask for questions 0 and 2, then calls builder.convert_positions with a 32-byte hex neg_risk_on_chain_id and an amount of 1e18. Requires the adapter to be approved as an operator (use ApprovalScope(operation="CONVERT", ...)).

```python
index_set = 0
for question_index in [0, 2]:
    index_set |= 1 << question_index

result = builder.convert_positions(
    neg_risk_on_chain_id="0x...",   # 32-byte hex from GET /categories
    index_set=index_set,
    amount=1_000_000_000_000_000_000,
    is_yield_bearing=False,
)
```

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

### Example usage with string and raw hash

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

Demonstrates signing a plain string message and a raw hash, plus the async variant. The raw hash is signed directly, while the string is EIP-191-prefixed.

```python
sig = builder.sign_predict_account_message("Hello, world!")
sig2 = builder.sign_predict_account_message({"raw": "0x1234..."})

# Async variant
sig3 = await builder.sign_predict_account_message_async("Hello, world!")
```

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

### validate_token_ids usage example

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

Example of calling validate_token_ids with two token IDs and flags. Prints a message if any token ID is not registered.

```python
ok = builder.validate_token_ids([12345, 67890], is_neg_risk=False, is_yield_bearing=False)
if not ok:
    print("one or more token ids are not registered in this exchange")
```

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

### Build a LIMIT order without a signer

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

Create an OrderBuilder without a signer, calculate limit order amounts, and build an order. The fee_rate_bps value should be obtained from the GET /markets endpoint.

```python
from predict_sdk import (
    OrderBuilder,
    ChainId,
    Side,
    BuildOrderInput,
    LimitHelperInput,
)

# Create an OrderBuilder without a signer (read-only)
builder = OrderBuilder.make(ChainId.BNB_MAINNET)

# Calculate order amounts for a LIMIT order
amounts = builder.get_limit_order_amounts(
    LimitHelperInput(
        side=Side.BUY,
        price_per_share_wei=500000000000000000,  # 0.5 USDT per share
        quantity_wei=10000000000000000000,  # 10 shares
    )
)

print(f"Maker Amount: {amounts.maker_amount}")
print(f"Taker Amount: {amounts.taker_amount}")

# Build an order
order = builder.build_order(
    "LIMIT",
    BuildOrderInput(
        side=Side.BUY,
        token_id="YOUR_TOKEN_ID",
        maker_amount=str(amounts.maker_amount),
        taker_amount=str(amounts.taker_amount),
        fee_rate_bps=100,  # Get from GET /markets endpoint
    ),
)
```

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

### Wrapping a hash with eip712_wrap_hash

Source: https://github.com/predictdotfun/sdk-python/blob/main/_autodocs/api-reference/internal-utilities.md

Example of wrapping a hash for a Kernel account using `eip712_wrap_hash`. This is what `sign_predict_account_message` does internally. The domain is built from `KERNEL_DOMAIN_BY_CHAIN_ID` for the BNB mainnet chain and includes a `verifyingContract` field.

```python
from predict_sdk._internal.utils import eip712_wrap_hash
from predict_sdk.constants import KERNEL_DOMAIN_BY_CHAIN_ID, ChainId

digest = eip712_wrap_hash(
    "0x1234...",
    {**KERNEL_DOMAIN_BY_CHAIN_ID[ChainId.BNB_MAINNET], "verifyingContract": predict_account},
)
```

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

### Example: expiration error handling

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

Demonstrates catching InvalidExpirationError when expires_at is in the past for a LIMIT order. The example uses a past date (2020) and prints a message when the error is raised.

```python
from predict_sdk import InvalidExpirationError

try:
    builder.build_order("LIMIT", BuildOrderInput(
        side=Side.BUY, token_id="1", maker_amount="1", taker_amount="1",
        fee_rate_bps=100, expires_at=datetime(2020, 1, 1, tzinfo=timezone.utc)))
except InvalidExpirationError:
    print("expiration must be in the future")

```

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

### Error handling for get_limit_order_amounts

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

Error handling example for get_limit_order_amounts. Attempts a SELL order with quantity below 1e16, which triggers InvalidQuantityError. Shows how to catch and print the error message.

```python
from predict_sdk import InvalidQuantityError

try:
    builder.get_limit_order_amounts(
        LimitHelperInput(side=Side.SELL, price_per_share_wei=400_000_000_000_000_000,
                         quantity_wei=500_000_000_000_000)  # below 1e16
    )
except InvalidQuantityError as e:
    print("Quantity too small:", e)
```

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

### Read-only OrderBuilder.make() example

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

Creates a read-only OrderBuilder without a signer. The builder's contracts attribute is None, meaning it cannot access the chain or perform signing/on-chain operations.

```python
from predict_sdk import OrderBuilder, ChainId

builder = OrderBuilder.make(ChainId.BNB_MAINNET)
assert builder.contracts is None  # read-only

```

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

### Market Order Amounts by Quantity and Value

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

Calculates market order amounts using either a quantity (number of shares) or a value (total USDT to spend). The orderbook is obtained from GET /orderbook/{marketId}. Prints the resulting maker/taker amounts, price per share, slippage, and whether the amount is the minimum out.

```python
from predict_sdk import MarketHelperInput, MarketHelperValueInput

# Market order by quantity (number of shares)
amounts = builder.get_market_order_amounts(
    MarketHelperInput(
        side=Side.BUY,
        quantity_wei=10000000000000000000,  # 10 shares
    ),
    orderbook,  # From GET /orderbook/{marketId}
)

# Market BUY by value (total USDT to spend)
amounts = builder.get_market_order_amounts(
    MarketHelperValueInput(
        side=Side.BUY,
        value_wei=5000000000000000000,  # 5 USDT
    ),
    orderbook,
)

print(f"Maker Amount: {amounts.maker_amount}")
print(f"Taker Amount: {amounts.taker_amount}")
print(f"Amount: {amounts.amount}")
print(f"Price Per Share: {amounts.price_per_share}")
print(f"Slippage Applied: {amounts.slippage_bps} bps")
print(f"Is Min Amount Out: {amounts.is_min_amount_out}")
```

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

### Render a live approval checklist

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

Implements the typical UI flow for an in-app 'Approvals' modal: build the plan, render a checklist marking already-satisfied steps, then run the remaining steps with live progress updates. For first-time onboarding, swap `get_approval_steps(scope)` for `get_all_approval_steps()` to approve everything the protocol could need in one pass.

```python
builder = OrderBuilder.make(ChainId.BNB_MAINNET, private_key)

# 1. Build the plan.
steps = builder.get_approval_steps(
    ApprovalScope(operation="TRADE", is_neg_risk=is_neg_risk, is_yield_bearing=is_yield_bearing)
)

# 2. Render the checklist, marking which are already satisfied.
for check in builder.check_approvals(steps):
    add_row(check.step.id, check.step.label, check.step.description,
            "done" if check.satisfied else "pending")

# 3. Run the remaining steps, updating each row as it progresses.
report = builder.run_approvals(
    steps,
    on_progress=lambda p: set_row_status(p.step.id, p.status),
)
```

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

### Build approval steps with get_approval_steps and get_all_approval_steps

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

Builds approval steps from a signer-backed OrderBuilder. get_approval_steps returns the minimal ordered set for one operation; get_all_approval_steps returns everything. Both are pure (no signer or network access), so they can be called on a signer-less builder to render a checklist before the wallet is connected.

```python
from predict_sdk import OrderBuilder, ChainId, Side, ApprovalScope

builder = OrderBuilder.make(ChainId.BNB_MAINNET, private_key)

# For a single operation on a market:
steps = builder.get_approval_steps(
    ApprovalScope(
        operation="TRADE",
        is_neg_risk=True,
        is_yield_bearing=False,
        # side=Side.BUY,  # optional TRADE narrowing
    )
)

# For onboarding, every approval across both market types (and, by default, both tracks):
all_steps = builder.get_all_approval_steps()  # or is_yield_bearing=False to limit to one track
```

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

### split_positions usage example

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

Example call to split_positions with a condition ID, an amount of 5e18 wei, and is_neg_risk=False, is_yield_bearing=False. The result is assigned to a variable named result.

```python
result = builder.split_positions("0x...", amount=5_000_000_000_000_000_000,
                                 is_neg_risk=False, is_yield_bearing=False)
```

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

### merge_positions usage example

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

Example call to merge_positions with a condition ID, an amount of 1e18 wei, and is_neg_risk=True, is_yield_bearing=False. The result is assigned to a variable named result.

```python
result = builder.merge_positions("0x...", amount=1_000_000_000_000_000_000,
                                 is_neg_risk=True, is_yield_bearing=False)
```

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

### level property

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

Property to get the current log level.

```python
@property
def level(self) -> LogLevel:
    """Get the current log level."""

```

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

### Configure OrderBuilder with options

Source: https://github.com/predictdotfun/sdk-python/blob/main/_autodocs/configuration.md

Use this snippet to initialize an OrderBuilder for the BNB Mainnet chain. It requires a signer (private key string or LocalAccount) and an OrderBuilderOptions object. The options include precision, predict account, a custom salt generator, and log level. The generate_salt lambda uses random.randint to produce a salt within a specified range.

```python
from predict_sdk import OrderBuilder, ChainId, OrderBuilderOptions

builder = OrderBuilder.make(
    ChainId.BNB_MAINNET,
    signer="0x-your-privy-exported-private-key",  # str or LocalAccount
    options=OrderBuilderOptions(
        precision=18,
        predict_account="0x...YourPredictAccount",
        generate_salt=lambda: str(random.randint(0, 2_147_483_648)),
        log_level="DEBUG",
    ),
)
```

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

### Sign an order with a private key

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

Create an OrderBuilder with a signer using a private key, build typed data, and sign the order. The private key is provided as a placeholder.

```python
from eth_account import Account
from predict_sdk import OrderBuilder, ChainId

# Create from private key
private_key = "0x..."  # Your private key
signer = Account.from_key(private_key)

# Or pass private key directly
builder = OrderBuilder.make(ChainId.BNB_MAINNET, private_key)

# Now you can sign orders and interact with contracts
typed_data = builder.build_typed_data(
    order,
    is_neg_risk=False,
    is_yield_bearing=False,
)

signed_order = builder.sign_typed_data_order(typed_data)
print(f"Signature: {signed_order.signature}")
```

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

### Using float_to_wei and retain_significant_digits

Source: https://github.com/predictdotfun/sdk-python/blob/main/_autodocs/api-reference/internal-utilities.md

Example usage of `float_to_wei` and `retain_significant_digits`. `float_to_wei(0.421031, 10**18)` returns 421031000000000000, and `retain_significant_digits(123456789, 3)` returns 123000000.

```python
from predict_sdk._internal.utils import float_to_wei, retain_significant_digits

wei = float_to_wei(0.421031, 10**18)          # 421031000000000000 (exact decimal)
truncated = retain_significant_digits(123456789, 3)  # 123000000
```

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

### Calculate market order amounts

Source: https://github.com/predictdotfun/sdk-python/blob/main/_autodocs/types.md

Initializes a Book object with market data and uses the builder to calculate market order amounts for a buy side order.

```python
from predict_sdk import Book, MarketHelperInput, Side

book = Book(
    market_id=1,
    update_timestamp_ms=0,
    asks=[(0.51, 5000.0), (0.52, 8000.0)],  # (price, quantity)
    bids=[(0.49, 9000.0)],
)
amounts = builder.get_market_order_amounts(
    MarketHelperInput(side=Side.BUY, quantity_wei=10_000_000_000_000_000_000), book
)
print(amounts.price_per_share, amounts.maker_amount, amounts.taker_amount)
```

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

### OrderBuilder.__init__

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

Constructor for the OrderBuilder class. It initializes the builder with chain configuration, precision, addresses, salt generator, logger, and optional signer, predict account, contracts, and web3 instance. Do not call directly; use the make() factory.

```APIDOC
## OrderBuilder.__init__

### Description
Constructor for the OrderBuilder class. It initializes the builder with chain configuration, precision, addresses, salt generator, logger, and optional signer, predict account, contracts, and web3 instance. Do not call directly; use the make() factory.

### Method
Constructor

### Signature
```python
def __init__(
    self,
    chain_id: ChainId,
    precision: int,
    addresses: Addresses,
    generate_salt_fn: Callable[[], str],
    logger: Logger,
    signer: LocalAccount | None = None,
    predict_account: str | None = None,
    contracts: Contracts | None = None,
    web3: Web3 | None = None,
) -> None:
```

### Parameters
- **chain_id** (ChainId) - Required - Chain to operate on
- **precision** (int) - Required - Decimal precision; stored as `10**precision` (see `OrderBuilderOptions.precision`)
- **addresses** (Addresses) - Required - Per-chain contract addresses
- **generate_salt_fn** (Callable[[], str]) - Required - Salt generator for orders
- **logger** (Logger) - Required - SDK logger
- **signer** (LocalAccount | None) - Optional - EOA account used for signing/sending
- **predict_account** (str | None) - Optional - Predict (Kernel) smart-account address
- **contracts** (Contracts | None) - Optional - Pre-built contract container (`predict_sdk._internal.contracts.Contracts`)
- **web3** (Web3 | None) - Optional - Web3 instance

### Notes
- The constructor stores dependencies and sets `self._execution_mode = bytes.fromhex(ZERO_HASH[2:])` (the `bytes32` execMode passed to `Kernel.execute`).
- Do not call directly — use the `make()` factory.
```

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

### run_approvals(steps, *, skip_satisfied=True, stop_on_error=True, on_progress=None) -> ApprovalRunReport

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

Synchronously executes a list of approval steps on-chain. Steps are deduplicated by id (first occurrence wins). If skip_satisfied is True, each step is pre-checked on-chain and skipped if already in place; pre-check read failures are non-fatal. If stop_on_error is True, execution stops after the first failed step. The on_progress callback is invoked on each transition with an ApprovalProgress object.

```APIDOC
## run_approvals(steps, *, skip_satisfied=True, stop_on_error=True, on_progress=None) -> ApprovalRunReport

### Description
Synchronously executes a list of approval steps on-chain. Steps are deduplicated by `id` (first occurrence wins). If `skip_satisfied` is `True`, each step is pre-checked on-chain and skipped if already in place; pre-check read failures are non-fatal. If `stop_on_error` is `True`, execution stops after the first failed step. The `on_progress` callback is invoked on each transition with an `ApprovalProgress` object.

### Method
Synchronous method call

### Endpoint
`OrderBuilder.run_approvals`

### Parameters
- `steps` (list[ApprovalStep]) - Required - List of approval steps to execute. Deduplicated by `id` (first occurrence wins).
- `skip_satisfied` (bool) - Optional, default `True` - Pre-check each step on-chain; skip if already in place. Pre-check read failures are non-fatal (falls through to send).
- `stop_on_error` (bool) - Optional, default `True` - Stop after the first failed step.
- `on_progress` (Callable[[ApprovalProgress], None] | None) - Optional, default `None` - Called on each transition with `ApprovalProgress(step, status, transaction)`.

### Returns
`ApprovalRunReport(success: bool, steps: list[ApprovalStepResult])` where each `ApprovalStepResult.status` is `"skipped"`, `"confirmed"`, or `"failed"`.

### Progress Statuses
`ApprovalStatus`: `"checking"` (reading on-chain, only with `skip_satisfied`) → `"skipped"` | `"submitting"` → `"confirmed"` | `"failed"`.

### Example
python
steps = builder.get_approval_steps(
    ApprovalScope(operation="TRADE", is_neg_risk=True, is_yield_bearing=False)
)
report = builder.run_approvals(
    steps,
    on_progress=lambda p: update_ui(p.step.id, p.status),
)
if not report.success:
    failed = [s.step.id for s in report.steps if s.status == "failed"]
    raise RuntimeError(f"Approvals failed: {failed}")


### Example - pessimistic run, continuing past failures
python
report = builder.run_approvals(steps, skip_satisfied=False, stop_on_error=False)
for r in report.steps:
    print(r.step.id, r.status, r.transaction.cause if r.transaction and not r.transaction.success else "")

```

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

### Book orderbook data structure

Source: https://github.com/predictdotfun/sdk-python/blob/main/_autodocs/types.md

Represents the orderbook payload returned by GET /orderbook/{marketId}, containing market ID, timestamp, and depth levels for asks and bids.

```python
DepthLevel = tuple[float, float]  # (price, quantity)

@dataclass
class Book:
    """Orderbook data."""

    market_id: int
    update_timestamp_ms: int
    asks: list[DepthLevel]
    bids: list[DepthLevel]
```

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

### make_contracts function signature

Source: https://github.com/predictdotfun/sdk-python/blob/main/_autodocs/api-reference/internal-utilities.md

Instantiates all 13 contracts with the ABI mapping. Sets web3.eth.default_account to signer.address when a signer is provided.

```python
def make_contracts(
    web3: Web3,
    addresses: Addresses,
    signer: LocalAccount | None = None,
) -> Contracts:
```

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

### async run_approvals_async(steps, *, skip_satisfied=True, stop_on_error=True, on_progress=None) -> ApprovalRunReport

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

Asynchronously executes a list of approval steps on-chain. Behaves like run_approvals but is designed for use inside an event loop. Steps are deduplicated by id (first occurrence wins). If skip_satisfied is True, each step is pre-checked on-chain and skipped if already in place; pre-check read failures are non-fatal. If stop_on_error is True, execution stops after the first failed step. The on_progress callback is invoked on each transition with an ApprovalProgress object.

```APIDOC
## async run_approvals_async(steps, *, skip_satisfied=True, stop_on_error=True, on_progress=None) -> ApprovalRunReport

### Description
Asynchronously executes a list of approval steps on-chain. Behaves like `run_approvals` but is designed for use inside an event loop. Steps are deduplicated by `id` (first occurrence wins). If `skip_satisfied` is `True`, each step is pre-checked on-chain and skipped if already in place; pre-check read failures are non-fatal. If `stop_on_error` is `True`, execution stops after the first failed step. The `on_progress` callback is invoked on each transition with an `ApprovalProgress` object.

### Method
Asynchronous method call

### Endpoint
`OrderBuilder.run_approvals_async`

### Parameters
- `steps` (list[ApprovalStep]) - Required - List of approval steps to execute. Deduplicated by `id` (first occurrence wins).
- `skip_satisfied` (bool) - Optional, default `True` - Pre-check each step on-chain; skip if already in place. Pre-check read failures are non-fatal (falls through to send).
- `stop_on_error` (bool) - Optional, default `True` - Stop after the first failed step.
- `on_progress` (Callable[[ApprovalProgress], None] | None) - Optional, default `None` - Called on each transition with `ApprovalProgress(step, status, transaction)`.

### Returns
`ApprovalRunReport(success: bool, steps: list[ApprovalStepResult])` where each `ApprovalStepResult.status` is `"skipped"`, `"confirmed"`, or `"failed"`.

### Progress Statuses
`ApprovalStatus`: `"checking"` (reading on-chain, only with `skip_satisfied`) → `"skipped"` | `"submitting"` → `"confirmed"` | `"failed"`.

### Example
python
# Async inside an event loop:
report = await builder.run_approvals_async(
    [*trade_steps, *split_steps],  # duplicate ids removed automatically
    stop_on_error=False,
)

```

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

### get_market_order_amounts method signature

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

The method signature for get_market_order_amounts. It takes a MarketHelperInput or MarketHelperValueInput and a Book object, returning OrderAmounts. The book comes from the external REST endpoint GET /orderbook/{marketId}.

```python
def get_market_order_amounts(
    self,
    data: MarketHelperInput | MarketHelperValueInput,
    book: Book,
) -> OrderAmounts:

```

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

### Create OrderBuilder with Predict Account

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

Initializes an OrderBuilder for the BNB mainnet using a private key that must be the Privy exported wallet, and specifies the Predict account address.

```python
from predict_sdk import OrderBuilder, ChainId, OrderBuilderOptions

builder = OrderBuilder.make(
    ChainId.BNB_MAINNET,
    private_key,  # Must be the Privy exported wallet
    OrderBuilderOptions(
        predict_account="0x...",  # Your Predict account address
    ),
)
```

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

### Async Support with balance_of_async and set_approvals_async

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

Demonstrates async versions of contract interaction methods. All contract interaction methods have async variants, such as balance_of_async and set_approvals_async. Use asyncio.run to execute the async main function.

```python
import asyncio

async def main():
    balance = await builder.balance_of_async("USDT")
    result = await builder.set_approvals_async()

asyncio.run(main())

```

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

### Create OrderBuilder with make Factory Method

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

Factory method for creating an OrderBuilder instance. Requires a ChainId and optionally a signer (LocalAccount or private key string) and OrderBuilderOptions. Returns an OrderBuilder.

```python
OrderBuilder.make(
    chain_id: ChainId,
    signer: LocalAccount | str | None = None,
    options: OrderBuilderOptions | None = None,
) -> OrderBuilder

```

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

### OrderBuilder.make() overload signatures

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

Shows the three overload signatures and the implementation signature of the make() classmethod. The first two are @overload declarations, and the third is the actual implementation. The implementation accepts chain_id, an optional signer (LocalAccount or str), and optional OrderBuilderOptions.

```python
@overload
@classmethod
def make(
    cls,
    chain_id: ChainId,
    signer: None = None,
    options: OrderBuilderOptions | None = None,
) -> OrderBuilder: ...

@overload
@classmethod
def make(
    cls,
    chain_id: ChainId,
    signer: LocalAccount | str,
    options: OrderBuilderOptions | None = None,
) -> OrderBuilder: ...

@classmethod
def make(
    cls,
    chain_id: ChainId,
    signer: LocalAccount | str | None = None,
    options: OrderBuilderOptions | None = None,
) -> OrderBuilder:

```

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

### Convert NO positions in NegRisk markets

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

Convert NO positions in a NegRisk market into complementary YES positions plus collateral. Only NegRisk markets support conversions. The neg_risk_on_chain_id is a 32-byte hex string from the GET /categories endpoint, not the numeric API id. The index_set is a bitmask selecting which NO positions to convert. Conversions require the NegRisk adapter to be approved as an operator first (see Scoped Approvals, CONVERT operation).

```python
# Set the bit at each market's questionIndex to select its NO position
question_indexes = [0, 2]  # e.g. convert the NO positions of the first and third questions
index_set = 0
for index in question_indexes:
    index_set |= 1 << index

result = builder.convert_positions(
    neg_risk_on_chain_id="0x...",  # 32-byte hex, not the numeric API id
    index_set=index_set,
    amount=1000000000000000000,  # Amount of each NO position to convert (in wei)
    is_yield_bearing=False,
)
```

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

### run_approvals_async and run_approvals signatures

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

Method signatures for the async and sync approval runners. Both accept a list of ApprovalStep and optional parameters for skipping satisfied steps, stopping on error, and progress callbacks.

```python
async def run_approvals_async(
    self,
    steps: list[ApprovalStep],
    *,
    skip_satisfied: bool = True,
    stop_on_error: bool = True,
    on_progress: Callable[[ApprovalProgress], None] | None = None,
) -> ApprovalRunReport:

def run_approvals(
    self,
    steps: list[ApprovalStep],
    *,
    skip_satisfied: bool = True,
    stop_on_error: bool = True,
    on_progress: Callable[[ApprovalProgress], None] | None = None,
) -> ApprovalRunReport:
```

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

### convert_positions_async and convert_positions signatures

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

Method signatures for the async and sync versions. Both take neg_risk_on_chain_id, index_set, amount, and is_yield_bearing, returning a TransactionResult. NegRisk-only: burns amount of each NO position in index_set and returns complementary YES positions plus USDT collateral proportional to (number of NO positions - 1). Fees (if any) are taken from both collateral and YES tokens.

```python
async def convert_positions_async(
    self,
    neg_risk_on_chain_id: str,
    index_set: int,
    amount: int,
    *,
    is_yield_bearing: bool,
) -> TransactionResult:

def convert_positions(
    self,
    neg_risk_on_chain_id: str,
    index_set: int,
    amount: int,
    *,
    is_yield_bearing: bool,
) -> TransactionResult:
```

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

### APPROVAL_STEP_COPY constant

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

Defines the APPROVAL_STEP_COPY mapping from role and type keys to label and description strings. Used by OrderBuilder._make_approval_step, which falls back to empty strings if a key is missing.

```python
APPROVAL_STEP_COPY: Final[dict[str, dict[str, str]]] = {
    "EXCHANGE:ERC1155_APPROVAL": {
        "label": "Approve Exchange",
        "description": "Allows you to interact with the exchange.",
    },
    "EXCHANGE:ERC20_ALLOWANCE": {
        "label": "Exchange Allowance",
        "description": "Grants the exchange permission to use your collateral to trade.",
    },
    "NEG_RISK_EXCHANGE:ERC1155_APPROVAL": {
        "label": "Approve Multi-Outcome",
        "description": "Allows you to interact with multi-outcome markets.",
    },
    "NEG_RISK_ADAPTER:ERC1155_APPROVAL": {
        "label": "Approve Multi-Outcome Adapter",
        "description": "Allows the multi-outcome adapter to manage your tokens.",
    },
    "NEG_RISK_EXCHANGE:ERC20_ALLOWANCE": {
        "label": "Multi-Outcome Allowance",
        "description": "Grants the multi-outcome exchange permission to use your collateral.",
    },
    "CONDITIONAL_TOKENS:ERC20_ALLOWANCE": {
        "label": "Split Allowance",
        "description": "Grants permission to use your collateral to split positions.",
    },
    "NEG_RISK_ADAPTER:ERC20_ALLOWANCE": {
        "label": "Multi-Outcome Split Allowance",
        "description": "Grants the adapter permission to use your collateral to split positions.",
    },
}
```

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

### redeem_positions_async and redeem_positions method signatures

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

Shows the async and sync method signatures for redeeming positions. Both accept condition_id, index_set, optional amount, and keyword-only is_neg_risk and is_yield_bearing flags.

```python
async def redeem_positions_async(
    self,
    condition_id: str,
    index_set: Literal[1, 2],
    amount: int | None = None,
    *,
    is_neg_risk: bool,
    is_yield_bearing: bool,
) -> TransactionResult:

def redeem_positions(
    self,
    condition_id: str,
    index_set: Literal[1, 2],
    amount: int | None = None,
    *,
    is_neg_risk: bool,
    is_yield_bearing: bool,
) -> TransactionResult:
```

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

### get_all_approval_steps signature

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

Signature for the pure method that returns all approval steps across both neg-risk values and operations, deduplicated by id.

```python
def get_all_approval_steps(
    self,
    *,
    is_yield_bearing: bool | None = None,
) -> list[ApprovalStep]:
```

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

### Usage: Import ABI constants and build a web3 contract

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

Shows how to import ABI constants from predict_sdk and use CTF_EXCHANGE_ABI to create a raw web3 contract for a custom call, such as calling validateTokenId.

```python
from predict_sdk import CTF_EXCHANGE_ABI, KERNEL_ABI

# Build a raw web3 contract for a custom call
contract = web3.eth.contract(address=addr, abi=CTF_EXCHANGE_ABI)
print(contract.functions.validateTokenId(token_id).call())
```

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

### validate_token_ids_async and validate_token_ids method signatures

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

Shows the async and sync method signatures for validating token IDs. Both take a list of integers and keyword-only flags for exchange selection.

```python
async def validate_token_ids_async(
    self,
    token_ids: list[int],
    *,
    is_neg_risk: bool,
    is_yield_bearing: bool,
) -> bool:

def validate_token_ids(
    self,
    token_ids: list[int],
    *,
    is_neg_risk: bool,
    is_yield_bearing: bool,
) -> bool:
```

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

### make_contract function signature

Source: https://github.com/predictdotfun/sdk-python/blob/main/_autodocs/api-reference/internal-utilities.md

Creates a contract instance using web3.eth.contract with a checksummed address and the provided ABI.

```python
def make_contract(
    web3: Web3,
    address: str,
    abi: list[dict[str, Any]],
) -> Contract:
```

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

### balance_of / balance_of_async method signatures

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

Method signatures for balance_of_async and balance_of. Both return the USDT balance in wei via usdt.functions.balanceOf(check_address).call(). The address parameter defaults to predict_account, else the signer address. Only USDT is supported.

```python
async def balance_of_async(
    self,
    token: Literal["USDT"] = "USDT",
    address: str | None = None,
) -> int:

def balance_of(
    self,
    token: Literal["USDT"] = "USDT",
    address: str | None = None,
) -> int:
```

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

### OrderBuilder

Source: https://github.com/predictdotfun/sdk-python/blob/main/_autodocs/index.md

The main class of the SDK, providing all 43 public methods for building, signing, and cancelling orders, managing approvals, and performing position operations.

```APIDOC
## OrderBuilder

### Description
The `OrderBuilder` class is the main entry point for the Predict SDK. It provides methods to build, sign (EIP-712), and cancel CTF Exchange orders, manage approvals (ERC-1155 operator approvals and ERC-20 USDT allowances), perform on-chain position operations (split/merge/redeem/convert), and support both EOA signers and Predict smart accounts (Kernel wallets).

### Import Path
- `predict_sdk.order_builder`
- `predict_sdk` (re-exported)

### Public Methods
All 43 public methods are available on this class. Refer to the source code for the full list of method signatures and parameters.
```

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

### Run approval steps with progress reporting

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

Runs approval steps with progress reporting. The `run_approvals` method accepts `skip_satisfied` (default True) and `stop_on_error` (default True) options, and an `on_progress` callback that receives an `ApprovalProgress(step, status, transaction)` as each step transitions. The returned `ApprovalRunReport` has `success` and `steps` fields.

```python
builder = OrderBuilder.make(ChainId.BNB_MAINNET, private_key)

steps = builder.get_approval_steps(
    ApprovalScope(operation="TRADE", is_neg_risk=True, is_yield_bearing=False)
)

report = builder.run_approvals(
    steps,
    skip_satisfied=True,     # default
    stop_on_error=True,      # default
    on_progress=lambda p: update_ui(p.step.id, p.status),
)
```

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

### Internal utility function signatures

Source: https://github.com/predictdotfun/sdk-python/blob/main/_autodocs/api-reference/internal-utilities.md

Function signatures for the internal utilities module. `float_to_wei` converts a float to integer wei using Decimal quantization with ROUND_DOWN, matching Solidity integer division. `generate_order_salt` returns a random salt string used by `OrderBuilder.make` when no custom generator is supplied. `retain_significant_digits` truncates to N significant digits and handles negatives. `hash_kernel_message` applies the Kernel inner wrapper keccak256("Kernel(bytes32 hash)" || hash). `eip712_wrap_hash` wraps a hash with the EIP-712 domain separator. `compute_order_hash` returns the EIP-191 hash of `encode_typed_data(full_message=typed_data)`.

```python
def float_to_wei(value: float, precision: int) -> int:
def generate_order_salt() -> str:
def retain_significant_digits(num: int, significant_digits: int) -> int:
def hash_kernel_message(message_hash: str) -> str:
def eip712_wrap_hash(message_hash: str, domain: dict[str, Any]) -> str:
def compute_order_hash(typed_data: dict[str, Any]) -> str:
```

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

### Check Balance with balance_of

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

Checks the USDT balance for the signer's address. The token parameter defaults to "USDT". Returns an integer balance.

```python
balance = builder.balance_of("USDT")
print(f"USDT Balance: {balance}")

```

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

### sign_typed_data_order and async variant signatures

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

Signatures for sign_typed_data_order and its async twin. The async version is a thin wrapper because signing is CPU-bound. Both return a SignedOrder with signature set; hash remains None.

```python
def sign_typed_data_order(self, typed_data: EIP712TypedData) -> SignedOrder:

async def sign_typed_data_order_async(self, typed_data: EIP712TypedData) -> SignedOrder:
```
Tokens:
Raw