SubaccountViewService

Get Subaccount View

Return a single payload containing the sub-account and requested related read models, such as members, API keys, invites, policy, and balances.

Method

GET

Path

/v1/auth/subaccounts/{subaccount_id}

Visibility

Authentication required

Authentication

Session token or API key

MFA Requirement

Not required

GET

/v1/auth/subaccounts/{subaccount_id}

Request

Testnet

curl --request GET \ \
  --url 'https://api.testnet.polyester.com/v1/auth/subaccounts/6789012345678?includeApiKeys=false&includeBalances=false&includeInvites=false&includeMembers=false&includePolicy=false&invitesDirection=INCOMING' \
  --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

{
  "apiKeys": [
    {
      "color": "#7C3AED",
      "createdAt": "2025-01-01T00:00:00Z",
      "createdByActor": "dashboard",
      "expiresAt": "2025-01-01T00:00:00Z",
      "icon": "💰",
      "ipWhitelist": [
        "203.0.113.0/24"
      ],
      "keyId": "ak_1a3c6de8153d5a5b04cd2a6529779542",
      "label": "Trading Bot",
      "lastUsedAt": "2025-01-01T00:00:00Z",
      "policyId": "3Gxbxht1EK",
      "publicKeyEd25519": "AA==",
      "revision": "1",
      "status": "ACTIVE",
      "subaccountId": "37E2o5r2qHk",
      "updatedAt": "2025-01-01T00:00:00Z"
    }
  ],
  "balances": {
    "balances": [
      {
        "assetId": 100,
        "available": {
          "hi": "1",
          "lo": "1"
        },
        "funding": {
          "hi": "1",
          "lo": "1"
        },
        "fundingRevision": "1",
        "reserved": {
          "hi": "1",
          "lo": "1"
        },
        "trading": {
          "hi": "1",
          "lo": "1"
        },
        "tradingRevision": "1"
      }
    ]
  },
  "invites": [
    {
      "createdAt": "2025-01-01T00:00:00Z",
      "granteeAccountId": "3LH9o1FBKZC",
      "granteeRootSmartAccountAddress": "0x2222222222222222222222222222222222222222",
      "granteeUsername": "trader_alpha",
      "id": "6MxJavPReT",
      "inviterAccountId": "3JowFx91FxT",
      "inviterRootSmartAccountAddress": "0x2222222222222222222222222222222222222222",
      "inviterUsername": "trader_alpha",
      "requireMemberMfa": false,
      "respondedAt": "2025-01-01T00:00:00Z",
      "role": "VIEWER",
      "status": "PENDING",
      "subaccountId": "3AS6RGERAUL",
      "subaccountLabel": "Market Making"
    }
  ],
  "members": [
    {
      "accountId": "3HRq9SkcwNm",
      "avatarUrl": "https://placehold.co/128x128.png",
      "mfaEnrolled": false,
      "role": "VIEWER",
      "smartAccountAddress": "0x2222222222222222222222222222222222222222",
      "username": "trader_alpha"
    }
  ],
  "policy": {
    "actions": [
      "TRADE_SPOT"
    ],
    "createdAt": "2025-01-01T00:00:00Z",
    "description": "Allow spot trading for selected markets.",
    "expiresAt": "2025-01-01T00:00:00Z",
    "id": "7gQY8okwBT",
    "isTemplate": false,
    "locked": false,
    "maxOpenOrders": 1,
    "maxOrderNotional": "12345",
    "name": "Market Maker Policy",
    "reviewAt": "2025-01-01T00:00:00Z",
    "revision": "1",
    "sourceTemplateId": "8gnKtjkL5A",
    "spotMarketScope": "ALL",
    "spotMarkets": [
      {
        "symbolId": 1
      }
    ],
    "tradingHalted": false,
    "updatedAt": "2025-01-01T00:00:00Z"
  },
  "subaccount": {
    "color": "#7C3AED",
    "icon": "💰",
    "id": "62LGjN2AD8",
    "label": "Market Making",
    "ownerAvatarUrl": "https://placehold.co/128x128.png",
    "ownerRootSmartAccountAddress": "0x2222222222222222222222222222222222222222",
    "ownerUsername": "trader_alpha",
    "requireMemberMfa": false,
    "revision": "1",
    "role": "VIEWER",
    "smartAccountAddress": "0x2222222222222222222222222222222222222222",
    "smartAccountSaltNonce": 1,
    "status": "ACTIVE",
    "subaccountPolicyId": "8b5f1EAGDm",
    "updatedAt": "2025-01-01T00:00:00Z"
  }
}

subaccount_id string (int64) required > 0

Target sub-account (opaque ID).

includeApiKeys boolean

Include API keys scoped to this sub-account. Only owner and admin callers receive API keys.

