@somnia-chain/markets-sdk / index / Trader
Interface: Trader
Defined in: trade.ts:917
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: trade.ts:935
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
cancelOrder()
cancelOrder(
params):Promise<TxResult>
Defined in: trade.ts:937
Cancel a resting order on its pool (works for spot + binary).
Parameters
params
Returns
Promise<TxResult>
reduceOrder()
reduceOrder(
params):Promise<TxResult>
Defined in: trade.ts:943
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: trade.ts:949
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: trade.ts:954
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: trade.ts:960
Opt a routing/builder frontend in on a BinaryPool 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.
Parameters
params
Returns
Promise<TxResult>
getBuilderApproval()
getBuilderApproval(
pool,user,builder):Promise<bigint>
Defined in: trade.ts:962
Read a trader's per-builder approval cap on a BinaryPool (pool bps×1000; 0 = none).
Parameters
pool
`0x${string}`
user
`0x${string}`
builder
`0x${string}`
Returns
Promise<bigint>
getEffectiveBuilderApproval()
getEffectiveBuilderApproval(
pool,user,builder):Promise<bigint>
Defined in: trade.ts:968
Effective builder approval on a BinaryPool: the trader's raw cap clamped by the
pool's protocol-wide getMaxBuilderFeeBpsTimes1k ceiling — the actual enforced
limit a builderFeeBpsTimes1k on Trader.placeOrder must not exceed.
Parameters
pool
`0x${string}`
user
`0x${string}`
builder
`0x${string}`
Returns
Promise<bigint>
getMaxBuilderFeeBpsTimes1k()
getMaxBuilderFeeBpsTimes1k(
pool):Promise<bigint>
Defined in: trade.ts:970
Read a BinaryPool's protocol-wide builder-fee ceiling (bps×1000).
Parameters
pool
`0x${string}`
Returns
Promise<bigint>
placeSpotOrder()
placeSpotOrder(
params):Promise<PlaceOrderResult>
Defined in: trade.ts:975
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>
placePerpOrder()
placePerpOrder(
params):Promise<PlaceOrderResult>
Defined in: trade.ts:980
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>
depositMargin()
depositMargin(
params):Promise<TxResult>
Defined in: trade.ts:985
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: trade.ts:987
Withdraw free collateral from the MarginBank (margin-checked on-chain).
Parameters
params
Returns
Promise<TxResult>
withdrawVault()
withdrawVault(
params):Promise<TxResult>
Defined in: trade.ts:993
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).
Parameters
params
Returns
Promise<TxResult>
setPerpLeverage()
setPerpLeverage(
params):Promise<TxResult>
Defined in: trade.ts:995
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: trade.ts:997
Permissionlessly poke a perp pool's funding settlement (updateFunding).
Parameters
params
pool
`0x${string}`
gas?
bigint
Returns
Promise<TxResult>
placeSpotStopOrder()
placeSpotStopOrder(
params):Promise<TxResult>
Defined in: trade.ts:1002
Place a spot stop-loss / take-profit pending order on a SpotStopOrderRegistry (funds the trigger via SOMI msg.value).
Parameters
params
Returns
Promise<TxResult>
cancelStopOrder()
cancelStopOrder(
params):Promise<TxResult>
Defined in: trade.ts:1004
Cancel a pending stop order on its registry.
Parameters
params
Returns
Promise<TxResult>
mintSet()
mintSet(
params):Promise<TxResult>
Defined in: trade.ts:1006
Mint a YES+NO set: deposit collateral, receive equal YES + NO.
Parameters
params
Returns
Promise<TxResult>
burnSet()
burnSet(
params):Promise<TxResult>
Defined in: trade.ts:1008
Burn a YES+NO set: surrender both halves, receive collateral back.
Parameters
params
Returns
Promise<TxResult>
redeem()
redeem(
params):Promise<TxResult>
Defined in: trade.ts:1015
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: trade.ts:1023
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: trade.ts:1029
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: trade.ts:1031
Claim winnings from many settled markets in one transaction (batch redeem).
Parameters
params
Returns
Promise<TxResult>
redeemDirect()
redeemDirect(
params):Promise<TxResult>
Defined in: trade.ts:1036
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: trade.ts:1038
Claim an accrued push-fallback (owed) balance on the settlement singleton.
Parameters
params
Returns
Promise<TxResult>
finalizeMarket()
finalizeMarket(
params):Promise<TxResult>
Defined in: trade.ts:1043
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: trade.ts:1049
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: trade.ts:1054
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: trade.ts:1060
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: trade.ts:1062
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: trade.ts:1064
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: trade.ts:1069
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: trade.ts:1074
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: trade.ts:1079
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: trade.ts:1081
Mint TestUSDC from the faucet to the signer.
Parameters
params?
Returns
Promise<TxResult>
resolve()
resolve(
params):Promise<TxResult>
Defined in: trade.ts:1083
Resolve a market via the FakeOracle (demo resolver).
Parameters
params
Returns
Promise<TxResult>
voidMarket()
voidMarket(
params):Promise<TxResult>
Defined in: trade.ts:1085
Void a market via the FakeOracle (demo resolver).
Parameters
params
Returns
Promise<TxResult>
poke()
poke(
params):Promise<TxResult>
Defined in: trade.ts:1087
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: trade.ts:1093
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