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

# Quickstart: your first order

> Set up a wallet, place an order, read it back and cancel it, in Python or JavaScript.

This places one order that rests on the book, then cancels it. It signs with a local test key, so you can see the whole loop before you wire up a real wallet. Pick Python (plain HTTP, no SDK) or JavaScript (the SDK).

You need:

* Your partner id and the staging base URL ([onboarding](https://docs.kairos.trade/wallets/onboarding.md)).
* A test wallet funded on one venue: for example USDC in its Hyperliquid account. See [funding](https://docs.kairos.trade/wallets/setup.md#2-fund-the-wallet).
* A market id from that venue, such as `hyperliquid:<digits>` or `polymarket:0x…`. Find one with [Show markets](https://docs.kairos.trade/wallets/markets.md).

> [!WARNING]
>
> Staging trades on the real venues with real funds. Use a test wallet and a price well away from the market.

## Run it

> [tab] Python
>
> Save the [Python client](https://docs.kairos.trade/wallets/http.md#a-complete-python-client) as `kairos_wallet.py`. It signs with a local key using `eth-account`; in an app, the user's wallet signs instead.
>
> ```bash theme={null}
> pip install requests eth-account
> ```
>
> ```python quickstart.py theme={null}
> import os, secrets
> from kairos_wallet import api, run, WALLET
>
> market = os.environ["MARKET"]  # for example "hyperliquid:<digits>"
> print(run({"type": "setup", "venues": [market.split(":")[0]]}))
>
> order = run({
>     "type": "order", "market": market, "outcome": "Yes", "side": "buy",
>     "price": "0.01", "size": "1000",  # far below the market, so it rests ($10 notional)
>     "timeInForce": "GTC", "postOnly": True,
>     "clientOrderId": "0x" + secrets.token_hex(16),
> })
> print("placed", order["orderId"], order["status"])
>
> token = run({"type": "login"})["token"]  # orders are private: sign in once
> auth = {"Authorization": f"SIWE {token}"}
> print("open", api("GET", f"/v3/wallets/{WALLET}/orders?open=true", headers=auth)["orders"])
>
> print("cancel", run({"type": "cancel", "orderIds": [order["orderId"]]}))
> ```
>
> ```bash theme={null}
> KAIROS_URL=https://staging-execution.kairos.trade KAIROS_PARTNER_ID=… PRIVATE_KEY=0x… \
>   MARKET=hyperliquid:… python quickstart.py
> ```

> [tab] JavaScript (SDK)
>
> `viem` signs with the test key; any EIP-1193 provider works the same way in an app (for example `window.ethereum`).
>
> ```bash theme={null}
> npm install @kairos.trade/sdk viem
> ```
>
> ```js quickstart.mjs theme={null}
> import { createKairos } from '@kairos.trade/sdk'
> import { privateKeyToAccount } from 'viem/accounts'
> import { randomBytes } from 'node:crypto'
>
> const account = privateKeyToAccount(process.env.TEST_PRIVATE_KEY)
>
> // A minimal EIP-1193 provider around a local key.
> let chainId = '0x89'
> const provider = {
>   async request({ method, params }) {
>     if (method === 'eth_chainId') return chainId
>     if (method === 'wallet_switchEthereumChain') { chainId = params[0].chainId; return null }
>     if (method === 'personal_sign') return account.signMessage({ message: { raw: params[0] } })
>     if (method === 'eth_signTypedData_v4') {
>       const { domain, types, primaryType, message } = JSON.parse(params[1])
>       const { EIP712Domain, ...rest } = types
>       return account.signTypedData({ domain, types: rest, primaryType, message })
>     }
>     throw Object.assign(new Error(`unsupported ${method}`), { code: 4200 })
>   },
> }
>
> const kairos = createKairos({
>   wallet: {
>     baseUrl: 'https://staging-execution.kairos.trade',
>     partnerId: process.env.KAIROS_PARTNER_ID,
>     provider,
>     onStep: (step) => console.log('sign:', step.description),
>   },
> })
>
> const wallet = account.address
> const market = process.env.MARKET // for example 'hyperliquid:<digits>'
>
> console.log(await kairos.wallet.setup(wallet, { venues: [market.split(':')[0]] }))
>
> const order = await kairos.wallet.order(wallet, {
>   market, outcome: 'Yes', side: 'buy',   // one of the market's outcome names
>   price: '0.01', size: '1000',            // far below the market, so it rests ($10 notional)
>   timeInForce: 'GTC', postOnly: true,
>   clientOrderId: '0x' + randomBytes(16).toString('hex'),
> })
> console.log('placed', order.orderId, order.status)
>
> console.log('open', await kairos.wallet.orders(wallet, { open: true }))
> console.log('cancel', await kairos.wallet.cancel(wallet, [order.orderId]))
> ```
>
> ```bash theme={null}
> TEST_PRIVATE_KEY=0x… KAIROS_PARTNER_ID=… MARKET=hyperliquid:… node quickstart.mjs
> ```

What you'll see:

1. **Setup** asks for the venue's one-time signatures (none on a wallet that is already set up).
2. **The order** asks for one signature, then returns with `status` and `final: false`, because it rests.
3. **Open orders** needs one sign-in signature first: orders are private. Keep the token for 24 hours (the SDK does this for you).
4. **The cancel** asks for one signature on Polygon (`0x89`), whatever the venue.

The `clientOrderId` above is in Hyperliquid's format (`0x` plus 32 hex), which every venue accepts. Hyperliquid buys must be worth at least 10 USDC; other venues have their own minimums ([venue rules](https://docs.kairos.trade/wallets/venues.md)).

## The same over HTTP

Every SDK call is a few JSON requests. Read a wallet's status with curl:

```bash theme={null}
curl "https://staging-execution.kairos.trade/v3/wallets/$WALLET" \
  -H "X-Kairos-Partner-Id: $KAIROS_PARTNER_ID" \
  -H "X-Kairos-Wallet-Api: 2"
```

[Plain HTTP clients](https://docs.kairos.trade/wallets/http.md) runs the whole loop with curl, and has complete JavaScript and Python clients.

## Next

* [Set up and fund a wallet](https://docs.kairos.trade/wallets/setup.md) for real users.
* [What the wallet signs](https://docs.kairos.trade/wallets/signing.md), so your UI can show each step.
* [Onboarding and go-live](https://docs.kairos.trade/wallets/onboarding.md) for the launch checklist.


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