auth.v1.SubaccountViewService
GetSubaccount
Aggregate commonly-needed read data for a sub-account dashboard page.
Request
curl --request POST \ \
--url 'https://api.testnet.polyester.com/auth.v1.SubaccountViewService/GetSubaccount' \
--header 'Content-Type: application/json' \
--header 'Connect-Protocol-Version: 1' \
--data '{
"includeApiKeys": false,
"includeBalances": false,
"includeInvites": false,
"includeMembers": false,
"includePolicy": false,
"invitesDirection": "INCOMING",
"subaccountId": "6789012345678"
}'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": "1",
"publicKeyEd25519": "AA==",
"revision": "1",
"status": "ACTIVE",
"subaccountId": "6789012345678",
"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": "7563897446546",
"granteeRootSmartAccountAddress": "0x2222222222222222222222222222222222222222",
"granteeUsername": "trader_alpha",
"id": "1",
"inviterAccountId": "7563897446546",
"inviterRootSmartAccountAddress": "0x2222222222222222222222222222222222222222",
"inviterUsername": "trader_alpha",
"requireMemberMfa": false,
"respondedAt": "2025-01-01T00:00:00Z",
"role": "VIEWER",
"status": "SUBACCOUNT_INVITE_STATUS_PENDING",
"subaccountId": "6789012345678",
"subaccountLabel": "Market Making"
}
],
"members": [
{
"accountId": "7563897446546",
"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": "1",
"isTemplate": false,
"locked": false,
"maxOpenOrders": 1,
"maxOrderNotional": "12345",
"name": "Market Maker Policy",
"reviewAt": "2025-01-01T00:00:00Z",
"revision": "1",
"sourceTemplateId": "1",
"spotMarketScope": "ALL",
"spotMarkets": [
{
"symbolId": 1
}
],
"tradingHalted": false,
"updatedAt": "2025-01-01T00:00:00Z"
},
"subaccount": {
"color": "#7C3AED",
"icon": "💰",
"id": "1",
"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": "SUBACCOUNT_STATUS_ACTIVE",
"subaccountPolicyId": "1",
"updatedAt": "2025-01-01T00:00:00Z"
}
}auth.v1.GetSubaccountRequestauth.v1.GetSubaccountResponseTarget sub-account (opaque ID).
Include API keys scoped to this sub-account. Only owner and admin callers receive API keys.
Include current members for this sub-account. Every current member may receive the roster.
Include invitations visible to the caller.
Include the attached sub-account policy, when one is attached. Every current member may receive it.
Include current balances for this sub-account. The caller needs the READ_BALANCES action on the sub-account: its role, any attached sub-account policy and, for an API key, the key's policy must allow it, or the request fails with PermissionDenied. When balances cannot be read right now, the request fails with Unavailable and AUTH_TEMPORARILY_UNAVAILABLE; retry the same request.
Optional invitation direction filter. An omitted value includes both scopes.
Sub-account identifier (opaque ID).
Role of the current caller on this sub-account. SUBACCOUNT_ROLE_UNSPECIFIED when removed is true.
Optional human-readable label for this sub-account.
Optional user-chosen icon/emoji for UI display.
Optional user-chosen color token for UI display. Tokens use lowercase letters, numbers, underscores, or hyphens.
Current public lifecycle status of the sub-account.
Smart Account EVM address backing this sub-account.
Owner (root account) public username, if set. Useful for shared views.
Owner (root account) avatar URL, if set.
Owner (root account) primary Smart Account address, when available. Allows clients to display a stable identity even when no username is set.
Optional sub-account policy identifier (opaque ID). 0 means no explicit policy attached.
Owner-controlled security baseline for delegated interactive members on protected sub-account actions. This does not apply to read-only real-time subscriptions.
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.
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.
Monotonic resource revision used for conditional updates.
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.
Stable opaque identifier used to refer to this key, formatted as "ak_" followed by 32 lowercase hex characters.
Human-readable label for the key. Maximum length is 64 characters.
Optional user-chosen icon/emoji for UI display.
Optional user-chosen color token for UI display.
Optional CIDR whitelist. Empty means no IP restriction. Maximum 32 unique entries.
Current key status.
Optional sub-account this key is scoped to (opaque ID; empty = root-level).
Optional API policy attached to this key (opaque ID). Empty means no policy is attached and the key has no permissions.
Time in UTC when this key was created.
Approximate last time in UTC when this key authenticated a request, recorded at most about once a minute; it may lag recent use by a few minutes. Omitted when no use has been recorded.
Ed25519 public key bytes associated with this API key. The private key or seed is never returned by the API.
Optional expiry time in UTC. When set, the key cannot authenticate requests after this time, regardless of status.
Read-only actor label describing who created this key, such as a username or account label.
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.
Monotonic resource revision used for conditional updates.
Identifier for the member's root account (opaque ID).
Effective role on this sub-account.
Optional username for the member's root account.
Smart Account address for the member's root account, if any.
Optional avatar URL for the member's root account.
True when the member has at least one MFA factor enrolled on their root account.
Invite identifier (opaque ID).
Target sub-account (opaque ID).
Grantee root account ID the invite is for (opaque ID).
Inviter root account ID (opaque ID).
Requested role for the grantee.
Current invitation status.
Time when the invitation was created.
Time when the invitation was accepted, declined, or cancelled. Empty while pending.
Optional usernames for better UX in invite lists.
Username of the account that sent the invitation, when available.
Optional label for the target sub-account, for display in invite lists.
Inviter (root account) primary Smart Account address, when available. Useful for displaying a stable identity when no username is set.
Grantee (root account) primary Smart Account address, when available. Useful for displaying a stable identity when no username is set.
Current delegated-member MFA requirement on the target sub-account. If true, accepting the invite requires MFA enrollment and fresh step-up.
Policy identifier (opaque ID).
Human-readable policy name.
Optional policy description for dashboards and audits.
Stable numeric pair ID.
Market-level scope for spot markets. When ALL, spot_markets is returned for display only and is not enforced.
Effective high-level actions enabled for the sub-account. Mandatory read-only actions are always included.
True if this policy is a reusable template; false if it is a per-sub-account instance.
Optional source template this policy was copied from (opaque ID). This is audit metadata only and does not imply live linkage.
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".
Maximum number of resting orders allowed on this sub-account at any time. A value of 0 means "no explicit cap".
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.
When true, this policy is write-protected and requires an elevated approval flow to modify it.
Optional review time in UTC. This is governance metadata and does not automatically disable the policy.
Optional expiry time in UTC. This is governance metadata and does not automatically disable the policy.
Creation time in UTC.
Last update time in UTC.
Monotonic resource revision used for conditional updates.
Public unified asset id. Resolve symbol from SpotConfig; U128 amounts in this message always use fixed 18-decimal ledger scale.
Most significant 64 bits.
Least significant 64 bits.
Most significant 64 bits.
Least significant 64 bits.
Most significant 64 bits.
Least significant 64 bits.
Most significant 64 bits.
Least significant 64 bits.
Opaque monotonic revision for the atomic trading, reserved, and available values. Higher means newer; zero means no trading state has been observed.
Opaque monotonic revision for the funding value. Higher means newer; zero means no funding state has been observed.
| 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. |