How Address Whitelisting Differs From IP Whitelisting
IP whitelisting restricts which network locations can make API calls to the gateway — it controls who can initiate commands. Address whitelisting restricts which destination addresses can receive outgoing funds from the gateway — it controls where money can go. The two controls operate at different layers of the security architecture and protect against different attacks.
A compromised API credential with no address whitelist in place allows an attacker to redirect all outgoing settlements and payouts to any address of their choosing. A compromised API credential with address whitelisting in place cannot redirect funds — any withdrawal targeting a non-whitelisted address is rejected regardless of who authorised it or what credentials were used. The fund movement cannot occur until an authorised administrator adds the destination to the whitelist through a separately authenticated process.
The Time-Lock Delay for New Address Additions
Address whitelisting is most effective when combined with a time-lock delay: when a new address is added to the whitelist, there is a mandatory waiting period — typically 24–72 hours — before that address can receive funds. This delay ensures that a fraudulent address addition (by a compromised account or insider) can be detected and reversed before any funds are transferred to the new address.
During the time-lock window, the gateway should notify designated security contacts by email and optionally by SMS that a new withdrawal address has been added. If the notification was not expected — because the legitimate account owner did not make the addition — the security contact can immediately revoke the addition and change credentials before the delay expires and funds become transferable. Time-locked address addition transforms a time-sensitive race (attacker adds address and immediately withdraws) into a detective control (suspicious addition is visible and reversible before any funds move).
Address Whitelisting in API-Driven Payout Flows
For businesses using the gateway's API to programmatically initiate payouts — marketplace seller payments, affiliate commissions, contractor disbursements — address whitelisting requires integration into the recipient management workflow. Recipient wallet addresses must be added to the whitelist before they can receive a payout. This creates an onboarding step: when a new marketplace seller, affiliate, or contractor registers, their payout wallet address must be submitted for whitelisting, verified (if the gateway requires address ownership confirmation), and approved through the time-lock period before the first payout can be sent.
This process adds friction but is operationally manageable when designed into the platform's onboarding flow: sellers provide their wallet address during registration, the gateway adds it to the pending whitelist, and payouts are enabled after the time-lock clears. Attempting to add address whitelisting retroactively to a platform with existing recipients requires a batch re-verification process that is operationally intensive but worth completing as a security uplift.
Protecting Against the Insider Threat
Address whitelisting is one of the few controls that meaningfully mitigates the insider threat: the risk that an employee with legitimate gateway access uses that access to divert funds. An employee who adds their own wallet to the whitelist and initiates a payout to it has committed a detectable fraud — the whitelist addition creates an audit log entry, the time-lock delay creates a detection window, and the notification system alerts other team members. Without address whitelisting, an employee with payout authorisation could transfer funds to any address, with discovery only possible after the fact from settlement logs.
Compliance Note: This glossary entry is provided for general educational purposes only and does not constitute financial, investment, legal, or tax advice. Industry terminology may vary across jurisdictions and providers; definitions herein may not directly reflect the specific features, terms, or specifications of Finassets' services. For details on Finassets' offerings, please refer to official product documentation or contact our team directly.