Read a wallet's readiness and balances per venue
Returns whether the wallet is ready to trade on each venue, what to do next, and the venue balance. Needs only the partner id or API key — no wallet sign-in — because it reports on-chain state and readiness, not orders.
next tells the app what to do: setup (run a setup action), wait (approvals are confirming), fund (deposit collateral, or gas on Predict.fun), blocked (Hyperliquid cannot enroll this account; see venueDetail.reason), or null. The top-level next picks the most urgent across not-ready venues (setup > wait > fund > blocked); when every venue is ready it is fund if no ready venue reports a non-zero balance — including when a balance is unknown (null).
Venues not offered on the deployment are omitted. A venue whose read failed appears as {"ready": false, "available": false, "error": …} and is left out of the top-level ready and next. Readings may be up to 30 s old (asOf); a setup action refreshes them.
curl --request GET \
--url https://execution.kairos.trade/v3/wallets/{address} \
--header 'X-Kairos-Partner-Id: <api-key>' \
--header 'X-Kairos-Wallet-Api: <x-kairos-wallet-api>'import requests
url = "https://execution.kairos.trade/v3/wallets/{address}"
headers = {
"X-Kairos-Wallet-Api": "<x-kairos-wallet-api>",
"X-Kairos-Partner-Id": "<api-key>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {
'X-Kairos-Wallet-Api': '<x-kairos-wallet-api>',
'X-Kairos-Partner-Id': '<api-key>'
}
};
fetch('https://execution.kairos.trade/v3/wallets/{address}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://execution.kairos.trade/v3/wallets/{address}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-Kairos-Partner-Id: <api-key>",
"X-Kairos-Wallet-Api: <x-kairos-wallet-api>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://execution.kairos.trade/v3/wallets/{address}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-Kairos-Wallet-Api", "<x-kairos-wallet-api>")
req.Header.Add("X-Kairos-Partner-Id", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://execution.kairos.trade/v3/wallets/{address}")
.header("X-Kairos-Wallet-Api", "<x-kairos-wallet-api>")
.header("X-Kairos-Partner-Id", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://execution.kairos.trade/v3/wallets/{address}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-Kairos-Wallet-Api"] = '<x-kairos-wallet-api>'
request["X-Kairos-Partner-Id"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"wallet": "0x8ba1f109551bd432803012645ac136ddd64dba72",
"ready": false,
"next": "fund",
"venues": {
"polymarket": {
"ready": true,
"next": null,
"tradingWallet": "0x2f9c4b8e1d7a6c5b4a3f2e1d0c9b8a7f6e5d4c3b",
"balance": "25",
"currency": "pUSD",
"venueDetail": {
"chainId": "0x89"
},
"asOf": "2026-10-28T12:00:00.125Z"
},
"predictfun": {
"ready": false,
"next": "fund",
"tradingWallet": "0x8ba1f109551bd432803012645ac136ddd64dba72",
"balance": "0",
"currency": "USDT",
"venueDetail": {
"chainId": "0x38",
"gasBalance": "0",
"missingApprovals": 3,
"sessionExpiresAt": null
},
"asOf": "2026-10-28T12:00:00.140Z"
},
"hyperliquid": {
"ready": true,
"next": "fund",
"tradingWallet": "0x8ba1f109551bd432803012645ac136ddd64dba72",
"balance": "0",
"currency": "USDC",
"venueDetail": {
"chainId": "0xa4b1",
"network": "Mainnet",
"transferFromPerps": {
"available": "12.5",
"note": "your next order asks you to move what it needs from perps to spot"
}
},
"asOf": "2026-10-28T12:00:00.180Z"
}
},
"tradingWallet": "0x2f9c4b8e1d7a6c5b4a3f2e1d0c9b8a7f6e5d4c3b",
"balance": "25"
}{
"error": "unknown or expired action"
}{
"error": "send X-Kairos-Partner-Id or your API key (X-Client-Id, X-Api-Key, X-Api-Secret)"
}{
"error": "unknown partner id"
}{
"error": "rate limit exceeded for this endpoint; retry later"
}{
"error": "internal error"
}{
"error": "unknown or expired action"
}{
"error": "unknown or expired action"
}{
"error": "unknown or expired action"
}Authorizations
Wallet API partner id, issued by Kairos together with the partner's base URL. Identifies the partner (tenant) on every /v3 call; sent instead of an API key. Letters, digits and ._:-, at most 64 characters, case-insensitive. A partner id issued for an individual account cannot be sent this way — that account sends its API key triple instead.
Headers
Wallet API contract version. Send 2 — the multi-venue contract this reference documents. Without the header (or with any other value) /v3/actions and /v3/wallets/* serve the original Polymarket-only contract, which ignores venue prefixes, expiresAt and setup.venues, omits chainId, venue and fallbackRequests from steps, refuses orders on a wallet that is not set up (409), and returns snake_case order and position rows.
2 Path Parameters
The wallet's EVM address (0x + 40 hex; checksum not required).
^0x[0-9a-fA-F]{40}$Response
Readiness and balances per venue.
Response of GET /v3/wallets/{address}.
EVM address, 0x + 40 hex.
^0x[0-9a-fA-F]{40}$"0x8ba1f109551bd432803012645ac136ddd64dba72"
Every venue that could be read is ready, and at least one could be read.
The most urgent next step across venues.
setup, wait, fund, blocked, null Readiness per venue offered on this deployment.
Show child attributes
Show child attributes
Polymarket's trading wallet, when Polymarket is offered.
Polymarket's balance, when Polymarket is offered.
Was this page helpful?
curl --request GET \
--url https://execution.kairos.trade/v3/wallets/{address} \
--header 'X-Kairos-Partner-Id: <api-key>' \
--header 'X-Kairos-Wallet-Api: <x-kairos-wallet-api>'import requests
url = "https://execution.kairos.trade/v3/wallets/{address}"
headers = {
"X-Kairos-Wallet-Api": "<x-kairos-wallet-api>",
"X-Kairos-Partner-Id": "<api-key>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {
'X-Kairos-Wallet-Api': '<x-kairos-wallet-api>',
'X-Kairos-Partner-Id': '<api-key>'
}
};
fetch('https://execution.kairos.trade/v3/wallets/{address}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://execution.kairos.trade/v3/wallets/{address}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-Kairos-Partner-Id: <api-key>",
"X-Kairos-Wallet-Api: <x-kairos-wallet-api>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://execution.kairos.trade/v3/wallets/{address}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-Kairos-Wallet-Api", "<x-kairos-wallet-api>")
req.Header.Add("X-Kairos-Partner-Id", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://execution.kairos.trade/v3/wallets/{address}")
.header("X-Kairos-Wallet-Api", "<x-kairos-wallet-api>")
.header("X-Kairos-Partner-Id", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://execution.kairos.trade/v3/wallets/{address}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-Kairos-Wallet-Api"] = '<x-kairos-wallet-api>'
request["X-Kairos-Partner-Id"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"wallet": "0x8ba1f109551bd432803012645ac136ddd64dba72",
"ready": false,
"next": "fund",
"venues": {
"polymarket": {
"ready": true,
"next": null,
"tradingWallet": "0x2f9c4b8e1d7a6c5b4a3f2e1d0c9b8a7f6e5d4c3b",
"balance": "25",
"currency": "pUSD",
"venueDetail": {
"chainId": "0x89"
},
"asOf": "2026-10-28T12:00:00.125Z"
},
"predictfun": {
"ready": false,
"next": "fund",
"tradingWallet": "0x8ba1f109551bd432803012645ac136ddd64dba72",
"balance": "0",
"currency": "USDT",
"venueDetail": {
"chainId": "0x38",
"gasBalance": "0",
"missingApprovals": 3,
"sessionExpiresAt": null
},
"asOf": "2026-10-28T12:00:00.140Z"
},
"hyperliquid": {
"ready": true,
"next": "fund",
"tradingWallet": "0x8ba1f109551bd432803012645ac136ddd64dba72",
"balance": "0",
"currency": "USDC",
"venueDetail": {
"chainId": "0xa4b1",
"network": "Mainnet",
"transferFromPerps": {
"available": "12.5",
"note": "your next order asks you to move what it needs from perps to spot"
}
},
"asOf": "2026-10-28T12:00:00.180Z"
}
},
"tradingWallet": "0x2f9c4b8e1d7a6c5b4a3f2e1d0c9b8a7f6e5d4c3b",
"balance": "25"
}{
"error": "unknown or expired action"
}{
"error": "send X-Kairos-Partner-Id or your API key (X-Client-Id, X-Api-Key, X-Api-Secret)"
}{
"error": "unknown partner id"
}{
"error": "rate limit exceeded for this endpoint; retry later"
}{
"error": "internal error"
}{
"error": "unknown or expired action"
}{
"error": "unknown or expired action"
}{
"error": "unknown or expired action"
}