@somnia-chain/markets-sdk / index / Trader

Interface: Trader

Defined in: packages/sdk/src/trade.ts:2122

The SDK's write tier — every pool/market transaction it can sign and send, bound to one signer. Built via client.createTrader(config) (see TraderConfig); shares that client's chain, addresses, and WebSocket.

Every write AWAITS its receipt before resolving — there is no bare-hash return to babysit. Order placements additionally resolve to the decoded order id + fills.

Methods

placeOrder()

placeOrder(params): Promise<PlaceOrderResult>

Defined in: packages/sdk/src/trade.ts:2148

Place a limit order (auto-approving the escrow token by default). Resolves once mined, with the resting order id and any fills.

Gotchas

Throws InvalidInputError - price or quantity was not > 0.
Throws ContractRevertError - the pool rejected the order; errorName carries the protocol's own error (e.g. InsufficientBalance). Also thrown when the transaction mines with a reverted status — the SDK replays the call to recover the reason, so you get a name rather than a failed receipt.
Throws RpcError - the send never got an answer from the node.

Example (Placing a binary bid)

Bid 0.62 for 10 YES, bigint-exact (6-decimal collateral).

const trader = client.createTrader({ privateKey });
const res = await trader.placeOrder({
  pool,
  side: "BUY_YES",
  price: 620_000n,       // 0.62 × 10^6
  quantity: 10_000_000n, // 10 outcome tokens × 10^6
});
console.log(res.orderId, res.fills.length); // resting id (if it rested) + immediate fills

Parameters

params

PlaceOrderParams

Returns

Promise<PlaceOrderResult>

cancelOrder()

