Wallets

List My Wallets

List the user’s wallets in display order (MAIN, SANDBOX, API, COMPETITION).

Includes ACTIVE, FROZEN, and ARCHIVED so the UI can render generation history. DELETED wallets are hidden.

Per-user 5s Redis cache (override via ME_CACHE_TTL_S env). Wallet balance/baseline/status mutations on this user (top-up webhook, MAIN reset, archive, etc.) intentionally don’t bust this cache — the short TTL is the staleness contract. If you need fresh-immediate after a write, the writer hits the wallet directly via SQL.

GET

wallets

List My Wallets

curl --request GET \
  --url https://api.polysimulator.com/v1/me/wallets \
  --header 'X-API-Key: <api-key>'

{
  "wallets": [
    {
      "id": 123,
      "kind": "<string>",
      "label": "<string>",
      "balance": "<string>",
      "baseline": "<string>",
      "status": "<string>",
      "generation": 123,
      "parent_wallet_id": 123,
      "competition_id": 123,
      "created_at": "<string>",
      "archived_at": "<string>",
      "is_legacy": false,
      "managed_by": {
        "tenant_slug": "<string>",
        "display_name": "<string>"
      },
      "b2b_account": {
        "account_id": "<string>",
        "stage": "<string>",
        "status": "<string>"
      }
    }
  ]
}

Authorizations

X-API-Key

string

header

required

Issue from /v1/keys (or admin-issued for enterprise tier).

Headers

authorization

string | null

X-API-Key

string | null

POLY_API_KEY

string | null

Poly-API-Key

string | null

Response

Successful Response

wallets

WalletOut · object[]

required

Show child attributes

Create WalletCreate a new SANDBOX wallet, gated by per-plan caps. Rejects MAIN (auto-seeded), COMPETITION (runner-spawned), and currently API as well — extra API wallets need per-API-key routing to receive trades, which is a separate follow-up PR. The body of this handler still contains the API code path so flipping the rejection on becomes a one-line removal once routing lands.

List My Wallets

curl --request GET \
  --url https://api.polysimulator.com/v1/me/wallets \
  --header 'X-API-Key: <api-key>'

{
  "wallets": [
    {
      "id": 123,
      "kind": "<string>",
      "label": "<string>",
      "balance": "<string>",
      "baseline": "<string>",
      "status": "<string>",
      "generation": 123,
      "parent_wallet_id": 123,
      "competition_id": 123,
      "created_at": "<string>",
      "archived_at": "<string>",
      "is_legacy": false,
      "managed_by": {
        "tenant_slug": "<string>",
        "display_name": "<string>"
      },
      "b2b_account": {
        "account_id": "<string>",
        "stage": "<string>",
        "status": "<string>"
      }
    }
  ]
}