Field Naming Normalization
Address and identifier fields now follow one convention across the API: user_address for a user's EOA, wallet_address for a Smart Wallet, destination_address for the target of a transfer, recipient_address for a recipient's crypto address, and user_id for a user's UUID. The previous names are still populated on responses and still accepted on requests, so existing integrations continue to work unchanged.
What's changed
| Endpoint or payload | Was | Now |
|---|---|---|
POST /api/v2/user, POST /api/v1/user request | wallet_address | user_address |
GET /api/v2/user, POST {your_webhook_base_url}/v2/webhooks/user | id, owner | user_id, user_address |
GET /api/v1/user | id, wallet_address | user_id, user_address |
POST /api/v1/user/retail/validate | id, wallet_address | user_id, user_address |
GET /api/v1/cards/3ds/requests, POST {your_webhook_base_url}/v2/webhooks/3ds | owner | user_address |
GET /api/v1/withdrawal/requests, POST {your_webhook_base_url}/v2/webhooks/erc-withdrawals | account_address, to_address | wallet_address, destination_address |
POST /api/v1/fx/estimate | deposit_address | destination_address |
POST /api/v1/activity/statement/full | owner, account_address | user_address, wallet_address |
Recipient crypto payment details, on create, update, read, and POST {your_webhook_base_url}/v2/webhooks/recipients | address | recipient_address |
Compatibility
- Responses carry both the old and the new field. Both hold the same value.
- Requests accept either field. Supplying both is allowed only when they match; mismatched values fail validation.
- Nothing has been removed. Read the new names in new code and migrate existing readers when convenient.
Requirements
wallet_address now means two different things depending on where it appears, so a blanket find-and-replace will break an integration:
- On user registration and user profile payloads it was the user's EOA, and is replaced by
user_address. - On withdrawal payloads and statement operations it is the Smart Wallet address, and is the new preferred name there, replacing
account_address.
The wallets webhook, the balances webhook, GET /api/v1/wallets, and the XRPL POST /api/v1/accounts response are unaffected — wallet_address was already correct in all of them.
The TypeScript SDK has not been updated. It still sends wallet_address on user creation and still exposes account_address and to_address on withdrawal records. Both continue to work.
Also in this release
- Three webhooks are now documented —
/v2/webhooks/user,/v2/webhooks/debt-cases, and/v2/webhooks/corporationsare delivered to configured webhook endpoints and now have published payloads and field tables. The user webhook is the v2 replacement for the legacy/webhook/users. - 3DS error handling corrected — the approve and decline endpoints never return
401. A transaction that is unknown, already decided, expired, or owned by another user returns the same400withErrorNotFound, because ownership is enforced by scoping the lookup to the caller. The documented 5-minute expiry window and the guarantee that a decision cannot be replayed are now described in 3DS Authentication. - Card limit webhook — the field table listed an
ownerfield that is not sent. It has been removed. - KYC Sharing via API — the integration guide is now published.