Skip to main content
GET /v2/merchant/wallet/registered returns the list of settlement wallets the authenticated merchant has registered via POST /v2/merchant/wallet/claim. This endpoint backs the merchant Wallets panel in the dashboard.
Live on dev as of 2026-06-14; PROD ETA after next GTFU. Shipped via PR #2103 (Phase 5.4.7).

​
GET /v2/merchant/wallet/registered

​
Authentication

GuardRequirement
JWTRequired, any authenticated merchant role
ScopemerchantId derived from JWT sub — not from query / body
Obtain a merchant JWT via POST /merchant/admin/login — see Authentication. Any ?merchantId= query parameter is silently ignored.

​
Query parameters

None. The response is always the full list for the JWT-bound merchant across all networks.

​
Example

curl "https://apiv3.droplinked.com/v2/merchant/wallet/registered" \
  -H "Authorization: Bearer <MERCHANT_JWT>"

​
Response — 200 OK

{
  "wallets": [
    {
      "walletAddress": "0xB2721aD4F1c4dD8fE45F3F3c8e4F8c8c5d5f1eA9",
      "network": "base",
      "label": "Mainnet Treasury",
      "isPrimary": true,
      "claimedAt": "2026-06-14T17:30:00.000Z",
      "lastVerifiedAt": "2026-06-14T17:31:00.000Z"
    }
  ],
  "asOf": "2026-06-14T17:31:05.220Z"
}

​
Fields

FieldTypeNullableDescription
walletsarrayNoOne entry per registered wallet for the merchant, across all networks. Empty array for merchants who have never claimed a wallet.
wallets[].walletAddressstringNoThe address as the merchant originally submitted it (EIP-55 case preserved).
wallets[].networkstringNoSettlement network (base in MVP).
wallets[].labelstringYesOperator-supplied label. null when none was supplied.
wallets[].isPrimarybooleanNoWhether this row is the primary settlement target on network. At most one per (merchantId, network).
wallets[].claimedAtISO-8601 stringNoOriginal claim timestamp (UTC).
wallets[].lastVerifiedAtISO-8601 stringNoMost-recent claim-call timestamp (UTC). Refreshed on every re-claim.
asOfISO-8601 stringNoSnapshot timestamp (server clock, UTC).

​
Errors

StatusBodyWhen
401{ "statusCode": 401, "status": "failed", "data": { "message": "Unauthorized" } }Missing or invalid JWT
5xx{ "statusCode": 500, "status": "failed", ... }Hard backend failure — see Notes below

​
Notes

  • Caching. The response carries Cache-Control: private, max-age=30. Clients should expect up to a 30s lag after a claim / deregister before the change is visible if the response was cached by an intermediate.
  • Auth scope. The endpoint reads merchantId from the JWT sub claim only. Any ?merchantId= query parameter is silently ignored. A merchant cannot read another merchant’s wallets through this endpoint.
  • Ordering. Rows are sorted by claimedAt descending — most-recently claimed first. Primary status does not affect order; check isPrimary to identify the routed-to wallet.
  • Fail-open semantics. If the underlying read throws, the endpoint returns the empty-state envelope (wallets: []) with 200 OK rather than propagating the error. Inspect server logs / Sentry for the underlying failure. Merchants never see a partial Wallets-panel error in the dashboard.
  • Across networks. The list is not filtered by network. A merchant registered on base today and a future second network tomorrow will see both rows here; clients filter client-side as needed.