SubaccountService

List Subaccounts

List sub-accounts owned by or shared with the caller, including role and label.

Method

GET

Path

/v1/auth/subaccounts

Visibility

Authentication required

Authentication

Session token or API key

MFA Requirement

Not required

GET

/v1/auth/subaccounts

Request

Testnet

curl --request GET \ \
  --url 'https://api.testnet.polyester.com/v1/auth/subaccounts' \
  --header 'Accept: */*' \
  --header 'X-API-KEY-ID: YOUR_API_KEY_ID' \
  --header 'X-API-TIMESTAMP: YOUR_API_TIMESTAMP' \
  --header 'X-API-SIGNATURE: YOUR_API_SIGNATURE'

Responses

{
  "subaccounts": [
    {
      "color": "#7C3AED",
      "icon": "💰",
      "id": "9eLaFXwP59",
      "label": "Market Making",
      "ownerAvatarUrl": "https://placehold.co/128x128.png",
      "ownerRootSmartAccountAddress": "0x2222222222222222222222222222222222222222",
      "ownerUsername": "trader_alpha",
      "removed": false,
      "requireMemberMfa": false,
      "revision": "1",
      "role": "VIEWER",
      "smartAccountAddress": "0x2222222222222222222222222222222222222222",
      "smartAccountSaltNonce": 1,
      "status": "ACTIVE",
      "subaccountPolicyId": "627BigpnRg",
      "updatedAt": "2025-01-01T00:00:00Z"
    }
  ],
  "totalCreated": 1
}

16 fields

id string (fixed64)

Sub-account identifier (opaque ID).

Example 9eLaFXwP59

role enum

Role of the current caller on this sub-account. SUBACCOUNT_ROLE_UNSPECIFIED when removed is true.

VIEWER TRADER LEVERAGED_TRADER TREASURY ADMIN OWNER

Example VIEWER

label string

Optional human-readable label for this sub-account.

Example Market Making

icon string

Optional user-chosen icon/emoji for UI display.

Example 💰

color string (color)

Optional user-chosen color token for UI display. Tokens use lowercase letters, numbers, underscores, or hyphens.

Example #7C3AED

status enum

Current public lifecycle status of the sub-account.

SUBACCOUNT_STATUS_ACTIVE SUBACCOUNT_STATUS_DISABLED

Example ACTIVE

smartAccountAddress string

Smart Account EVM address backing this sub-account.

Example 0x2222222222222222222222222222222222222222

ownerUsername string

Owner (root account) public username, if set. Useful for shared views.

Example trader_alpha

ownerAvatarUrl string

Owner (root account) avatar URL, if set.

Example https://placehold.co/128x128.png

ownerRootSmartAccountAddress string

Owner (root account) primary Smart Account address, when available. Allows clients to display a stable identity even when no username is set.

Example 0x2222222222222222222222222222222222222222

subaccountPolicyId string (fixed64)

Optional sub-account policy identifier (opaque ID). 0 means no explicit policy attached.

Example 627BigpnRg

requireMemberMfa boolean

Owner-controlled security baseline for delegated interactive members on protected sub-account actions. This does not apply to read-only real-time subscriptions.

Example false

smartAccountSaltNonce integer (int32)

Smart-account derivation salt nonce assigned when this sub-account was created. Present only when the caller owns the sub-account and can use it for direct chain signing.

Example 1

updatedAt string (date-time)

Time in UTC when this sub-account's configuration was last changed. For the same sub-account, later is fresher, equal is an idempotent replay, and earlier is stale. Equal timestamps with different configuration, other than role and removed, indicate an invariant failure.

Example 2025-01-01T00:00:00Z

revision string (uint64)

Monotonic resource revision used for conditional updates.

Example 1

removed boolean

True when the caller no longer has access to this sub-account, for example after its owner removed the caller as a member: remove the sub-account from the caller's list. Only real-time updates set it; responses list only sub-accounts the caller can access. A change of the caller's role or access does not change revision or updated_at, so real-time updates deliver such changes in order and each one applies as it arrives. Ending access also ends the caller's subscriptions to this sub-account's real-time channels, and can, rarely, also end a subscription made after access was granted again. When the server ends a subscription to one of this sub-account's channels while the latest update lists this sub-account with a role and removed false, subscribe again: access is checked again on subscribe.

Example false

totalCreated integer (int32)

Total number of sub-accounts that have ever been created for this root, including soft-deleted ones. Request CreateSubaccountChallenge to obtain the canonical next smart-account address and salt.

Example 1

Possible errors: 5

Key	HTTP status	Connect code	Error	When
unauthenticated	401	unauthenticated	Unauthenticated	Authentication required.
permission-denied	403	permission_denied	Permission Denied	Permission denied.
invalid-argument	400	invalid_argument	Invalid Argument	Invalid argument.
not-found	404	not_found	Not Found	Not found.
unavailable	503	unavailable	Unavailable	Service unavailable.

GET

/v1/auth/subaccounts

Request

Testnet

curl --request GET \ \
  --url 'https://api.testnet.polyester.com/v1/auth/subaccounts' \
  --header 'Accept: */*' \
  --header 'X-API-KEY-ID: YOUR_API_KEY_ID' \
  --header 'X-API-TIMESTAMP: YOUR_API_TIMESTAMP' \
  --header 'X-API-SIGNATURE: YOUR_API_SIGNATURE'

Responses

{
  "subaccounts": [
    {
      "color": "#7C3AED",
      "icon": "💰",
      "id": "9eLaFXwP59",
      "label": "Market Making",
      "ownerAvatarUrl": "https://placehold.co/128x128.png",
      "ownerRootSmartAccountAddress": "0x2222222222222222222222222222222222222222",
      "ownerUsername": "trader_alpha",
      "removed": false,
      "requireMemberMfa": false,
      "revision": "1",
      "role": "VIEWER",
      "smartAccountAddress": "0x2222222222222222222222222222222222222222",
      "smartAccountSaltNonce": 1,
      "status": "ACTIVE",
      "subaccountPolicyId": "627BigpnRg",
      "updatedAt": "2025-01-01T00:00:00Z"
    }
  ],
  "totalCreated": 1
}