@somnia-chain/markets-sdk / index / Trader
Interface: Trader
Defined in: packages/sdk/src/trade.ts:1532
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:1557
Place a limit order (auto-approving the escrow token by default). Resolves once mined, with the resting order id and any fills.
Parameters
params
Returns
Promise<PlaceOrderResult>
Example
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
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.
cancelOrder()
cancelOrder(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:1565
Cancel a resting order on its pool (works for spot + binary).
Parameters
params
Returns
Promise<TxResult>
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.
reduceOrder()
reduceOrder(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:1571
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
Returns
Promise<TxResult>
cancelExpiredOrders()
cancelExpiredOrders(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:1577
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
Returns
Promise<TxResult>
sweepExpiredAtLevel()
sweepExpiredAtLevel(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:1582
Permissionless keeper drain: clean up to maxCount expired orders at one
price level on a side.
Parameters
params
Returns
Promise<TxResult>
approveBuilder()
approveBuilder(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:1598
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
Returns
Promise<TxResult>
getBuilderApproval()
getBuilderApproval(
ref):Promise<bigint>
Defined in: packages/sdk/src/trade.ts:1600
Read a trader's per-builder approval cap on a pool (pool bps×1000; 0 = none).
Parameters
ref
Returns
Promise<bigint>
getEffectiveBuilderApproval()
getEffectiveBuilderApproval(
ref):Promise<bigint>
Defined in: packages/sdk/src/trade.ts:1606
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
Returns
Promise<bigint>
getMaxBuilderFeeBpsTimes1k()
getMaxBuilderFeeBpsTimes1k(
pool):Promise<bigint>
Defined in: packages/sdk/src/trade.ts:1608
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:1613
Place a spot limit/market order on a SpotPool (auto-approves the escrow token, or sends native msg.value on a native-base sell).
Parameters
params
Returns
Promise<PlaceOrderResult>
placeSpotOrders()
placeSpotOrders(
params):Promise<PlaceSpotOrdersResult>
Defined in: packages/sdk/src/trade.ts:1666
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.
Example
// Place a three-rung sell ladder in one transaction.
const trader = client.createTrader({ privateKey });
const res = await trader.placeSpotOrders({
pool,
baseDecimals: 6,
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
Returns
Promise<PlaceSpotOrdersResult>
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).
cancelOrders()
cancelOrders(
params):Promise<CancelOrdersResult>
Defined in: packages/sdk/src/trade.ts:1693
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.
Example
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
Returns
Promise<CancelOrdersResult>
Throws
InvalidInputError - orderIds was empty.
Throws
ContractRevertError - errorName EmptyBatch when the contract
rejects the payload.
reduceOrders()
reduceOrders(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:1710
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.
Parameters
params
Returns
Promise<TxResult>
Throws
InvalidInputError - reductions was empty.
Throws
ContractRevertError - a reduction was rejected; errorName
carries the protocol's error.
placePerpOrder()
placePerpOrder(
params):Promise<PlaceOrderResult>
Defined in: packages/sdk/src/trade.ts:1715
Place a perp limit/market order on a PerpPool. Margin is locked from the signer's MarginBank balance — Trader.depositMargin first.
Parameters
params
Returns
Promise<PlaceOrderResult>
amendOrder()
amendOrder(
params):Promise<AmendOrderResult>
Defined in: packages/sdk/src/trade.ts:1760
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.
Parameters
params
Returns
Promise<AmendOrderResult>
Example
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 },
});
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.
amendOrders()
amendOrders(
params):Promise<AmendOrdersResult>
Defined in: packages/sdk/src/trade.ts:1765
Cancel N orders and place their replacements atomically. All-or-nothing, and it places — so the same BinaryPool restriction applies.
Parameters
params
Returns
Promise<AmendOrdersResult>
buildPlaceOrder()
buildPlaceOrder(
params):Promise<UnsignedOrder>
Defined in: packages/sdk/src/trade.ts:1804
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.
Parameters
params
Returns
Promise<UnsignedOrder>
Example
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 });
Throws
InvalidInputError - price or quantity was not > 0.
buildPlaceSpotOrder()
buildPlaceSpotOrder(
params):Promise<UnsignedOrder>
Defined in: packages/sdk/src/trade.ts:1821
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.
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
Returns
Promise<UnsignedOrder>
buildPlacePerpOrder()
buildPlacePerpOrder(
params):Promise<UnsignedOrder>
Defined in: packages/sdk/src/trade.ts:1829
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
Returns
Promise<UnsignedOrder>
depositMargin()
depositMargin(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:1834
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
Returns
Promise<TxResult>
withdrawMargin()
withdrawMargin(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:1836
Withdraw free collateral from the MarginBank (margin-checked on-chain).
Parameters
params
Returns
Promise<TxResult>
withdrawVault()
withdrawVault(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:1844
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
Returns
Promise<TxResult>
depositVault()
depositVault(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:1851
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
Returns
Promise<TxResult>
depositVaultNative()
depositVaultNative(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:1856
Pre-fund a native (SOMI) vault balance for the signer, or for another account
when owner is set. The amount travels as msg.value.
Parameters
params
Returns
Promise<TxResult>
depositVaultNativeFor()
depositVaultNativeFor(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:1861
Pre-fund ANOTHER account's native vault balance — depositVaultNative
with owner required (an operator funding a bot wallet).
Parameters
params
DepositVaultNativeParams & object
Returns
Promise<TxResult>
setManualVaultMode()
setManualVaultMode(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:1867
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
Returns
Promise<TxResult>
setOperatorApprovalForPool()
setOperatorApprovalForPool(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:1873
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:1879
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:1881
Set the signer's max leverage for one perp pool (caps position size vs margin).
Parameters
params
Returns
Promise<TxResult>
pokeFunding()
pokeFunding(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:1883
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:1888
Place a spot stop-loss / take-profit pending order on a SpotStopOrderRegistry (funds the trigger via SOMI msg.value).
Parameters
params
Returns
Promise<PlaceStopOrderResult>
cancelStopOrder()
cancelStopOrder(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:1890
Cancel a pending stop order on its registry.
Parameters
params
Returns
Promise<TxResult>
placePerpStopOrder()
placePerpStopOrder(
params):Promise<PlacePerpStopOrderResult>
Defined in: packages/sdk/src/trade.ts:1901
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
Returns
Promise<PlacePerpStopOrderResult>
linkPerpStopOrders()
linkPerpStopOrders(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:1906
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
Returns
Promise<TxResult>
cancelPerpStopOrder()
cancelPerpStopOrder(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:1911
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
Returns
Promise<TxResult>
cancelPerpStopOrders()
cancelPerpStopOrders(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:1913
Cancel several of the signer's pending perp stops in one tx, one refund transfer.
Parameters
params
Returns
Promise<TxResult>
claimPerpStopSomi()
claimPerpStopSomi(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:1918
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
Returns
Promise<TxResult>
buildPlacePerpStopOrder()
buildPlacePerpStopOrder(
params):Promise<UnsignedPerpStopOrder>
Defined in: packages/sdk/src/trade.ts:1938
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
Returns
Promise<UnsignedPerpStopOrder>
buildCancelPerpStopOrder()
buildCancelPerpStopOrder(
params):UnsignedCall
Defined in: packages/sdk/src/trade.ts:1940
Build cancelPerpStopOrder without sending it.
Parameters
params
Returns
buildCancelPerpStopOrders()
buildCancelPerpStopOrders(
params):UnsignedCall
Defined in: packages/sdk/src/trade.ts:1942
Build cancelPerpStopOrders without sending it.
Parameters
params
Returns
buildDepositMargin()
buildDepositMargin(
params):Promise<UnsignedMarginDeposit>
Defined in: packages/sdk/src/trade.ts:1947
Build depositMargin without sending it — the deposit call plus, unless
autoApprove: false, the ERC-20 approval the bank needs first.
Parameters
params
Returns
Promise<UnsignedMarginDeposit>
buildWithdrawMargin()
buildWithdrawMargin(
params):Promise<UnsignedCall>
Defined in: packages/sdk/src/trade.ts:1949
Build withdrawMargin without sending it. Nothing to approve.
Parameters
params
Returns
Promise<UnsignedCall>
mintSet()
mintSet(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:1952
Mint a YES+NO set: deposit collateral, receive equal YES + NO.
Parameters
params
Returns
Promise<TxResult>
burnSet()
burnSet(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:1954
Burn a YES+NO set: surrender both halves, receive collateral back.
Parameters
params
Returns
Promise<TxResult>
redeem()
redeem(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:1961
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
Returns
Promise<TxResult>
signRedeemAuth()
signRedeemAuth(
params):Promise<RedeemAuthorization>
Defined in: packages/sdk/src/trade.ts:1969
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
Returns
Promise<RedeemAuthorization>
redeemFor()
redeemFor(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:1975
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
Returns
Promise<TxResult>
redeemMany()
redeemMany(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:1977
Claim winnings from many settled markets in one transaction (batch redeem).
Parameters
params
Returns
Promise<TxResult>
redeemDirect()
redeemDirect(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:1982
Low-level direct redemption against the BinarySettlement singleton (bypasses
the module; no operator attribution). Takes the raw ERC-6909 outcomeId.
Parameters
params
Returns
Promise<TxResult>
claimOwed()
claimOwed(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:1984
Claim an accrued push-fallback (owed) balance on the settlement singleton.
Parameters
params
Returns
Promise<TxResult>
pokeOracle()
pokeOracle(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:2006
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
Returns
Promise<TxResult>
voidExpired()
voidExpired(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:2032
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
Returns
Promise<TxResult>
finalizeMarket()
finalizeMarket(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:2037
Permissionless keeper: finalize a settled market (sweep its pool's backing + resolution snapshot to the settlement singleton). No-op-guarded on repeat.
Parameters
params
Returns
Promise<TxResult>
syncSettlement()
syncSettlement(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:2043
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
Returns
Promise<TxResult>
releasePool()
releasePool(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:2048
Permissionless keeper: release a finalized, drained pool back to its creator's free list for recycle onto the next market.
Parameters
params
Returns
Promise<TxResult>
getSettlement()
getSettlement(
marketId,opts?):Promise<SettlementRecord|null>
Defined in: packages/sdk/src/trade.ts:2054
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:2056
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:2058
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:2063
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
Returns
Promise<TxResult>
mintSetPermit2()
mintSetPermit2(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:2068
Mint a complete YES+NO set pulling collateral via a Permit2 signature through
the CollateralRouter (no prior ERC-20 approve).
Parameters
params
Returns
Promise<TxResult>
redeemNative()
redeemNative(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:2073
Redeem winning outcome tokens for a NATIVE payout via the CollateralRouter (unwraps wNative → native). Approve the router for the winning outcome first.
Parameters
params
Returns
Promise<TxResult>
faucet()
faucet(
params?):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:2075
Mint TestUSDC from the faucet to the signer.
Parameters
params?
Returns
Promise<TxResult>
resolve()
resolve(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:2077
Resolve a market via the FakeOracle (demo resolver).
Parameters
params
Returns
Promise<TxResult>
voidMarket()
voidMarket(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:2079
Void a market via the FakeOracle (demo resolver).
Parameters
params
Returns
Promise<TxResult>
poke()
poke(
params):Promise<TxResult>
Defined in: packages/sdk/src/trade.ts:2081
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:2087
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