cancelOrder(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2157

Cancel a resting order on its pool (works for spot + binary).

Gotchas

Throws ContractRevertError - the cancel did not land (already filled, already canceled, not the owner — errorName distinguishes them).
Throws RpcError - the send never got an answer from the node.

Parameters

params

CancelOrderParams

Returns

Promise<TxResult>

reduceOrder()

reduceOrder(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2163

Shrink a resting order's remaining quantity in place, keeping its price-time queue priority (works for spot + binary). Reverts on-chain for an expired order — use Trader.cancelOrder there.

Parameters

params

ReduceOrderParams

Returns

Promise<TxResult>

cancelExpiredOrders()

cancelExpiredOrders(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2169

Permissionless keeper drain: clean an explicit list of expired resting orders on a pool, returning each order's escrow to its owner (best-effort; skips non-expired / stale ids).

Parameters

params

CancelExpiredOrdersParams

Returns

Promise<TxResult>

sweepExpiredAtLevel()

sweepExpiredAtLevel(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2174

Permissionless keeper drain: clean up to maxCount expired orders at one price level on a side.

Parameters

params

SweepExpiredAtLevelParams

Returns

Promise<TxResult>

captureClose()

captureClose(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2181

Permissionless closing-price capture on a BinaryPool (post-expiry): stores the closing mid and lifts the closing-book lock. Required before sweeping a pre-terminal closing book — a CloseNotCaptured revert on a cancel/sweep means "capture first, then retry".

Parameters

params

CaptureCloseParams

Returns

Promise<TxResult>

approveBuilder()

approveBuilder(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2197

Opt a routing/builder frontend in on a pool so orders the trader places with that builder code may charge up to maxFeeBpsTimes1k (0 revokes). Required before a non-zero builder/builderFeeBpsTimes1k on Trader.placeOrder, Trader.placeSpotOrder or Trader.placePerpOrder.

Binary, spot and perp pools each implement this interface, but the approval is stored PER POOL: approving a builder on one pool grants nothing on another. Call it once per pool the trader will place attributed orders on, or the placement reverts. Each pool declares the whole builder-error set; which one fires depends on the check that trips first. With NO approval at all that is BuilderNotApproved on a SpotPool (it guards approved > 0), BuilderFeeExceedsApproval on a PerpPool, and BuilderFeeExceedsCap on a BinaryPool — whose ceiling, unlike the other two, is frozen at init.

Parameters

params

ApproveBuilderParams

Returns

Promise<TxResult>

getBuilderApproval()

getBuilderApproval(ref): Promise<bigint>

Defined in: packages/sdk/src/trade.ts:2199

Read a trader's per-builder approval cap on a pool (pool bps×1000; 0 = none).

Parameters

ref

BuilderApprovalRef

Returns

Promise<bigint>

getEffectiveBuilderApproval()

getEffectiveBuilderApproval(ref): Promise<bigint>

Defined in: packages/sdk/src/trade.ts:2205

Effective builder approval on a pool: the trader's raw cap clamped by the pool's protocol-wide getMaxBuilderFeeBpsTimes1k ceiling — the actual enforced limit a builderFeeBpsTimes1k on any place-order verb must not exceed.

Parameters

ref

BuilderApprovalRef

Returns

Promise<bigint>

getMaxBuilderFeeBpsTimes1k()

getMaxBuilderFeeBpsTimes1k(pool): Promise<bigint>

Defined in: packages/sdk/src/trade.ts:2207

Read a pool's protocol-wide builder-fee ceiling (bps×1000).

Parameters

pool

`0x${string}`

Returns

Promise<bigint>

placeSpotOrder()

placeSpotOrder(params): Promise<PlaceOrderResult>

Defined in: packages/sdk/src/trade.ts:2218

Place a spot limit/market order on a SpotPool (auto-approves the escrow token, or sends native msg.value on a native-base sell).

An ERC-20 approval check uses requiredAmount, which is the pool's worst-case reserve including fee headroom. A native sell sends delta, which subtracts the owner's current vault balance from that reserve. The SDK reads the requirement once per uncached token/pool approval and on each native-base sell.

Parameters

params

PlaceSpotOrderParams

Returns

Promise<PlaceOrderResult>

placeSpotOrders()

placeSpotOrders(params): Promise<PlaceSpotOrdersResult>

Defined in: packages/sdk/src/trade.ts:2267

Place several orders on one SpotPool in a single transaction — a market maker's ladder in one tx instead of a loop of sends.

Gotchas

This write is NON-PAYABLE: unlike Trader.placeSpotOrder, it takes no msg.value. A native-base sell in a batch therefore funds from the pool's VAULT balance — pre-deposit native to the vault and auto-pull consumes it. ERC-20 auto-pull works normally per request, and the batch approves each escrow token once for the whole batch's total.

SPOT ONLY. A binary pool reverts UseBinaryPlacement on generic placement — the YES/NO kind must be explicit, so use Trader.placeOrder there.

A request that does not place is NOT an error: outcomes[i].success is false with no id for a PostOnly that would cross, an unfilled FillOrKill, an IOC that found no liquidity, an already-expired expiry, or a CancelTaker self-match. A hard validation error (bad lot size, insufficient funds) reverts the whole batch.

Outcome attribution matches each OrderPlaced event to its request on every field the event echoes (side, price, quantity, userData, expiry), in order. Two byte-identical adjacent requests with different outcomes are therefore indistinguishable from logs — the earlier index gets the credit. Tag rungs with distinct userData when exact attribution matters.

Throws InvalidInputError - orders was empty, or a request had a non-positive price or quantity.
Throws ContractRevertError - the batch was rejected; errorName carries the protocol's error (EmptyBatch, UseBinaryPlacement on a binary pool, or a per-order validation failure).

Example (Placing a spot-order batch)

// Place a three-rung sell ladder in one transaction.
const trader = client.createTrader({ privateKey });
const res = await trader.placeSpotOrders({
  pool,
  quoteToken,
  baseToken,
  orders: [1_010_000n, 1_020_000n, 1_030_000n].map((price) => ({
    isBid: false,
    price,
    quantity: 1_000_000n,
  })),
});
// Index-aligned with `orders`; a rung that did not place is success:false.
const ids = res.outcomes.flatMap((o) => (o.success ? [o.orderId!] : []));

Parameters

params

PlaceSpotOrdersParams

Returns

Promise<PlaceSpotOrdersResult>

cancelOrders()

cancelOrders(params): Promise<CancelOrdersResult>

Defined in: packages/sdk/src/trade.ts:2293

Cancel several resting orders on one pool in a single transaction — pull a whole ladder without leaving the remaining rungs exposed. Works on spot AND binary pools (cancel is inherited from the OrderBook base, not placement-gated).

Gotchas

BEST-EFFORT by design: an id that can no longer be cancelled (already filled, already cancelled, expired-and-swept, not owned by the signer) is SKIPPED on-chain instead of reverting the batch — which is the point in a fast market. Each outcomes[i].cancelled is inferred from whether the id emitted a cancel event, so a false does NOT tell you WHY: a benign fill race and a wrong id look identical here. Reconcile against the book if you need to know.

Throws InvalidInputError - orderIds was empty.
Throws ContractRevertError - errorName EmptyBatch when the contract rejects the payload.

Example (Inspecting batch cancellations)

const trader = client.createTrader({ privateKey });
const res = await trader.cancelOrders({ pool, orderIds: ladderIds });
const skipped = res.outcomes.filter((o) => !o.cancelled).map((o) => o.orderId);

Parameters

params

CancelOrdersParams

Returns

Promise<CancelOrdersResult>

reduceOrders()

reduceOrders(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2309

Shrink several resting orders in place in a single transaction, each keeping its price-time queue priority. Works on spot AND binary pools.

Gotchas

ATOMIC, unlike Trader.cancelOrders: the FIRST invalid reduction reverts the entire batch and no order changes. A reduction is invalid if the new quantity is not a lotSize multiple, is below minQuantity, is not strictly less than the current remaining, or the order has expired (cancel those instead). Size the batch accordingly — one stale id loses the whole tx.

Throws InvalidInputError - reductions was empty.
Throws ContractRevertError - a reduction was rejected; errorName carries the protocol's error.

Parameters

params

ReduceOrdersParams

Returns

Promise<TxResult>

placePerpOrder()

placePerpOrder(params): Promise<PlaceOrderResult>

Defined in: packages/sdk/src/trade.ts:2314

Place a perp limit/market order on a PerpPool. Margin is locked from the signer's MarginBank balance — Trader.depositMargin first.

Parameters

params

PlacePerpOrderParams

Returns

Promise<PlaceOrderResult>

amendOrder()

amendOrder(params): Promise<AmendOrderResult>

Defined in: packages/sdk/src/trade.ts:2358

Cancel ONE resting order and place its replacement atomically — the re-quote primitive, with no gap on the book.

When to use

Re-pricing a single quote. For a whole ladder use Trader.amendOrders, which cancels every old order before placing any replacement. To shrink an order without losing its place in the queue use Trader.reduceOrder — amend is not priority-preserving.

Details

Prefer this over Trader.amendOrders with a one-element array: this raises the replacement's own landing-time reason (PostOnlyWouldCross, SelfMatchCancelTaker, ImmediateOrCancelNoFill, FillOrKillNotFillable, OrderAlreadyExpired), where the batch wraps it as AmendReplacementRejected(requestIndex, reason) and leaves the caller unwrapping an index it already knew.

Gotchas

SpotPool and PerpPool only — a BinaryPool reverts UseBinaryPlacement, since binary placement is its own entry point. The replacement gets a NEW order id, so update local tracking. Non-payable: a native auto-pull amend reverts, because the cancel leg delivers the freed native to the wallet and the place leg cannot reach it — fund native replacements from a manual-vault balance.

Throws InvalidInputError - price or quantity was not > 0.
Throws ContractRevertError - the old order was gone and alwaysPlace was not set (AmendOldOrderGone), it belongs to someone else (IncorrectSender), or the replacement did not rest or fill; errorName carries the protocol's error.

Example (Amending an order)

Re-quote one bid a tick lower, and keep the new id.

const { newOrderId } = await trader.amendOrder({
  pool,
  oldOrderId: resting,
  newOrder: { isBid: true, price: 1_990_000n, quantity: 5_000_000n },
});

Parameters

params

AmendOrderParams

Returns

Promise<AmendOrderResult>

amendOrders()

amendOrders(params): Promise<AmendOrdersResult>

Defined in: packages/sdk/src/trade.ts:2363

Cancel N orders and place their replacements atomically. All-or-nothing, and it places — so the same BinaryPool restriction applies.

Parameters

params

AmendOrdersParams

Returns

Promise<AmendOrdersResult>

buildPlaceOrder()

buildPlaceOrder(params): Promise<UnsignedOrder>

Defined in: packages/sdk/src/trade.ts:2404

Build a binary placement WITHOUT sending it — the same inputs as Trader.placeOrder, handed back as unsigned calls.

When to use

Reach for this when the signing and the sending are not the same moment: to pre-sign an ERC-4337 UserOp while the user is still filling in the form, to batch the order into a multicall, to hand it to a relayer, or to simulate it. For ordinary "place this order now", use Trader.placeOrder — it is one call and it handles the approval for you.

Gotchas

The approval is RETURNED, not sent. placeOrder approves as a side effect; this cannot, because sending is exactly what it must not do. Send approval first when it is present, or the order reverts on-chain.

Still async: a binary placement reads the pool's market expiry when the caller does not pass expireTimestampNs, and resolves the pool's escrow tokens to work out which approval is needed. Pass expireTimestampNs, outcomeToken, yesId, noId, and collateral to keep it off the network.

No gas estimate and no nonce ride along — those belong to the signer, and pinning them here would stale the moment the call is cached.

Throws InvalidInputError - price or quantity was not > 0.

Example (Building an unsigned order)

Pre-sign off the form, send on the click.

const { order, approval } = await trader.buildPlaceOrder({
  pool, side: "BUY_YES", price: 620_000n, quantity: 10_000_000n,
});
if (approval) await walletClient.sendTransaction({ ...approval, account });
const signed = await account.signTransaction({ ...order, nonce, ...fees });

Parameters

params

PlaceOrderParams

Returns

Promise<UnsignedOrder>

buildPlaceSpotOrder()

buildPlaceSpotOrder(params): Promise<UnsignedOrder>

Defined in: packages/sdk/src/trade.ts:2428

Build a spot placement WITHOUT sending it — see Trader.buildPlaceOrder for when to reach for this and how the returned approval works.

A native-base sell pays via msg.value, so it comes back with no approval and a non-zero order.value: the pool's vault shortfall for this order, fee headroom included, as read when the call is built. A vault that gains funds before the send only shrinks the requirement (the pool refunds the overage); one that loses them makes the pool reject the call.

Throws InvalidInputError - price or quantity is not positive.
Throws ContractRevertError - the native-sell funding read reverted.
Throws RpcError - the native-sell funding read did not complete.

Gotchas

A spot placement that DEFAULTS its expiry pins it to ~50 years from now, so two builds a second apart differ in that one argument. Harmless against a 50-year horizon, but it means such a build is not byte-reproducible: sign and send the order you were handed rather than rebuilding and expecting the same bytes. Pass PlaceSpotOrderParams.expireTimestampNs explicitly and the build is reproducible, as binary and perp already are.

Parameters

params

PlaceSpotOrderParams

Returns

Promise<UnsignedOrder>

buildPlacePerpOrder()

buildPlacePerpOrder(params): Promise<UnsignedOrder>

Defined in: packages/sdk/src/trade.ts:2436

Build a perp placement WITHOUT sending it — see Trader.buildPlaceOrder for when to reach for this.

Never carries an approval: margin is locked from the MarginBank balance rather than escrowed per order (Trader.depositMargin first).

Parameters

params

PlacePerpOrderParams

Returns

Promise<UnsignedOrder>

depositMargin()

depositMargin(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2441

Deposit collateral into the MarginBank (auto-approving the collateral token to the bank by default). One cross-margin balance covers every perp pool.

Parameters

params

DepositMarginParams

Returns

Promise<TxResult>

withdrawMargin()

withdrawMargin(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2443

Withdraw free collateral from the MarginBank (margin-checked on-chain).

Parameters

params

WithdrawMarginParams

Returns

Promise<TxResult>

withdrawVault()

withdrawVault(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2451

Claim a payout that fell back to a pool's internal ERC20Vault (a PayoutFallbackToVault credit) back to the wallet. Read the claimable amount first with client.getVaultBalance({ vault, owner, token }).

Also how funds leave a manual-mode balance — see setManualVaultMode.

Parameters

params

WithdrawVaultParams

Returns

Promise<TxResult>

depositVault()

depositVault(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2458

Pre-fund an ERC-20 balance in a pool's internal vault (approves the pool when needed). Ordinary placement needs no deposit — auto-pull covers it; deposit when funding must precede the order. Native goes in via depositVaultNative.

Parameters

params

DepositVaultParams

Returns

Promise<TxResult>

depositVaultNative()

depositVaultNative(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2472

Pre-fund a native (SOMI) vault balance for the signer, or for another account when owner is set. The amount travels as msg.value.

A binary pool's vault takes exactly one token, so the SDK reads the pool's collateralToken() first and refuses a native deposit into a pool whose collateral is not native rather than spending a failed transaction. A pool without that view (a SpotPool) goes straight to the chain.

Throws InvalidInputError - amount is not positive, or the pool is a binary pool whose collateral is not native.
Throws RpcError - the preflight read or the deposit did not complete. A failed preflight never broadcasts.
Throws ContractRevertError - the pool rejected the deposit (InvalidDepositOrWithdrawal when native is not one of its tokens).

Parameters

params

DepositVaultNativeParams

Returns

Promise<TxResult>

depositVaultNativeFor()

depositVaultNativeFor(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2477

Pre-fund ANOTHER account's native vault balance — depositVaultNative with owner required (an operator funding a bot wallet). Same errors.

Parameters

params

DepositVaultNativeParams & object

Returns

Promise<TxResult>

setManualVaultMode()

setManualVaultMode(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2483

Opt out of (or back into) wallet auto-pull on one SpotPool. While enabled, orders draw only on pre-deposited vault balance AND payouts stay as vault credit — claim them with withdrawVault. Scoped per user per pool.

Parameters

params

SetManualVaultModeParams

Returns

Promise<TxResult>

setOperatorApprovalForPool()

setOperatorApprovalForPool(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2489

Grant or revoke an operator on ONE SpotPool — the tighter way to let a bot trade for you. The signer is the granting owner; approved: false revokes. Read it back with SomniaMarketsClient.isApprovedForPool.

Parameters

params

SetOperatorApprovalForPoolParams

Returns

Promise<TxResult>

setOperatorApprovalGlobal()

setOperatorApprovalGlobal(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2495

Grant or revoke an operator across EVERY registered pool. Required for SpotRouter (not on any pool's allowlist); prefer setOperatorApprovalForPool for a single-venue bot.

Parameters

params

SetOperatorApprovalGlobalParams

Returns

Promise<TxResult>

setPerpLeverage()

setPerpLeverage(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2497

Set the signer's max leverage for one perp pool (caps position size vs margin).

Parameters

params

SetPerpLeverageParams

Returns

Promise<TxResult>

proposePerpWalletLink()

proposePerpWalletLink(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2517

Offer a child wallet a link to the signer as its main — the first half of the handshake that gives a perp sub-account access to the signer's wallet.

Isolated margin on perps is one wallet per position, so a trader running N isolated positions runs N wallets. Linking them lets each child's position-increasing order draw its shortfall from this main's wallet, so one funded treasury serves all N.

The signer is the MAIN and this moves no money. The child must send acceptPerpWalletLink next, and it is the only party that can: read the offer from client.listPerpWalletLinkEvents({ child }), which is the ONLY record of a pending proposal.

Throws InvalidInputError - registry is the zero address, or none of registry, marginBank and pool was passed.
Throws NotConfiguredError - the bank holds no registry, so the rail is dormant on this deployment.
Throws RpcError - the registry or bank resolution read did not complete. A failed resolution never broadcasts.
Throws ContractRevertError - CannotLinkSelf, CallerIsChild (the signer is already someone's child), AlreadyLinked (child already has a main), NoStateChange (this offer already stands), or ZeroAddress.

Parameters

params

ProposePerpWalletLinkParams

Returns

Promise<TxResult>

acceptPerpWalletLink()

acceptPerpWalletLink(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2531

Accept a main's standing offer, as the child — the second half of the handshake.

From here the signer's position-increasing orders pull their shortfall from main's wallet. Funding does not wait for link maturity; maturesAt gates ADL netting only.

Throws InvalidInputError - registry is the zero address, or none of registry, marginBank and pool was passed.
Throws NotConfiguredError - the bank holds no registry, so the rail is dormant on this deployment.
Throws RpcError - the registry or bank resolution read did not complete. A failed resolution never broadcasts.
Throws ContractRevertError - NoProposalPending, CallerIsChild (main has itself become a child), CallerIsMain (the signer already has children), AlreadyLinked, or MaxChildrenReached.

Parameters

params

AcceptPerpWalletLinkParams

Returns

Promise<TxResult>

cancelPerpWalletLinkProposal()

cancelPerpWalletLinkProposal(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2541

Withdraw an offer the signer made and the child has not accepted. An ACCEPTED link comes down with unlinkPerpWallet instead.

Throws InvalidInputError - registry is the zero address, or none of registry, marginBank and pool was passed.
Throws NotConfiguredError - the bank holds no registry, so the rail is dormant on this deployment.
Throws RpcError - the registry or bank resolution read did not complete. A failed resolution never broadcasts.
Throws ContractRevertError - NoProposalPending (nothing pending for this pair, including an offer already accepted).

Parameters

params

CancelPerpWalletLinkProposalParams

Returns

Promise<TxResult>

unlinkPerpWallet()

unlinkPerpWallet(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2554

Dissolve an accepted link, from either end — pass the other party.

Settles no money: a claim the main funded survives the unlink and still gates the child's withdrawals. PerpsUnlinkGuard vetoes it while the leaver holds open positions and is liquidatable.

Throws InvalidInputError - registry is the zero address, or none of registry, marginBank and pool was passed.
Throws NotConfiguredError - the bank holds no registry, so the rail is dormant on this deployment.
Throws RpcError - the registry or bank resolution read did not complete. A failed resolution never broadcasts.
Throws ContractRevertError - NotLinked (the two are not a linked pair) or UnlinkBlockedByGuard (the leaver is liquidatable with open positions).

Parameters

params

UnlinkPerpWalletParams

Returns

Promise<TxResult>

repayPerpMainFunding()

repayPerpMainFunding(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2567

Return principal the signer's main funded, as the child.

Over-asking is clamped to min(amount, outstanding, balance) rather than rejected, so the outstanding figure from client.getPerpMainFunding cannot be stale-high. Repaying is what unlocks the child's own money: withdraw frees at most balance - outstanding.

Throws InvalidInputError - amount is not positive, marginBank is the zero address, or neither marginBank nor pool was passed.
Throws RpcError - the bank resolution read did not complete. A failed resolution never broadcasts.
Throws ContractRevertError - NoFundedPrincipal (nothing outstanding), NothingToReturn (the clamp reached zero, so the balance is gone), or InsufficientMarginAfterWithdrawal.

Parameters

params

RepayPerpMainFundingParams

Returns

Promise<TxResult>

recallPerpMainFunding()

recallPerpMainFunding(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2579

Pull principal back out of a child, as the payer. The signer must be the payer the bank recorded at funding time.

Recovers principal, never winnings, and performs no unlink — the child can be funded again without a fresh handshake.

Throws InvalidInputError - amount is not positive, marginBank is the zero address, or neither marginBank nor pool was passed.
Throws RpcError - the bank resolution read did not complete. A failed resolution never broadcasts.
Throws ContractRevertError - OnlyFundingPayer (the signer is not the recorded payer), NoFundedPrincipal, NothingToReturn, or InsufficientMarginAfterWithdrawal.

Parameters

params

RecallPerpMainFundingParams

Returns

Promise<TxResult>

pokeFunding()

pokeFunding(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2581

Permissionlessly poke a perp pool's funding settlement (updateFunding).

Parameters

params

pool

`0x${string}`

gas?

bigint

Returns

Promise<TxResult>

placeSpotStopOrder()

placeSpotStopOrder(params): Promise<PlaceStopOrderResult>

Defined in: packages/sdk/src/trade.ts:2586

Place a spot stop-loss / take-profit pending order on a SpotStopOrderRegistry (funds the trigger via SOMI msg.value).

Parameters

params

PlaceSpotStopOrderParams

Returns

Promise<PlaceStopOrderResult>

cancelStopOrder()

cancelStopOrder(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2588

Cancel a pending stop order on its registry.

Parameters

params

CancelStopOrderParams

Returns

Promise<TxResult>

placePerpStopOrder()

placePerpStopOrder(params): Promise<PlacePerpStopOrderResult>

Defined in: packages/sdk/src/trade.ts:2599

Place a perp take-profit / stop-loss on a PerpStopOrderRegistry (funds the trigger via SOMI msg.value), granting the registry's one-time operator approval first if the signer has not already.

The single perp-stop create entry: pass pair for a linked one-cancels-other set, or intent: "opening" for a stop-entry. Both default off, so an existing call is an ordinary reduce-only stop and produces the same transaction it always did.

Parameters

params

PlacePerpStopOrderParams

Returns

Promise<PlacePerpStopOrderResult>

linkPerpStopOrders()

linkPerpStopOrders(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2604

Link two existing perp stops into a one-cancels-other pair — the after-the-fact form of placePerpStopOrder({ pair }), and how a survivor is re-paired.

Parameters

params

LinkPerpStopOrdersParams

Returns

Promise<TxResult>

cancelPerpStopOrder()

cancelPerpStopOrder(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2609

Cancel a pending perp stop. If it is one leg of a pair the other stays armed and is unlinked — use cancelPerpStopOrders to tear down both.

Parameters

params

CancelStopOrderParams

Returns

Promise<TxResult>

cancelPerpStopOrders()

cancelPerpStopOrders(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2611

Cancel several of the signer's pending perp stops in one tx, one refund transfer.

Parameters

params

CancelPerpStopOrdersParams

Returns

Promise<TxResult>

claimPerpStopSomi()

claimPerpStopSomi(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2616

Claim SOMI the perp stop registry owes the signer — the refund path for an owner that cannot receive native. Reverts NothingToClaim on a zero balance.

Parameters

params

ClaimPerpStopSomiParams

Returns

Promise<TxResult>

buildPlacePerpStopOrder()

buildPlacePerpStopOrder(params): Promise<UnsignedPerpStopOrder>

Defined in: packages/sdk/src/trade.ts:2636

Build placePerpStopOrder without sending it — the stop-registry call plus, unless skipped, the operator grant the trigger needs first.

Recover the created ids from your own receipt with decodePerpStopOrderIds.

Parameters

params

PlacePerpStopOrderParams

Returns

Promise<UnsignedPerpStopOrder>

buildCancelPerpStopOrder()

buildCancelPerpStopOrder(params): UnsignedCall

Defined in: packages/sdk/src/trade.ts:2638

Build cancelPerpStopOrder without sending it.

Parameters

params

CancelStopOrderParams

Returns

UnsignedCall

buildCancelPerpStopOrders()

buildCancelPerpStopOrders(params): UnsignedCall

Defined in: packages/sdk/src/trade.ts:2640

Build cancelPerpStopOrders without sending it.

Parameters

params

CancelPerpStopOrdersParams

Returns

UnsignedCall

buildDepositMargin()

buildDepositMargin(params): Promise<UnsignedMarginDeposit>

Defined in: packages/sdk/src/trade.ts:2645

Build depositMargin without sending it — the deposit call plus, unless autoApprove: false, the ERC-20 approval the bank needs first.

Parameters

params

DepositMarginParams

Returns

Promise<UnsignedMarginDeposit>

buildWithdrawMargin()

buildWithdrawMargin(params): Promise<UnsignedCall>

Defined in: packages/sdk/src/trade.ts:2647

Build withdrawMargin without sending it. Nothing to approve.

Parameters

params

WithdrawMarginParams

Returns

Promise<UnsignedCall>

buildAcceptPerpWalletLink()

buildAcceptPerpWalletLink(params): Promise<UnsignedCall>

Defined in: packages/sdk/src/trade.ts:2657

Build acceptPerpWalletLink without sending it, so the accept and the child's first isolated placement go out as ONE transaction. The accept must execute first, or the placement finds no main.

Throws InvalidInputError - registry is the zero address, or none of registry, marginBank and pool was passed.
Throws NotConfiguredError - the bank holds no registry, so the rail is dormant on this deployment.
Throws RpcError - the registry or bank resolution read did not complete. A failed resolution never broadcasts.

Parameters

params

AcceptPerpWalletLinkParams

Returns

Promise<UnsignedCall>

buildRepayPerpMainFunding()

buildRepayPerpMainFunding(params): Promise<UnsignedCall>

Defined in: packages/sdk/src/trade.ts:2666

Build repayPerpMainFunding without sending it, so the repayment and the withdrawal it unlocks go out as ONE transaction. The repayment must execute first — the withdrawal's gate reads the claim it clears.

Throws InvalidInputError - amount is not positive, marginBank is the zero address, or neither marginBank nor pool was passed.
Throws RpcError - the bank resolution read did not complete.

Parameters

params

RepayPerpMainFundingParams

Returns

Promise<UnsignedCall>

mintSet()

mintSet(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2669

Mint a YES+NO set: deposit collateral, receive equal YES + NO.

Parameters

params

MintSetParams

Returns

Promise<TxResult>

burnSet()

burnSet(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2671

Burn a YES+NO set: surrender both halves, receive collateral back.

Parameters

params

BurnSetParams

Returns

Promise<TxResult>

redeem()

redeem(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2678

Burn winning outcome tokens for collateral (resolved/voided markets). Settlement-extraction v2: module-routed — the module pulls the caller's winning tokens, finalizes-if-needed, and redeems through BinarySettlement. Takes marketId (not a pool address — a pool serves successive markets).

Parameters

params

RedeemParams

Returns

Promise<TxResult>

signRedeemAuth()

signRedeemAuth(params): Promise<RedeemAuthorization>

Defined in: packages/sdk/src/trade.ts:2686

Produce an EIP-712 RedeemAuthorization the connected signer (the position owner) hands to a relayer, so the relayer can call Trader.redeemFor and pay the gas while the OWNER receives the payout. Signs over the module's REDEEM_AUTH_TYPEHASH in the SomniaMarkets domain; no transaction is sent.

Parameters

params

SignRedeemAuthParams

Returns

Promise<RedeemAuthorization>

redeemFor()

redeemFor(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2692

Relayer path: submit a position owner's pre-signed RedeemAuthorization (from Trader.signRedeemAuth). The caller pays gas; the module pays the OWNER the collateral (payout is hard-pinned to owner, never the relayer).

Parameters

params

RedeemForParams

Returns

Promise<TxResult>

redeemMany()

redeemMany(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2694

Claim winnings from many settled markets in one transaction (batch redeem).

Parameters

params

RedeemManyParams

Returns

Promise<TxResult>

redeemDirect()

redeemDirect(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2699

Low-level direct redemption against the BinarySettlement singleton (bypasses the module; no operator attribution). Takes the raw ERC-6909 outcomeId.

Parameters

params

RedeemDirectParams

Returns

Promise<TxResult>

claimOwed()

claimOwed(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2701

Claim an accrued push-fallback (owed) balance on the settlement singleton.

Parameters

params

ClaimOwedParams

Returns

Promise<TxResult>

pokeOracle()

pokeOracle(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2723

Permissionless oracle retry — the FIRST move when a market is past expiry with no resolution: ask the module to re-pull the answer for its oracle question.

When to use

Use before Trader.voidExpired. A poke that succeeds resolves the market normally (winners paid in full); voiding pays everyone 1/N instead, so it is the fallback, not the first resort.

Gotchas

Keyed by ORACLE QUESTION, not market: the module fans out to every market bound to that question and resolves the ones whose adapter answers. Unanswered adapters are skipped, so this can resolve some markets and leave others — a success is not "all bound markets resolved". Reverts OracleNotAnswered only when none answered, UnknownOracleQuestion when no market is bound; both decode as ContractRevertError, so a keeper loop can branch on errorName.

Parameters

params

PokeOracleParams

Returns

Promise<TxResult>

voidExpired()

voidExpired(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2749

Permissionless dead-oracle escape hatch: void a market whose oracle never answered, so both sides can redeem at 1/N collateral.

When to use

Use only after Trader.pokeOracle has failed and expiry + settlementWindow has elapsed — this is the funds-unstranding backstop, and it pays 1/N rather than the real outcome.

Gotchas

This writes to the MARKET contract, bypassing the module — so the oracle hub's earmark release never fires. Follow with Trader.syncSettlement, then Trader.finalizeMarket and Trader.releasePool, to leave the market fully reconciled.

Before sending, this reads the market's status, expiry, and settlement window and throws InvalidInputError naming the gate time if the window is still open — the on-chain SettlementWindowOpen revert carries no timestamp, and "when can I retry" is the operator's real question. The comparison uses the chain's block.timestamp, matching the contract, so a skewed local clock neither lets a doomed call through nor blocks a valid one. Pass skipPreflight to send blind and let the contract judge.

Parameters

params

VoidExpiredParams

Returns

Promise<TxResult>

finalizeMarket()

finalizeMarket(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2754

Permissionless keeper: finalize a settled market (sweep its pool's backing + resolution snapshot to the settlement singleton). No-op-guarded on repeat.

Parameters

params

FinalizeMarketParams

Returns

Promise<TxResult>

syncSettlement()

syncSettlement(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2760

Permissionless earmark reconcile: release the oracle earmark of a market voided via BinaryMarket.voidExpired() (which bypasses the module, so the hub's earmark release never fired). Idempotent; reverts MarketNotSettled while still live.

Parameters

params

SyncSettlementParams

Returns

Promise<TxResult>

releasePool()

releasePool(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2765

Permissionless keeper: release a finalized, drained pool back to its creator's free list for recycle onto the next market.

Parameters

params

ReleasePoolParams

Returns

Promise<TxResult>

getSettlement()

getSettlement(marketId, opts?): Promise<SettlementRecord | null>

Defined in: packages/sdk/src/trade.ts:2771

Read a market's settlement record from the BinarySettlement singleton (by bytes32 marketId — resolves the marketKey via the module's yesId). Returns null when the market has never been finalized.

Parameters

marketId

`0x${string}`

opts?

module?

`0x${string}`

settlement?

`0x${string}`

Returns

Promise<SettlementRecord | null>

getFreePools()

getFreePools(creator, collateral, opts?): Promise<`0x${string}`[]>

Defined in: packages/sdk/src/trade.ts:2773

Read a creator's free (finalized + released, reusable) pools for a collateral.

Parameters

creator

`0x${string}`

collateral

`0x${string}`

opts?

module?

`0x${string}`

Returns

Promise<`0x${string}`[]>

poolCreator()

poolCreator(pool, opts?): Promise<`0x${string}`>

Defined in: packages/sdk/src/trade.ts:2775

Read a pool's creator (its first-deploy creator — the only party that can reuse it).

Parameters

pool

`0x${string}`

opts?

module?

`0x${string}`

Returns

Promise<`0x${string}`>

mintSetNative()

mintSetNative(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2780

Mint a complete YES+NO set paying with NATIVE token via the CollateralRouter (wraps msg.value → wNative). The market's collateral must be wNative.

Parameters

params

MintSetNativeParams

Returns

Promise<TxResult>

mintSetPermit2()

mintSetPermit2(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2785

Mint a complete YES+NO set pulling collateral via a Permit2 signature through the CollateralRouter (no prior ERC-20 approve).

Parameters

params

MintSetPermit2Params

Returns

Promise<TxResult>

redeemNative()

redeemNative(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2790

Redeem winning outcome tokens for a NATIVE payout via the CollateralRouter (unwraps wNative → native). Approve the router for the winning outcome first.

Parameters

params

RedeemNativeParams

Returns

Promise<TxResult>

faucet()

faucet(params?): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2792

Mint TestUSDC from the faucet to the signer.

Parameters

params?

FaucetParams

Returns

Promise<TxResult>

resolve()

resolve(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2794

Resolve a market via the FakeOracle (demo resolver).

Parameters

params

ResolveParams

Returns

Promise<TxResult>

voidMarket()

voidMarket(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2796

Void a market via the FakeOracle (demo resolver).

Parameters

params

VoidMarketParams

Returns

Promise<TxResult>

poke()

poke(params): Promise<TxResult>

Defined in: packages/sdk/src/trade.ts:2798

Poke a market to advance its lifecycle. No-op since status is derived; kept for ABI stability.

Parameters

params

market

`0x${string}`

gas?

bigint

Returns

Promise<TxResult>

clearApprovalCache()

clearApprovalCache(token?, spender?): void

Defined in: packages/sdk/src/trade.ts:2804

Forget cached token approvals so the next escrowing write re-checks allowance. Pass a (token, spender) to clear one pair, or nothing to clear all. Rarely needed — maxUint256 approvals don't decrement.

Parameters

token?

`0x${string}`

spender?

`0x${string}`

Returns

void