> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kairos.trade/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> Every method, option and error of the wallet client in @kairos.trade/sdk.

```bash theme={null}
npm install @kairos.trade/sdk
```

[npm](https://www.npmjs.com/package/@kairos.trade/sdk) · [GitHub](https://github.com/kairoslive/kairos-sdk) · No runtime dependencies · Browsers and Node 20+

## Create a client

```js theme={null}
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](https://docs.kairos.trade/wallets/venues.md) 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](https://docs.kairos.trade/wallets/fees.md).

## 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](https://docs.kairos.trade/wallets/trade-plans.md).

## 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](https://docs.kairos.trade/wallets/onchain.md).

## Errors

| Error | When | Look at |
| - | - | - |
| `ActionFailedError` | An action ended `failed` | `errorCode` ([codes](https://docs.kairos.trade/wallets/reference.md#error-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 |

```js theme={null}
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
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.