includeBalances boolean

Include current balances for this sub-account.

includeInvites boolean

Include invitations visible to the caller.

includeMembers boolean

Include current members for this sub-account. Every current member may receive the roster.

includePolicy boolean

Include the attached sub-account policy, when one is attached. Every current member may receive it.

invitesDirection enum must be defined value

Optional invitation direction filter. An omitted value includes both scopes.

15 fields

id string (fixed64)

Sub-account identifier (opaque ID).

Example 62LGjN2AD8

role enum

Role of the current caller on this sub-account.

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 8b5f1EAGDm

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 indicate an invariant failure.

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

revision string (uint64)

Monotonic resource revision used for conditional updates.

Example 1

15 fields

keyId string

Stable opaque identifier used to refer to this key, formatted as "ak_" followed by 32 lowercase hex characters.

Example ak_1a3c6de8153d5a5b04cd2a6529779542

label string

Human-readable label for the key. Maximum length is 64 characters.

Example Trading Bot

icon string

Optional user-chosen icon/emoji for UI display.

Example 💰

color string (color)

Optional user-chosen color token for UI display.

Example #7C3AED

ipWhitelist string[]

Optional CIDR whitelist. Empty means no IP restriction. Maximum 32 unique entries.

Example ["203.0.113.0/24"]

status enum

Current key status.

ACTIVE REVOKED DISABLED

Example ACTIVE

subaccountId string (fixed64)

Optional sub-account this key is scoped to (opaque ID; empty = root-level).

Example 37E2o5r2qHk

policyId string (fixed64)

Optional API policy attached to this key (opaque ID). Empty means no policy is attached and the key has no permissions.

Example 3Gxbxht1EK

createdAt string (date-time)

Time in UTC when this key was created.

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

lastUsedAt string (date-time)

Last time in UTC when this key authenticated a request. Omitted when the key has not been used.

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

publicKeyEd25519 string (byte)

Ed25519 public key bytes associated with this API key. The private key or seed is never returned by the API.

Example AA==

expiresAt string (date-time)

Optional expiry time in UTC. When set, the key cannot authenticate requests after this time, regardless of status.

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

createdByActor string

Read-only actor label describing who created this key, such as a username or account label.

Example dashboard

updatedAt string (date-time)

Time in UTC when this key's configuration was last changed. For the same key, later is fresher, equal is an idempotent replay, and earlier is stale. Equal timestamps with different configuration indicate an invariant failure. This is independent of last_used_at, which tracks authentication activity.

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

revision string (uint64)

Monotonic resource revision used for conditional updates.

Example 1

6 fields

14 fields

17 fields

id string (fixed64)

Policy identifier (opaque ID).

Example 7gQY8okwBT

name string

Human-readable policy name.

Example Market Maker Policy

description string

Optional policy description for dashboards and audits.

Example Allow spot trading for selected markets.

1 field

spotMarketScope enum

Market-level scope for spot markets. When ALL, spot_markets is returned for display only and is not enforced.

ALL ALLOWLIST

Example ALL

actions enum[]

Effective high-level actions enabled for the sub-account. Mandatory read-only actions are always included.

TRADE_SPOT INTERNAL_TRANSFER EXTERNAL_WITHDRAW READ_BALANCES READ_SPOT READ_INTERNAL_TRANSFERS READ_ADDRESS_BOOK MANAGE_ADDRESS_BOOK

Example ["TRADE_SPOT"]

isTemplate boolean

True if this policy is a reusable template; false if it is a per-sub-account instance.

Example false

sourceTemplateId string (fixed64)

Optional source template this policy was copied from (opaque ID). This is audit metadata only and does not imply live linkage.

Example 8gnKtjkL5A

maxOrderNotional string (uint64)

Maximum notional size allowed for any single order on this sub-account, expressed in canonical quote microunits (one unit is 0.000001 USDT). A value of 0 means "no explicit cap".

Example 12345

maxOpenOrders integer (int32)

Maximum number of resting orders allowed on this sub-account at any time. A value of 0 means "no explicit cap".

Example 1

tradingHalted boolean

When true, new orders and exposure-increasing order or trigger changes are rejected regardless of other settings. Existing orders and triggers may still be canceled or paused by an otherwise authorized caller.

Example false

locked boolean

When true, this policy is write-protected and requires an elevated approval flow to modify it.

Example false

reviewAt string (date-time)

Optional review time in UTC. This is governance metadata and does not automatically disable the policy.

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

expiresAt string (date-time)

Optional expiry time in UTC. This is governance metadata and does not automatically disable the policy.

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

createdAt string (date-time)

Creation time in UTC.

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

updatedAt string (date-time)

Last update time in UTC.

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

