Deregister Settlement Wallet (Merchant)

​

DELETE /v2/merchant/wallet/:walletAddress

​

Authentication

​

Path parameters

​

Query parameters

​

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

​

Errors

​

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.

​

Related

• Register Settlement Wallet — POST counterpart that creates / re-verifies a wallet entry.
• List Registered Wallets — GET counterpart for the current set of registered wallets.
• x402 Earnings (Merchant) — per-merchant rollup of settlement events affected by deregistration.