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=6789012345678' \ --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": "7563897446546",
"scopeType": "ROOT",
"subaccountId": "341ihSXYWzi"
},
"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": "ROOT",
"subaccountId": "3ArseuRahdw"
},
"tagIds": [
"1"
],
"updatedAt": "2025-01-01T00:00:00Z",
"whitelistStatus": "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": "ROOT",
"subaccountId": "38mKGUs1h1h"
},
"smartAccountAddress": "0x2222222222222222222222222222222222222222",
"subaccountLabel": "Market Making",
"tagIds": [
"1"
],
"targetAccountId": "7563897446546",
"targetScopeType": "ROOT",
"updatedAt": "2025-01-01T00:00:00Z",
"whitelistStatus": "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": "ROOT",
"subaccountId": "3AWgmNzsvkd"
},
"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": "ROOT",
"subaccountId": "37TtjUYg847"
},
"smartAccountAddress": "0x2222222222222222222222222222222222222222",
"subaccountLabel": "Market Making",
"targetAccountId": "7563897446546",
"targetScopeType": "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": "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.
Address-book scope type.
ROOTRoot account that owns this address book.
7563897446546Subaccount for subaccount-scoped books. Empty for root account books.
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.
1Address-book scope type.
ROOTRoot account that owns this address book.
7563897446546Subaccount for subaccount-scoped books. Empty for root account books.
3ArseuRahdwUser-defined display label.
Treasury WalletOptional user-defined note.
Primary treasury destination.Tag ids attached to this entry. See GetAddressBookViewResponse.tags for tag details.
["1"]Current active whitelist status for this destination.
NOT_WHITELISTEDExternal network identifier for the destination address.
1Destination address on the selected external network.
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.
1Address-book scope type.
ROOTRoot account that owns this address book.
7563897446546Subaccount for subaccount-scoped books. Empty for root account books.
38mKGUs1h1hUser-defined display label.
Market MakerOptional user-defined note.
Primary treasury destination.Tag ids attached to this entry. See GetAddressBookViewResponse.tags for tag details.
["1"]Current active whitelist status for this destination.
NOT_WHITELISTEDRoot account that owns the target internal account.
7563897446546Target account or subaccount public id.
7563897446546Whether 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.
7563897446546Subaccount for subaccount-scoped books. Empty for root account books.
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.
1Number 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.
0x3333333333333333333333333333333333333333Address-book scope type.
ROOTRoot account that owns this address book.
7563897446546Subaccount for subaccount-scoped books. Empty for root account books.
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.
1Number 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.
7563897446546Target account or subaccount public id.
7563897446546Whether 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.
1Human-readable tag name.
TreasuryOptional UI color token for this tag.
#7C3AEDAddress-book scope type.
ROOTRoot account that owns this address book.
7563897446546Subaccount for subaccount-scoped books. Empty for root account books.
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 | 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. |