TypeScript SDK

npm install @kairos.trade/sdk

npm · GitHub · No runtime dependencies · Browsers and Node 20+

Create a client

import { createKairos } from '@kairos.trade/sdk'

const kairos = createKairos({
  wallet: {
    baseUrl: 'https://<your base url>',
    partnerId: '<your partner id>',   // or apiKey: { clientId, apiKey, apiSecret } on a server
    provider: window.ethereum,        // any EIP-1193 provider
    onStep: (step) => showPrompt(step.description),
  },
})

Option	Default	Means
`baseUrl`	—	Your Kairos base URL
`partnerId`	—	Sent as `X-Kairos-Partner-Id`. Pass this or `apiKey`
`apiKey`	—	`{ clientId, apiKey, apiSecret }`, sent as the three API-key headers. Server-side only
`provider`	—	The wallet: anything with `request({ method, params })`, such as `window.ethereum`, a WalletConnect provider, or a viem or ethers adapter
`onStep`	—	Called before each wallet prompt with the step, so you can show `description`
`onLogin`	—	Called with `(wallet, credentials)` after each sign-in, so you can keep the token
`pollIntervalMs`	`2000`	How often to check work that is still running
`timeoutMs`	15 minutes	How long to wait for an action, plan, intent or settlement
`signal`	—	An `AbortSignal` that cancels every call. Each call also takes its own `{ signal }`
`fetch`	global `fetch`	Your own fetch, for proxies or tests. Pass it to `createKairos({ fetch })`, not inside `wallet`

The SDK sends X-Kairos-Wallet-Api: 2, switches the wallet to each step’s chain (adding Polygon, BNB Chain or Arbitrum when the wallet doesn’t know it), and waits until held orders’ holdUntilMs. It shows one wallet prompt at a time per provider, so a concurrent call can’t switch the chain before a signature. Reads that hit a network error, 408, 429, 502, 503 or 504 are retried until timeoutMs; a lost reply after signing is read back rather than signed twice.

Trading

Method	Returns
`wallet.setup(wallet, { venues? })`	`SetupResult`: `ready`, `tradingWallet`, and `venues.{venue}` with `ready`, `next`, `tradingWallet`
`wallet.status(wallet)`	`WalletStatus`: `ready`, `next`, and per venue `balance`, `currency`, `tradingWallet`, `venueDetail`, `asOf`
`wallet.order(wallet, order)`	`OrderResult`: `orderId`, `status`, `filledSize`, `filledNotional`, `avgPrice`, `final`, `success`, `message`, `venue`, `market`
`wallet.cancel(wallet, orderIds)`	`CancelResult`: `cancelled`, `alreadyClosed`, `failed`
`wallet.cancelAll(wallet)`	`CancelResult`
`wallet.run(wallet, action)`	Any action’s `result`, for actions without a helper
`wallet.getAction(id)`	The current `Step`

order takes market (a market object from kairos.markets, or venue:market_id), outcome, side, price, size, and optionally timeInForce, postOnly, clientOrderId and expiresAt (unix seconds, GTD only). See venues for each venue’s rules.

Reading

Method	Returns
`wallet.orders(wallet, { open?, limit?, venue? })`	`WalletOrder[]`
`wallet.ordersPage(wallet, { open?, limit?, venue? })`	`{ orders, venueDetail? }`: `venueDetail` names any venue that couldn’t be read
`wallet.positions(wallet, { venue? })`	`{ positions, resolved, closed, asOf }`
`wallet.positionsPage(wallet, { venue? })`	`{ positions: { … }, venueDetail? }`
`wallet.login(wallet)`	`{ token, expiresAt }`. With a partner id, called for you on the first read and again on a `401`
`wallet.useCredentials(wallet, credentials)`	Reuse a token you kept from `onLogin`

Fees (preview)

Method	Does
`wallet.fees.summary(wallet)`	What the wallet owes per venue: `owedRaw` (negative is a credit), `thresholdRaw`, `decimals`, any open `settlement`
`wallet.fees.settle(wallet, venue)`	Opens a settlement, has the wallet sign (Polymarket) or send (Predict.fun) the payment, answers, and waits until it’s `confirmed`, `failed` or `expired`. Refuses anything but one transfer of the owed amount, in the venue’s collateral, on its chain
`wallet.fees.settleAll(wallet)`	`settle` for every venue that owes anything
`wallet.fees.createSettlement(wallet, venue)`, `answerSettlement(id, answer)`, `getSettlement(id, wallet)`, `wait(id, wallet)`	The same steps one at a time

