Reads
List a wallet's positions across venues
Returns open, resolved and closed positions across venues. Requires Authorization: SIWE <token> from a login action (or an API key whose Kairos account owns the wallet).
The body is nested: the rows are at positions.positions, with positions.resolved, positions.closed and positions.asOf beside them. When a venue cannot be read, venueDetail.<venue>.error says why.
GET
/
v3
/
wallets
/
{address}
/
positions
List a wallet's positions across venues
curl --request GET \
--url https://execution.kairos.trade/v3/wallets/{address}/positions \
--header 'Authorization: <api-key>' \
--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}/positions"
headers = {
"X-Kairos-Wallet-Api": "<x-kairos-wallet-api>",
"X-Kairos-Partner-Id": "<api-key>",
"Authorization": "<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>',
Authorization: '<api-key>'
}
};
fetch('https://execution.kairos.trade/v3/wallets/{address}/positions', 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}/positions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"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}/positions"
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>")
req.Header.Add("Authorization", "<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}/positions")
.header("X-Kairos-Wallet-Api", "<x-kairos-wallet-api>")
.header("X-Kairos-Partner-Id", "<api-key>")
.header("Authorization", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://execution.kairos.trade/v3/wallets/{address}/positions")
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>'
request["Authorization"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"positions": {
"positions": [
{
"venue": "polymarket",
"market": "polymarket:0x5f3a8e1c2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a6c8e0b2d4f6a",
"marketId": "0x5f3a8e1c2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a6c8e0b2d4f6a",
"outcome": "Yes",
"tokenId": "71321045679252212594626385532706912750332728571942532289631379312455583992563",
"size": "4.5",
"availableToSell": "4.5",
"avgPrice": "0.52",
"realizedPnl": "0",
"holdingWallet": "0x2f9c4b8e1d7a6c5b4a3f2e1d0c9b8a7f6e5d4c3b",
"lastTradeAt": "2026-10-28T11:58:00Z"
}
],
"resolved": [],
"closed": [],
"asOf": "2026-10-28T12:00:00Z"
}
}{
"error": "unknown or expired action"
}{
"error": "sign-in token has expired; run a login action"
}{
"error": "unknown partner id"
}{
"error": "wallet not found"
}{
"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
walletPartnerId & walletSignInapiKeyClientId & apiKeyKey & apiKeySecret & walletSignInapiKeyClientId & apiKeyKey & apiKeySecretwalletPartnerId & apiKeyClientId & apiKeyKey & apiKeySecretwalletPartnerId & bearerAuth
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.
Wallet sign-in token: SIWE <token>, where <token> is result.token from a login action (exactly one space after SIWE). Proves the wallet on reads of its orders and positions, and on trade plans, fee settlements and on-chain intents. The token is bound to the partner and the environment that issued it and lasts 24 hours; run a new login action to renew it.
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.
Available options:
2 Path Parameters
The wallet's EVM address (0x + 40 hex; checksum not required).
Pattern:
^0x[0-9a-fA-F]{40}$Query Parameters
Read one venue only. Case-insensitive; predict.fun is accepted for predictfun. An unknown name is 400 unknown venue "<name>"; a venue not offered on this deployment returns an empty list.
Venue id. predict.fun is accepted as an input alias of predictfun.
Available options:
polymarket, predictfun, hyperliquid Was this page helpful?
⌘I
List a wallet's positions across venues
curl --request GET \
--url https://execution.kairos.trade/v3/wallets/{address}/positions \
--header 'Authorization: <api-key>' \
--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}/positions"
headers = {
"X-Kairos-Wallet-Api": "<x-kairos-wallet-api>",
"X-Kairos-Partner-Id": "<api-key>",
"Authorization": "<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>',
Authorization: '<api-key>'
}
};
fetch('https://execution.kairos.trade/v3/wallets/{address}/positions', 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}/positions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"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}/positions"
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>")
req.Header.Add("Authorization", "<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}/positions")
.header("X-Kairos-Wallet-Api", "<x-kairos-wallet-api>")
.header("X-Kairos-Partner-Id", "<api-key>")
.header("Authorization", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://execution.kairos.trade/v3/wallets/{address}/positions")
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>'
request["Authorization"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"positions": {
"positions": [
{
"venue": "polymarket",
"market": "polymarket:0x5f3a8e1c2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a6c8e0b2d4f6a",
"marketId": "0x5f3a8e1c2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a6c8e0b2d4f6a",
"outcome": "Yes",
"tokenId": "71321045679252212594626385532706912750332728571942532289631379312455583992563",
"size": "4.5",
"availableToSell": "4.5",
"avgPrice": "0.52",
"realizedPnl": "0",
"holdingWallet": "0x2f9c4b8e1d7a6c5b4a3f2e1d0c9b8a7f6e5d4c3b",
"lastTradeAt": "2026-10-28T11:58:00Z"
}
],
"resolved": [],
"closed": [],
"asOf": "2026-10-28T12:00:00Z"
}
}{
"error": "unknown or expired action"
}{
"error": "sign-in token has expired; run a login action"
}{
"error": "unknown partner id"
}{
"error": "wallet not found"
}{
"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"
}