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

# Set up and fund a wallet

> Get a user's wallet ready on each venue: the one-time setup signatures, where to send funds, and how to read readiness.

Before a wallet can trade on a venue, it needs that venue's one-time setup and some collateral there. Setup is per venue and per wallet, needs no Kairos account, and is skipped wherever it's already done.

You can also skip this page: an [order](https://docs.kairos.trade/wallets/trade.md) on a venue the wallet isn't set up on runs the missing setup steps first, in the same call. Running setup up front gives the user a clear "enable trading" moment and tells you where they still need funds.

## 1. Run setup

One setup covers every venue. It skips whatever is already done, so calling it again on a ready wallet asks for nothing.

```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":"setup"}}'
# Answer each step with the wallet's signature (or, for Predict.fun approvals,
# {"result": <what wallet_sendCalls returned>}) until status is "done":
# {"status":"done","result":{"ready":true,"tradingWallet":"0x…","venues":{"polymarket":{"ready":true,…},…}}}
```

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

setup = run({"type": "setup"})                          # every venue
setup = run({"type": "setup", "venues": ["predictfun"]})  # or just some
```

```js JavaScript (SDK) theme={null}
const setup = await kairos.wallet.setup(wallet)
// { ready: true, tradingWallet: '0x…', venues: { polymarket: { ready: true, … }, predictfun: { ready: true, … } } }
```

| Venue | What the wallet is asked for |
| - | - |
| Polymarket | One or two signatures, no gas. Setup creates a **trading wallet**: a smart wallet owned by the user's address. Their key controls it. Kairos never does. |
| Predict.fun | One batch of approvals on BNB Chain, sent by the wallet itself (one confirmation, the user pays BNB gas once), then one sign-in signature. |
| Hyperliquid | One `approveAgent` signature (plus a builder-fee approval where a builder fee is configured), no gas. The agent Kairos holds can only place and cancel trades: Hyperliquid agents cannot withdraw or transfer, and the user can revoke it on Hyperliquid at any time. |

Each venue asks for its own signature because each venue defines its own login, and approvals live on each venue's chain. If the wallet has no BNB for the Predict.fun approvals, or has never deposited to Hyperliquid (which refuses every action from an unfunded account), setup asks for nothing there and that venue reports `next: "fund"`.

Pass `{ venues: ['predictfun'] }` to set up only some venues.

## 2. Fund the wallet

| Venue | Send |
| - | - |
| Polymarket | **pUSD on Polygon** to `venues.polymarket.tradingWallet` (also `setup.tradingWallet`) |
| Predict.fun | **USDT on BNB Chain** to the wallet itself, plus a little BNB for the one-time approvals |
| Hyperliquid | **USDC** deposited to the wallet's Hyperliquid account (spot). USDC already in the wallet's Hyperliquid perps account works too: when spot is short, the order asks for one extra signature that moves just what it needs from the wallet's own perps to its own spot (status shows this as `venueDetail.transferFromPerps`) |

Use your wallet's normal send flow. Check readiness at any time:

```bash HTTP theme={null}
curl "$BASE/v3/wallets/$WALLET" -H "X-Kairos-Partner-Id: $PARTNER" -H "X-Kairos-Wallet-Api: 2"
# {"ready":true,"next":null,"venues":{"polymarket":{"ready":true,"balance":"25","currency":"pUSD",…},…}}
```

```python Python theme={null}
from kairos_wallet import api, WALLET

status = api("GET", f"/v3/wallets/{WALLET}")
print(status["next"], {v: (s["ready"], s["balance"]) for v, s in status["venues"].items()})
```

```js JavaScript (SDK) theme={null}
await kairos.wallet.status(wallet)
// { ready: true, next: null, venues: { polymarket: { ready: true, balance: '25', currency: 'pUSD', … }, predictfun: { … } } }
```

`next` is `"setup"`, `"wait"` (approvals the wallet already sent are still confirming; nothing to sign, check again shortly), `"fund"`, `"blocked"` (that venue account cannot be used here, for example a Hyperliquid portfolio-margin account; `venueDetail.reason` says why), or `null` when the wallet can trade. `ready: true` with `next: "fund"` means setup is done everywhere but there are no funds yet. Balances are in whole units of each venue's `currency`.

## 3. Read readiness

Wallet status is public and needs no signature. Poll it to drive your UI:

| `next` | Show the user |
| - | - |
| `"setup"` | An "enable trading" button that runs setup |
| `"wait"` | Approvals are confirming. Nothing to sign; check again in a few seconds |
| `"fund"` | Where to send funds, from the table above. For Predict.fun, `venueDetail.gasBalance` shows the BNB available for the approvals |
| `"blocked"` | This venue account can't be used here; `venueDetail.reason` says why |
| `null` | Ready to trade |

The top-level `next` is the first thing to do across all venues. Each venue in `venues` has its own `ready`, `next` and `balance`, so you can show readiness per venue. See [wallet status](https://docs.kairos.trade/wallets/reference.md#wallet-status) for every field, and [venue rules](https://docs.kairos.trade/wallets/venues.md) for what each venue asks for.

Over HTTP, setup is an action like any other: `POST /v3/actions` with `X-Kairos-Wallet-Api: 2` and `{ "wallet": "0x…", "action": { "type": "setup", "venues": ["polymarket"] } }`. Leave out `venues` to set up every venue. See [plain HTTP clients](https://docs.kairos.trade/wallets/http.md).


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