revision string (uint64)

Monotonic resource revision used for conditional updates.

Example 1

1 field

Possible errors: 5

Key	Status	Error	When
unauthenticated	401	Unauthenticated	Authentication required.
permission-denied	403	Permission Denied	Permission denied.
invalid-argument	400	Invalid Argument	Invalid argument.
not-found	404	Not Found	Not found.
unavailable	503	Unavailable	Service unavailable.

GET

/v1/auth/subaccounts/{subaccount_id}

Request

Testnet

curl --request GET \ \
  --url 'https://api.testnet.polyester.com/v1/auth/subaccounts/6789012345678?includeApiKeys=false&includeBalances=false&includeInvites=false&includeMembers=false&includePolicy=false&invitesDirection=INCOMING' \
  --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

{
  "apiKeys": [
    {
      "color": "#7C3AED",
      "createdAt": "2025-01-01T00:00:00Z",
      "createdByActor": "dashboard",
      "expiresAt": "2025-01-01T00:00:00Z",
      "icon": "💰",
      "ipWhitelist": [
        "203.0.113.0/24"
      ],
      "keyId": "ak_1a3c6de8153d5a5b04cd2a6529779542",
      "label": "Trading Bot",
      "lastUsedAt": "2025-01-01T00:00:00Z",
      "policyId": "3Gxbxht1EK",
      "publicKeyEd25519": "AA==",
      "revision": "1",
      "status": "ACTIVE",
      "subaccountId": "37E2o5r2qHk",
      "updatedAt": "2025-01-01T00:00:00Z"
    }
  ],
  "balances": {
    "balances": [
      {
        "assetId": 100,
        "available": {
          "hi": "1",
          "lo": "1"
        },
        "funding": {
          "hi": "1",
          "lo": "1"
        },
        "fundingRevision": "1",
        "reserved": {
          "hi": "1",
          "lo": "1"
        },
        "trading": {
          "hi": "1",
          "lo": "1"
        },
        "tradingRevision": "1"
      }
    ]
  },
  "invites": [
    {
      "createdAt": "2025-01-01T00:00:00Z",
      "granteeAccountId": "3LH9o1FBKZC",
      "granteeRootSmartAccountAddress": "0x2222222222222222222222222222222222222222",
      "granteeUsername": "trader_alpha",
      "id": "6MxJavPReT",
      "inviterAccountId": "3JowFx91FxT",
      "inviterRootSmartAccountAddress": "0x2222222222222222222222222222222222222222",
      "inviterUsername": "trader_alpha",
      "requireMemberMfa": false,
      "respondedAt": "2025-01-01T00:00:00Z",
      "role": "VIEWER",
      "status": "PENDING",
      "subaccountId": "3AS6RGERAUL",
      "subaccountLabel": "Market Making"
    }
  ],
  "members": [
    {
      "accountId": "3HRq9SkcwNm",
      "avatarUrl": "https://placehold.co/128x128.png",
      "mfaEnrolled": false,
      "role": "VIEWER",
      "smartAccountAddress": "0x2222222222222222222222222222222222222222",
      "username": "trader_alpha"
    }
  ],
  "policy": {
    "actions": [
      "TRADE_SPOT"
    ],
    "createdAt": "2025-01-01T00:00:00Z",
    "description": "Allow spot trading for selected markets.",
    "expiresAt": "2025-01-01T00:00:00Z",
    "id": "7gQY8okwBT",
    "isTemplate": false,
    "locked": false,
    "maxOpenOrders": 1,
    "maxOrderNotional": "12345",
    "name": "Market Maker Policy",
    "reviewAt": "2025-01-01T00:00:00Z",
    "revision": "1",
    "sourceTemplateId": "8gnKtjkL5A",
    "spotMarketScope": "ALL",
    "spotMarkets": [
      {
        "symbolId": 1
      }
    ],
    "tradingHalted": false,
    "updatedAt": "2025-01-01T00:00:00Z"
  },
  "subaccount": {
    "color": "#7C3AED",
    "icon": "💰",
    "id": "62LGjN2AD8",
    "label": "Market Making",
    "ownerAvatarUrl": "https://placehold.co/128x128.png",
    "ownerRootSmartAccountAddress": "0x2222222222222222222222222222222222222222",
    "ownerUsername": "trader_alpha",
    "requireMemberMfa": false,
    "revision": "1",
    "role": "VIEWER",
    "smartAccountAddress": "0x2222222222222222222222222222222222222222",
    "smartAccountSaltNonce": 1,
    "status": "ACTIVE",
    "subaccountPolicyId": "8b5f1EAGDm",
    "updatedAt": "2025-01-01T00:00:00Z"
  }
}

Polyester is best experienced on desktop.

Request

Responses