> ## 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.

# Place and cancel orders

> Place an order on any venue, follow its fill, and cancel it.

Placing and cancelling work the same on every venue (Polymarket, Predict.fun and Hyperliquid outcome markets). Each is one wallet prompt.

> [!NOTE]
>
> Each step names the chain it needs (`chainId`). The SDK switches the wallet to it, and adds the chain if the wallet doesn't know it.

Set up the wallet first ([set up and fund a wallet](https://docs.kairos.trade/wallets/setup.md)), or let the order run any missing setup steps itself.

## Place an order

```bash HTTP theme={null}
curl -X POST "$BASE/v3/actions" -H "X-Kairos-Partner-Id: $PARTNER" -H "X-Kairos-Wallet-Api: 2" -H "Content-Type: application/json" \
  -d '{"wallet":"0xUSER","action":{"type":"order","market":"predictfun:1027194","outcome":"Yes",
       "side":"buy","price":"0.52","size":"10","clientOrderId":"my-order-1"}}'
# Sign the step's request, post {"signature":"0x…"} to /v3/actions/{id}, until "done":
# {"status":"done","result":{"orderId":"…","status":"filled","filledSize":"10","filledNotional":"5.2",
#   "avgPrice":"0.52","final":true,"success":true,"message":null,…}}
```

```python Python theme={null}
from kairos_wallet import run

order = run({
    "type": "order", "market": "predictfun:1027194", "outcome": "Yes",
    "side": "buy", "price": "0.52", "size": "10", "clientOrderId": "my-order-1",
})
print(order["orderId"], order["status"], order["filledSize"], order["final"])
```

```js JavaScript (SDK) theme={null}
const order = await kairos.wallet.order(wallet, {
  market,             // a market from kairos.markets.list, or 'predictfun:1027194'
  outcome: 'Yes',
  side: 'buy',
  price: '0.52',      // 0–1
  size: '10',         // shares
})
// { orderId: '…', status: 'filled', venueOrderId: '…', venue: 'polymarket', market: '…',
//   filledSize: '10', filledNotional: '5.2', avgPrice: '0.52', final: true, success: true, message: null }
```

`filledSize` and `filledNotional` are what matched, before fees. `final: true` means matching is finished: nothing more will fill and nothing rests. `success: false` means the order ended without doing anything, or its outcome isn't confirmed yet; `message` says which. A resting `GTC` order returns with `final: false`; follow it in [orders](https://docs.kairos.trade/wallets/portfolio.md). See [order fills](https://docs.kairos.trade/wallets/reference.md#order).

On some Polymarket sports markets the venue holds a taking order for a second or more before matching it. The call waits through the hold and returns the final fill. See [delayed markets](https://docs.kairos.trade/wallets/reference.md#delayed-markets).

The venue comes from the market. As a string, a market is `venue:market_id`; a bare `0x…` condition id is a Polymarket market. If the wallet isn't set up on that venue yet, the order runs the missing setup steps first, in the same call. If setup can't run there (no BNB for the approvals, a never-funded or blocked Hyperliquid account), the order fails with the reason.

Optional: `timeInForce` (`GTC` default, `GTD` with `expiresAt` in unix seconds, `FOK`, `FAK`, `IOC`), `postOnly: true`, and `clientOrderId`: your own id, so a retry returns the same order instead of placing a second one ([rules](https://docs.kairos.trade/wallets/reference.md#clientorderid)).

On Hyperliquid each order is one Kairos order signature (plus one perps-to-spot transfer when spot USDC is short); Kairos then places exactly that order with the trade-only agent. Use `GTC`, `FAK` or `IOC` there, with whole-share sizes, and a `clientOrderId` of `0x` plus 32 lowercase hex characters. See [venues](https://docs.kairos.trade/wallets/venues.md) for every venue's rules.

On Predict.fun a resting order lasts at most as long as the wallet's Predict.fun sign-in (about a day): a `GTC` order is placed as `GTD` ending 10 minutes before it. When less than an hour of the sign-in is left, the next order renews it with one signature.

## Cancel

```bash HTTP theme={null}
curl -X POST "$BASE/v3/actions" -H "X-Kairos-Partner-Id: $PARTNER" -H "X-Kairos-Wallet-Api: 2" -H "Content-Type: application/json" \
  -d '{"wallet":"0xUSER","action":{"type":"cancel","orderIds":["<orderId>"]}}'
# or "action": {"type":"cancel","all":true}. Sign the one CancelOrders step (chain 0x89):
# {"status":"done","result":{"cancelled":["<orderId>"],"alreadyClosed":[],"failed":[]}}
```

```python Python theme={null}
from kairos_wallet import run

run({"type": "cancel", "orderIds": [order["orderId"]]})
run({"type": "cancel", "all": True})
```

```js JavaScript (SDK) theme={null}
await kairos.wallet.cancel(wallet, [order.orderId])
await kairos.wallet.cancelAll(wallet)
```

One signature cancels across every venue. Every cancel is signed by the wallet, so only its owner can cancel. The cancel signature is on Polygon (`0x89`) whatever the venue, so the wallet may be asked to switch chains.

## Errors

A failed action throws `ActionFailedError`; its `step.errorCode` says why ([codes](https://docs.kairos.trade/wallets/reference.md#error-codes)). `NO_MATCH` (an immediate order found nothing at its price), `VENUE_REJECTED` and `SIGNATURE_EXPIRED` mean nothing was placed. A refused request throws `KairosError` with `status` and, where there is one, `code`.

The order may be live if the action fails with `ORDER_OUTCOME_UNKNOWN`, or the call throws with `error.outcomeUnknown` (a server error before an answer). Check `kairos.wallet.orders(wallet)` before placing it again (not only open orders: it may have filled), or retry with the same `clientOrderId`, which never places a second order.

> [!WARNING]
>
> **Known issue (Polymarket):** orders on some standard (non-neg-risk) markets fail with `the order signer address has to be the address of the API KEY`. This is a Polymarket-side limit on deposit-wallet orders, and nothing is placed. Neg-risk markets are not affected. We will update this page when Polymarket fixes it.

## Not using JavaScript?

Everything above is plain JSON over HTTPS. [Without the SDK](https://docs.kairos.trade/wallets/http.md) walks through the loop with curl and has a complete Python client; the [reference](https://docs.kairos.trade/wallets/reference.md) lists every field.

## Next

* [Show positions](https://docs.kairos.trade/wallets/portfolio.md) after a fill.
* [What the wallet signs](https://docs.kairos.trade/wallets/signing.md), step by step.
* [Reference](https://docs.kairos.trade/wallets/reference.md) for every field and error.


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