Skip to main content
DELETE /v2/merchant/wallet/:walletAddress?network=base removes a previously registered settlement wallet from the merchant’s claim list. After deregistration, settlements that would have routed to this address no longer do — set a new primary via POST /v2/merchant/wallet/claim before settling fresh revenue.
Live on dev as of 2026-06-14; PROD ETA after next GTFU. Shipped via PR #2103 (Phase 5.4.7).

​
DELETE /v2/merchant/wallet/:walletAddress

​
Authentication

GuardRequirement
JWTRequired, any authenticated merchant role
ScopemerchantId derived from JWT sub — not from URL / query
Obtain a merchant JWT via POST /merchant/admin/login — see Authentication.

​
Path parameters

ParamTypeRequiredDescription
walletAddressstringYesEVM address to deregister, 0x + 40 hex chars. Case-insensitive — 0xB272… and 0xb272… match the same row via EIP-55 dedup.

​
Query parameters

ParamTypeRequiredDefaultDescription
networkstringNobaseSettlement network. MVP supports base only.

​
Example

curl -X DELETE \
  "https://apiv3.droplinked.com/v2/merchant/wallet/0xB2721aD4F1c4dD8fE45F3F3c8e4F8c8c5d5f1eA9?network=base" \
  -H "Authorization: Bearer <MERCHANT_JWT>"

​
Response — 200 OK (wallet existed)

{
  "deregistered": true,
  "walletAddress": "0xB2721aD4F1c4dD8fE45F3F3c8e4F8c8c5d5f1eA9",
  "network": "base"
}

​
Response — 200 OK (wallet never claimed)

{
  "deregistered": false,
  "walletAddress": "0xB2721aD4F1c4dD8fE45F3F3c8e4F8c8c5d5f1eA9",
  "network": "base"
}

​
Fields

FieldTypeNullableDescription
deregisteredbooleanNotrue when a row was actually removed. false when the address was not registered for this (merchantId, network) — the call still returns 200 (see Notes).
walletAddressstringNoEchoed input address.
networkstringNoEchoed network.

​
Errors

StatusBodyWhen
400{ "statusCode": 400, "status": "failed", "data": { "message": "walletAddress must match the EVM 0x+40-hex shape" } }walletAddress fails the ^0x[a-fA-F0-9]{40}$ shape check, or network is anything other than base.
401{ "statusCode": 401, "status": "failed", "data": { "message": "Unauthorized" } }Missing or invalid JWT.
5xx{ "statusCode": 500, "status": "failed", ... }DB delete failure.

​
Notes

  • Idempotent on the dedup key. Deregistering a wallet that was never claimed (or has already been removed) returns 200 with deregistered: false. Clients can safely retry without checking membership first. This mirrors the POST idempotency contract — the pair forms a clean upsert / delete API.
  • Mixed-case lookup. Path-parameter casing is normalized to lowercase before lookup, so 0xB272…eA9 and 0xb272…ea9 resolve to the same row.
  • Primary-flag side-effect. Deregistering the current primary leaves the merchant with no primary on that network. Settlement routing falls back to the merchant’s account-level settlement target (if configured) or the platform escrow until a new primary is claimed.
  • No 404 for unknown rows. Choice is deliberate: the dedup key is the natural identity of the resource, and “not present” is a valid terminal state of DELETE for that identity. Returning 404 would force every client to add a pre-check; instead the response itself carries the membership signal via deregistered.
  • Auth scope. A merchant cannot deregister another merchant’s wallet even if they know the address — the merchantId:network:wallet composite is the lookup key and merchantId always comes from the JWT.
  • Audit trail. Every deregister emits a PlatformAuditEvent (OPERATOR_ACTION, subjectType MERCHANT_WALLET_CLAIM) for the compliance trail, including the no-op cases where deregistered: false.