See fees.

Trade plans (preview)

Method	Does
`wallet.tradePlans.run(input, { maxDebitRaw?, idempotencyKey?, onSign? })`	Prepares, checks, signs, executes and waits. Returns the final plan
`wallet.tradePlans.prepare(input, { idempotencyKey? })`	Prepares a plan
`wallet.tradePlans.answer(id, wallet, planHash, answers)`	Sends signatures
`wallet.tradePlans.execute(id, wallet, planHash, answers?)`	Executes
`wallet.tradePlans.report(id, wallet, planHash, reports)`	Reports client-submitted funding
`wallet.tradePlans.get(id, wallet)`, `wait(id, wallet)`	Reads, or waits until final

Before anything is signed, run recomputes the plan hash and rebuilds every signing request, checks the venue order and any Relay funding permit the wallet will sign, and throws SafetyCheckError if the wallet, market, side, price, size, deadlines, funding or budget differ, or if maxDebitRaw is exceeded. It accepts only the server’s documented rewrites: the outcome’s canonical name (on Hyperliquid, its #<digits> coin), and Predict.fun’s session-bound GTD. run supports only Kairos-submitted funding; for client-submitted funding use prepare, answer and report. run fills in clientOrderId, the Idempotency-Key, and a tradeSubmitBefore 4 minutes out. Pass your own idempotencyKey to resume the same plan after a crash. See trade plans.

On-chain intents (preview)

Method	Does
`wallet.onchain.split(wallet, market, amountRaw)`	pUSD into one share of each outcome
`wallet.onchain.merge(wallet, market, amountRaw)`	A full set back into pUSD
`wallet.onchain.redeem(wallet, market, amountRaw, { outcome })`	Winning shares of a resolved market into pUSD
`wallet.onchain.prepare(input)`, `execute(id, wallet, input)`, `report(id, wallet, input)`, `get(id, wallet)`, `wait(id, wallet)`	The same steps one at a time

Amounts are base units (6 decimals). The SDK looks up the trading wallet, sends lowercase addresses, and throws SafetyCheckError before signing if the intent doesn’t move what you asked: it recomputes the intent hash, rebuilds both signing requests, and accepts only the approval and the split, merge or redeem call on Polymarket’s own contracts. See split, merge and redeem.

Errors

Error	When	Look at
`ActionFailedError`	An action ended `failed`	`errorCode` (codes), `message`, `step`
`ActionFailedError` with `outcomeUnknown`	`ORDER_OUTCOME_UNKNOWN` or `CANCEL_OUTCOME_UNKNOWN`: it may have happened	Check `orders(wallet, { open: true })`, or retry with the same `clientOrderId`
`KairosError`	The server refused a request	`status`, `code`, `message`, `body`
`KairosError` with `outcomeUnknown`	A `500`, `502`, `504` or `408`: the request may have taken effect	Same as above
`FeeSettlementRequiredError`	A trade plan was refused until the wallet pays its fees	`assetKey`, `owedRaw`, `thresholdRaw`. Call `fees.settle`
`SafetyCheckError`	A prepared plan, intent or fee settlement isn’t what you asked for. Nothing was signed	`message`, `prepared`
`WaitTimeoutError`	`timeoutMs` passed while a plan, intent or settlement was still running. It may still finish. An order or cancel that runs past `timeoutMs` throws `ActionFailedError` with `outcomeUnknown` instead	`last`: the last state read

try {
  await kairos.wallet.order(wallet, order)
} catch (e) {
  if (e.outcomeUnknown) return reconcile(wallet, order.clientOrderId)
  if (e.errorCode === 'NO_MATCH') return showNoLiquidity()
  throw e
}

Get started

Onboard users

Trade

Route and fund

Partner fees

Build

Endpoints

TypeScript SDK

Create a client

Trading

Reading

Fees (preview)

Trade plans (preview)

On-chain intents (preview)

Errors

​Create a client

​Trading

​Reading

​Fees (preview)

​Trade plans (preview)

​On-chain intents (preview)

​Errors

Create a client

Trading

Reading

Fees (preview)

Trade plans (preview)

On-chain intents (preview)

Errors