Skip to main content

IP whitelist

In addition to the API key, you may optionally restrict which source IP addresses are allowed to call any wallet-API-key-authenticated endpoint for a given wallet. This applies to the new GET /agent/transactions endpoint as well as every other endpoint that authenticates with the wallet API key.

The IP whitelist is opt-in and is configured per wallet. If you do not configure it, nothing changes — API key authentication continues to work as it did before.

Behavior​

  • If the whitelist is empty or unset for a wallet, no IP restriction is enforced and existing behavior is preserved.
  • If the whitelist is set, every request authenticated with the wallet's API key must originate from an address that matches at least one entry in the list. Otherwise the request is rejected with 401 Unauthorized and an IP_NOT_WHITELISTED reason is recorded in the auth-failure context.

Configuring the whitelist​

The whitelist is a wallet-level configuration value managed by the VCash operations team. To add, change, or remove the whitelist for your wallet, contact your VCash support contact with the desired comma-separated list of IPv4/IPv6 addresses and/or CIDR ranges or let us know you wish to disable the restriction.

Operational guidance​

  • We recommend enabling the IP whitelist for any wallet whose API key is used exclusively from a known, stable egress
  • Plan ahead before changing your egress IP (for example, when migrating to a new datacenter or NAT gateway). Update the whitelist to include the new range before cutting traffic over, and remove the old entry only after the migration is complete.