auth.v1.AddressBookService
GetAddressBookView
Request
curl --request POST \ \
--url 'https://api.testnet.polyester.com/auth.v1.AddressBookService/GetAddressBookView' \
--header 'Content-Type: application/json' \
--header 'Connect-Protocol-Version: 1' \
--data '{
"limit": 100,
"minimumViewRevision": "1",
"subaccountId": "6789012345678"
}'Responses
{
"books": [
{
"callerRole": "VIEWER",
"label": "Main Account",
"ownerUsername": "trader_alpha",
"scope": {
"rootAccountId": "7563897446546",
"scopeType": "SCOPE_ROOT",
"subaccountId": "6789012345678"
},
"smartAccountAddress": "0x2222222222222222222222222222222222222222"
}
],
"entries": {
"external": [
{
"address": "0x3333333333333333333333333333333333333333",
"addressBookEntryId": "1",
"createdAt": "2025-01-01T00:00:00Z",
"label": "Treasury Wallet",
"note": "Primary treasury destination.",
"polychainChainId": 1,
"revision": "1",
"scope": {
"rootAccountId": "7563897446546",
"scopeType": "SCOPE_ROOT",
"subaccountId": "6789012345678"
},
"tagIds": [
"1"
],
"updatedAt": "2025-01-01T00:00:00Z",
"whitelistStatus": "DESTINATION_NOT_WHITELISTED"
}
],
"internal": [
{
"addressBookEntryId": "1",
"createdAt": "2025-01-01T00:00:00Z",
"label": "Market Maker",
"note": "Primary treasury destination.",
"revision": "1",
"rootAccountId": "7563897446546",
"rootUsername": "trader_alpha",
"scope": {
"rootAccountId": "7563897446546",
"scopeType": "SCOPE_ROOT",
"subaccountId": "6789012345678"
},
"smartAccountAddress": "0x2222222222222222222222222222222222222222",
"subaccountLabel": "Market Making",
"tagIds": [
"1"
],
"targetAccountId": "7563897446546",
"targetScopeType": "SCOPE_ROOT",
"updatedAt": "2025-01-01T00:00:00Z",
"whitelistStatus": "DESTINATION_NOT_WHITELISTED"
}
]
},
"recentDestinations": {
"external": [
{
"address": "0x3333333333333333333333333333333333333333",
"addressBookEntryId": "1",
"lastDirection": "DEPOSIT_FROM",
"lastSeenAt": "2025-01-01T00:00:00Z",
"polychainChainId": 1,
"saved": false,
"scope": {
"rootAccountId": "7563897446546",
"scopeType": "SCOPE_ROOT",
"subaccountId": "6789012345678"
},
"useCount": "1"
}
],
"internal": [
{
"addressBookEntryId": "1",
"lastDirection": "DEPOSIT_FROM",
"lastSeenAt": "2025-01-01T00:00:00Z",
"rootAccountId": "7563897446546",
"rootUsername": "trader_alpha",
"saved": false,
"scope": {
"rootAccountId": "7563897446546",
"scopeType": "SCOPE_ROOT",
"subaccountId": "6789012345678"
},
"smartAccountAddress": "0x2222222222222222222222222222222222222222",
"subaccountLabel": "Market Making",
"targetAccountId": "7563897446546",
"targetScopeType": "SCOPE_ROOT",
"useCount": "1"
}
]
},
"recentDestinationsTruncated": false,
"tags": [
{
"color": "#7C3AED",
"name": "Treasury",
"tagId": "1"
}
],
"viewRevision": "1",
"withdrawWhitelist": {
"activeEntries": [
{
"canonicalAddress": "0x3333333333333333333333333333333333333333",
"polychainChainId": 1,
"rawAddressHex": "3333333333333333333333333333333333333333",
"updatedAt": "2025-01-01T00:00:00Z"
}
],
"externalWhitelistRequired": false,
"internalWhitelistRequired": false,
"scope": {
"rootAccountId": "7563897446546",
"scopeType": "SCOPE_ROOT",
"subaccountId": "6789012345678"
}
}
}auth.v1.GetAddressBookViewRequestauth.v1.GetAddressBookViewResponseOptional subaccount scope. Omit to use the root account address book view.
Maximum number of recent destinations to return. Defaults to 200 when omitted; maximum is 200.
Minimum revision observed in AddressBookViewInvalidated. When set, the server waits for its local projection to reach this revision instead of returning an older view.
Address-book scope type.
Root account that owns this address book.
Subaccount for subaccount-scoped books. Empty for root account books.
Caller role for this address book.
Display label for the address book. Usually present for subaccounts.
Username of the root owner when available.
Smart account address associated with this account or subaccount.
Stable public id of the saved external destination.
Address-book scope type.
Root account that owns this address book.
Subaccount for subaccount-scoped books. Empty for root account books.
User-defined display label.
Optional user-defined note.
Tag ids attached to this entry. See GetAddressBookViewResponse.tags for tag details.
Current active whitelist status for this destination.
External network identifier for the destination address.
Destination address on the selected external network: 1-256 characters, without whitespace or angle brackets.
Time this entry was created, as a UTC timestamp.
Time this entry was last updated, as a UTC timestamp.
Monotonic resource revision used for conditional updates.
Stable public id of the saved internal destination.
Address-book scope type.
Root account that owns this address book.
Subaccount for subaccount-scoped books. Empty for root account books.
User-defined display label.
Optional user-defined note.
Tag ids attached to this entry. See GetAddressBookViewResponse.tags for tag details.
Current active whitelist status for this destination.
Root account that owns the target internal account.
Target account or subaccount public id.
Whether target_account_id identifies a root account or a subaccount.
Smart account address for the internal transfer destination.
Username for the destination root account, when available.
Label for the destination subaccount, when the destination is a subaccount.
Time this entry was created, as a UTC timestamp.
Time this entry was last updated, as a UTC timestamp.
Monotonic resource revision used for conditional updates.
Address-book scope type.
Root account that owns this address book.
Subaccount for subaccount-scoped books. Empty for root account books.
Direction of the most recent interaction.
Whether this destination is already saved in the address book.
Saved address book entry id when saved is true.
Number of transfers observed for this destination.
Time this destination was last used, as a UTC timestamp.
External network identifier for the destination address.
Destination address on the selected external network: 1-256 characters, without whitespace or angle brackets.
Address-book scope type.
Root account that owns this address book.
Subaccount for subaccount-scoped books. Empty for root account books.
Direction of the most recent interaction.
Whether this destination is already saved in the address book.
Saved address book entry id when saved is true.
Number of transfers observed for this destination.
Time this destination was last used, as a UTC timestamp.
Root account that owns the target internal account.
Target account or subaccount public id.
Whether target_account_id identifies a root account or a subaccount.
Smart account address for the internal transfer destination.
Username for the destination root account, when available.
Label for the destination subaccount, when the destination is a subaccount.
Stable public id of the tag.
Human-readable tag name.
Optional UI color token for this tag.
Address-book scope type.
Root account that owns this address book.
Subaccount for subaccount-scoped books. Empty for root account books.
Whether external withdrawals are restricted to whitelisted destinations.
Destination address on the selected external network.
Encoded destination payload as lowercase hex, when available.
Time this whitelist entry was last updated, as a UTC timestamp.
External network identifier for this whitelist entry.
Whether internal transfers are restricted to whitelisted destinations.
True when more recent destinations exist than were returned. This bounded aggregate view does not provide continuation.
Revision of the complete scope projection returned by this response.
| 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. |