AddressBookService
Get Address Book View
Get address books, saved destinations, recent destinations, tags, and whitelist status in one response.
Request
curl --request GET \ \ --url 'https://api.testnet.polyester.com/v1/auth/address-book?limit=100&minimumViewRevision=1&subaccountId=45LUmqjT' \ --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
{
"books": [
{
"callerRole": "VIEWER",
"label": "Main Account",
"ownerUsername": "trader_alpha",
"scope": {
"rootAccountId": "3BYw1KrcZxz",
"scopeType": "ROOT",
"subaccountId": "341ihSXYWzi"
},
"smartAccountAddress": "0x2222222222222222222222222222222222222222"
}
],
"entries": {
"external": [
{
"address": "0x3333333333333333333333333333333333333333",
"addressBookEntryId": "7st3bnazq",
"createdAt": "2025-01-01T00:00:00Z",
"label": "Treasury Wallet",
"note": "Primary treasury destination.",
"polychainChainId": 1,
"revision": "1",
"scope": {
"rootAccountId": "3CZux54TviB",
"scopeType": "ROOT",
"subaccountId": "3ArseuRahdw"
},
"tagIds": [
"97e9Su8MH"
],
"updatedAt": "2025-01-01T00:00:00Z",
"whitelistStatus": "NOT_WHITELISTED"
}
],
"internal": [
{
"addressBookEntryId": "6y6sAPZmGX",
"createdAt": "2025-01-01T00:00:00Z",
"label": "Market Maker",
"note": "Primary treasury destination.",
"revision": "1",
"rootAccountId": "3DMydsTWTLP",
"rootUsername": "trader_alpha",
"scope": {
"rootAccountId": "3DThvrTXKH3",
"scopeType": "ROOT",
"subaccountId": "38mKGUs1h1h"
},
"smartAccountAddress": "0x2222222222222222222222222222222222222222",
"subaccountLabel": "Market Making",
"tagIds": [
"2tWN7RALfX"
],
"targetAccountId": "3DZcFiDXnJ6",
"targetScopeType": "ROOT",
"updatedAt": "2025-01-01T00:00:00Z",
"whitelistStatus": "NOT_WHITELISTED"
}
]
},
"recentDestinations": {
"external": [
{
"address": "0x3333333333333333333333333333333333333333",
"addressBookEntryId": "RwsmjF3w3",
"lastDirection": "DEPOSIT_FROM",
"lastSeenAt": "2025-01-01T00:00:00Z",
"polychainChainId": 1,
"saved": false,
"scope": {
"rootAccountId": "3Gjxo5hy8XH",
"scopeType": "ROOT",
"subaccountId": "3AWgmNzsvkd"
},
"useCount": "1"
}
],
"internal": [
{
"addressBookEntryId": "3QUBbNQyhm",
"lastDirection": "DEPOSIT_FROM",
"lastSeenAt": "2025-01-01T00:00:00Z",
"rootAccountId": "3CmunKBqG51",
"rootUsername": "trader_alpha",
"saved": false,
"scope": {
"rootAccountId": "3H9pMzNtFtV",
"scopeType": "ROOT",
"subaccountId": "37TtjUYg847"
},
"smartAccountAddress": "0x2222222222222222222222222222222222222222",
"subaccountLabel": "Market Making",
"targetAccountId": "3L224G46QKk",
"targetScopeType": "ROOT",
"useCount": "1"
}
]
},
"recentDestinationsTruncated": false,
"tags": [
{
"color": "#7C3AED",
"name": "Treasury",
"tagId": "9SYQomkJBz"
}
],
"viewRevision": "1",
"withdrawWhitelist": {
"activeEntries": [
{
"canonicalAddress": "0x3333333333333333333333333333333333333333",
"polychainChainId": 1,
"rawAddressHex": "3333333333333333333333333333333333333333",
"updatedAt": "2025-01-01T00:00:00Z"
}
],
"externalWhitelistRequired": false,
"internalWhitelistRequired": false,
"scope": {
"rootAccountId": "3C91KuCaPEq",
"scopeType": "ROOT",
"subaccountId": "34RHq4Bu6f1"
}
}
}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.
Optional subaccount scope. Omit to use the root account address book view. Public ID, as a base58 string.
Address-book scope type.
ROOTRoot account that owns this address book. Public ID. ConnectRPC carries it as fixed64 (a decimal string in JSON).
3BYw1KrcZxzSubaccount for subaccount-scoped books. Empty for root account books. Public ID. ConnectRPC carries it as fixed64 (a decimal string in JSON).
341ihSXYWziCaller role for this address book.
VIEWERDisplay label for the address book. Usually present for subaccounts.
Main AccountUsername of the root owner when available.
trader_alphaSmart account address associated with this account or subaccount.
0x2222222222222222222222222222222222222222Stable public id of the saved external destination. Public ID. ConnectRPC carries it as fixed64 (a decimal string in JSON).
7st3bnazqAddress-book scope type.
ROOTRoot account that owns this address book. Public ID. ConnectRPC carries it as fixed64 (a decimal string in JSON).
3CZux54TviBSubaccount for subaccount-scoped books. Empty for root account books. Public ID. ConnectRPC carries it as fixed64 (a decimal string in JSON).
3ArseuRahdwUser-defined display label.
Treasury WalletOptional user-defined note.
Primary treasury destination.Tag ids attached to this entry. See GetAddressBookViewResponse.tags for tag details. Public ID. ConnectRPC carries it as fixed64 (a decimal string in JSON).
["97e9Su8MH"]Current active whitelist status for this destination.
NOT_WHITELISTEDExternal network identifier for the destination address.
1Destination address on the selected external network: 1-256 characters, without whitespace or angle brackets.
0x3333333333333333333333333333333333333333Time this entry was created, as a UTC timestamp.
2025-01-01T00:00:00ZTime this entry was last updated, as a UTC timestamp.
2025-01-01T00:00:00ZMonotonic resource revision used for conditional updates.
1Stable public id of the saved internal destination. Public ID. ConnectRPC carries it as fixed64 (a decimal string in JSON).
6y6sAPZmGXAddress-book scope type.
ROOTRoot account that owns this address book. Public ID. ConnectRPC carries it as fixed64 (a decimal string in JSON).
3DThvrTXKH3Subaccount for subaccount-scoped books. Empty for root account books. Public ID. ConnectRPC carries it as fixed64 (a decimal string in JSON).
38mKGUs1h1hUser-defined display label.
Market MakerOptional user-defined note.
Primary treasury destination.Tag ids attached to this entry. See GetAddressBookViewResponse.tags for tag details. Public ID. ConnectRPC carries it as fixed64 (a decimal string in JSON).
["2tWN7RALfX"]Current active whitelist status for this destination.
NOT_WHITELISTEDRoot account that owns the target internal account. Public ID. ConnectRPC carries it as fixed64 (a decimal string in JSON).
3DMydsTWTLPTarget account or subaccount public id. Public ID. ConnectRPC carries it as fixed64 (a decimal string in JSON).
3DZcFiDXnJ6Whether target_account_id identifies a root account or a subaccount.
ROOTSmart account address for the internal transfer destination.
0x2222222222222222222222222222222222222222Username for the destination root account, when available.
trader_alphaLabel for the destination subaccount, when the destination is a subaccount.
Market MakingTime this entry was created, as a UTC timestamp.
2025-01-01T00:00:00ZTime this entry was last updated, as a UTC timestamp.
2025-01-01T00:00:00ZMonotonic resource revision used for conditional updates.
1Address-book scope type.
ROOTRoot account that owns this address book. Public ID. ConnectRPC carries it as fixed64 (a decimal string in JSON).
3Gjxo5hy8XHSubaccount for subaccount-scoped books. Empty for root account books. Public ID. ConnectRPC carries it as fixed64 (a decimal string in JSON).
3AWgmNzsvkdDirection of the most recent interaction.
DEPOSIT_FROMWhether this destination is already saved in the address book.
falseSaved address book entry id when saved is true. Public ID. ConnectRPC carries it as fixed64 (a decimal string in JSON).
RwsmjF3w3Number of transfers observed for this destination.
1Time this destination was last used, as a UTC timestamp.
2025-01-01T00:00:00ZExternal network identifier for the destination address.
1Destination address on the selected external network: 1-256 characters, without whitespace or angle brackets.
0x3333333333333333333333333333333333333333Address-book scope type.
ROOTRoot account that owns this address book. Public ID. ConnectRPC carries it as fixed64 (a decimal string in JSON).
3H9pMzNtFtVSubaccount for subaccount-scoped books. Empty for root account books. Public ID. ConnectRPC carries it as fixed64 (a decimal string in JSON).
37TtjUYg847Direction of the most recent interaction.
DEPOSIT_FROMWhether this destination is already saved in the address book.
falseSaved address book entry id when saved is true. Public ID. ConnectRPC carries it as fixed64 (a decimal string in JSON).
3QUBbNQyhmNumber of transfers observed for this destination.
1Time this destination was last used, as a UTC timestamp.
2025-01-01T00:00:00ZRoot account that owns the target internal account. Public ID. ConnectRPC carries it as fixed64 (a decimal string in JSON).
3CmunKBqG51Target account or subaccount public id. Public ID. ConnectRPC carries it as fixed64 (a decimal string in JSON).
3L224G46QKkWhether target_account_id identifies a root account or a subaccount.
ROOTSmart account address for the internal transfer destination.
0x2222222222222222222222222222222222222222Username for the destination root account, when available.
trader_alphaLabel for the destination subaccount, when the destination is a subaccount.
Market MakingStable public id of the tag. Public ID. ConnectRPC carries it as fixed64 (a decimal string in JSON).
9SYQomkJBzHuman-readable tag name.
TreasuryOptional UI color token for this tag.
#7C3AEDAddress-book scope type.
ROOTRoot account that owns this address book. Public ID. ConnectRPC carries it as fixed64 (a decimal string in JSON).
3C91KuCaPEqSubaccount for subaccount-scoped books. Empty for root account books. Public ID. ConnectRPC carries it as fixed64 (a decimal string in JSON).
34RHq4Bu6f1Whether external withdrawals are restricted to whitelisted destinations.
falseDestination address on the selected external network.
0x3333333333333333333333333333333333333333Encoded destination payload as lowercase hex, when available.
3333333333333333333333333333333333333333Time this whitelist entry was last updated, as a UTC timestamp.
2025-01-01T00:00:00ZExternal network identifier for this whitelist entry.
1Whether internal transfers are restricted to whitelisted destinations.
falseTrue when more recent destinations exist than were returned. This bounded aggregate view does not provide continuation.
falseRevision of the complete scope projection returned by this response.
1| 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. |