Whitelists

Whitelists restrict where an account can send funds. Configure destinations for the source account before enabling automated withdrawals or transfers, then read their confirmed status before use. Each Main Account and Subaccount has its own entries and requirement settings.

Testnet is the public environment; hosts are in Environments and hosts.

Two whitelist types

The external withdraw whitelist applies to withdrawals to other Networks. An entry identifies both the Network and its destination address. Approval on one Network does not approve the same address on another Network.

The internal whitelist applies to movement within Polyester Chain and to Trading-account transfers. There is one internal whitelist for these paths. It identifies destination smart-account addresses, not labels, usernames, or public account IDs. Trading transfer APIs resolve the selected account to that address before checking it.

Each source account has separate external and internal requirement flags. When the relevant flag is enabled, the destination must be listed. When it is disabled, ordinary movement can accept an unlisted destination if every other check passes. Disabling a requirement does not make every destination a whitelist member.

Add or remove destinations

Whitelist changes are on-chain actions through the selected account's smart account. There is no REST or ConnectRPC mutation that directly adds, removes, or authorizes a whitelist entry.

Where GuardSigner protection applies, adding or removing entries and disabling a whitelist requirement need its second signature. Enabling a requirement remains wallet-authorized but does not require a GuardSigner approval. See GuardSigner for initialization and supported protected actions.

Use the same on-chain authority path for removals and requirement changes. Trading APIs enforce their mirror of the chain-confirmed state, so a removal is not guaranteed to be enforced until the mirror shows it. Read the resulting state before resuming a bot that depends on it. The user guide to address books and whitelists covers interactive management.

Read whitelist state

These read methods accept authorized sessions and API keys without fresh step-up. For API-key integrations, grant READ_ADDRESS_BOOK in the key policy and allow the read in the Subaccount policy where applicable. See API key policies.

• External entries and requirement flags: GetWithdrawWhitelistView (REST whitelist view) returns active external entries and both the external and internal requirement flags.
• Internal entries: ListInternalTransferWhitelistEntries (REST internal whitelist) returns active internal entries, including the destination smart-account address and account-resolution status.
• Destinations for a picker or bot configuration: ListTransferDestinations (REST destinations) combines saved destinations with active whitelisted destinations. It distinguishes saved, whitelisted, and whitelistStatus.

For a session, omit subaccountId to read the Main Account, or select an accessible Subaccount. For a Subaccount-scoped API key, omission selects the bound Subaccount. Keep reads and subsequent movement scoped to the same account; see Subaccounts and roles.

Follow nextPageToken for internal-entry and destination lists until it is empty. Do not conclude that an entry is absent after checking only the first page. Keep the account and filters unchanged when following a cursor.

The external view exposes a canonical address and, when available, raw address bytes as hex. Use the Network's destination encoding; do not treat raw hex as a second address to send funds to. An unresolved destination or status is not evidence of approval.

Address book versus whitelist

An address-book entry saves a label and reusable destination details. Saving, copying, or editing an entry does not whitelist it. Deleting a saved entry is not an on-chain whitelist removal. A destination can be saved, whitelisted, both, or neither.

A bot must inspect whitelist membership and the source account's requirement flag, rather than assuming that presence in ListTransferDestinations authorizes a withdrawal or transfer.

See Withdrawals and transfer security for the combined authorization rules. API-key movement does not use interactive MFA; protected whitelist administration does.

How movement is checked

Withdrawals to other Networks

Both Funding withdrawals and Trading withdrawals to external Networks use the source account's external whitelist requirement. Match the selected Network and destination, not the address label. Funding withdrawals are on-chain actions; Trading withdrawals use CreateTradingWithdraw for API keys or CreateWalletTradingWithdraw for interactive sessions.

Destination-format validation does not create whitelist membership or authorize movement. See Withdraw from Trading for withdrawal submission and Funds transfer overview for Funding and external destination validation.

Internal movement

Trading-to-Trading transfers check the source account's internal whitelist against the resolved destination smart-account address. Another Subaccount under the same owner is not exempt from an enabled requirement. See Internal transfers.

Trading-to-Funding withdrawals to another smart-account address also use the internal whitelist. To move Trading funds to the selected account's own Funding Account, omit the destination override; that own-account path does not need an internal whitelist entry.

Funding-to-Funding movement happens on Polyester Chain, where the contract checks the internal whitelist requirement. It does not use the Trading internal-transfer API.

Auto-withdraw

Auto-withdraw requires explicitly whitelisted external destinations when writing a rule and when paying it. Turning off the external requirement does not satisfy this rule. If a destination leaves the whitelist, the rule pauses with reason destination_not_whitelisted.

Handle a destination refusal

The Trading APIs refuse missing whitelist membership with HTTP 403. REST returns the code in an application/problem+json body. ConnectRPC reports permission_denied with the corresponding service's ErrorDetail code, prefixed with ERROR_CODE_.

• EXTERNAL_DESTINATION_NOT_WHITELISTED: A Trading withdrawal's external Network and destination do not satisfy the source account's external whitelist requirement.
• INTERNAL_RECIPIENT_NOT_WHITELISTED: A Trading-to-Funding withdrawal's different Funding recipient does not satisfy the internal whitelist requirement.
• DESTINATION_NOT_WHITELISTED: A Trading-to-Trading transfer's resolved destination does not satisfy the internal whitelist requirement.

Check the source account, Network, complete address, and current requirement flags. If the destination should be approved, complete the on-chain addition and wait until it appears in the read view before retrying. Saving the destination again or changing an API-key policy cannot add whitelist membership.

If whitelist state is unavailable, movement can instead fail with unavailable. Treat that as a readiness failure, not a missing entry; re-read and retry with backoff. On-chain Funding actions can revert when contract whitelist checks fail, independently of an earlier API read.

Use Error responses for decoding and the error catalog for the full endpoint-specific codes.

Related Topics