Set up and fund a wallet

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

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,…},…}}}

from kairos_wallet import run

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

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:

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",…},…}}

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()})

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 for every field, and venue rules 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.

Get started

Onboard users

Trade

Route and fund

Partner fees

Build

Endpoints

Set up and fund a wallet

1. Run setup

2. Fund the wallet

3. Read readiness

​1. Run setup

​2. Fund the wallet

​3. Read readiness

1. Run setup

2. Fund the wallet

3. Read readiness