Wallet linking

Link or unlink wallet addresses and verify a switch to the customer account that already owns a wallet. Wallet address validation and normalization belong to the web3 service.

Access labels such as Origin + Brand key + Customer are defined in Headers and access. Each endpoint ends in a Try it console; set the host and keys once in its Settings tab or on the overview.

Link wallet

Link a wallet to the current customer. An existing owner can trigger the account-switch flow.

Method	URL path	Required access
POST	/api/v1/brand/wallet/link	Origin + Brand key + Customer

Request fields:

Field	Type	Required	Rules / meaning
body.payload	object	yes	—
body.payload.walletAddress	string	yes	Whitespace trimmed
body.payload.provider	string	optional	Whitespace trimmed

HTTP 409 returns {success:false,error:"Wallet is linked to another account",result:{status:"owned_by_other_account",maskedEmail:"..."}}. Use the switch-OTP endpoints to continue.

Example:

curl -X POST "$BASE_URL/api/v1/brand/wallet/link" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-raw '{"payload":{"walletAddress":"<WALLET_ADDRESS>"}}'

Response: JSON with success: true and result containing the operation’s service data.

Source: app/v1/controller/wallet_link_controller.ts:44 → linkWallet; routes: routes/v1/wallet_link_route.ts:9; service: _linkWallet (app/v1/service/wallet_link_service.ts:66).

Get wallet links

List wallets linked to the current customer within the brand or organization scope.

Method	URL path	Required access
GET	/api/v1/brand/wallet/links	Origin + Brand key + Customer

Request fields: no body, query, or path fields are read by this controller. Context comes from the headers/middleware above.

Example:

curl -X GET "$BASE_URL/api/v1/brand/wallet/links" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN"

Response: JSON with success: true and result containing the operation’s service data.

Source: app/v1/controller/wallet_link_controller.ts:68 → getWalletLinks; routes: routes/v1/wallet_link_route.ts:20; service: _getWalletLinks (app/v1/service/wallet_link_service.ts:115).

Unlink wallet

Remove a wallet link from the current customer.

Method	URL path	Required access
POST	/api/v1/brand/wallet/unlink	Origin + Brand key + Customer

Request fields:

Field	Type	Required	Rules / meaning
body.payload	object	yes	—
body.payload.walletAddress	string	yes	Whitespace trimmed

Example:

curl -X POST "$BASE_URL/api/v1/brand/wallet/unlink" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-raw '{"payload":{"walletAddress":"<WALLET_ADDRESS>"}}'

Response: JSON with success: true and result containing the operation’s service data.

Source: app/v1/controller/wallet_link_controller.ts:81 → unlinkWallet; routes: routes/v1/wallet_link_route.ts:30; service: _unlinkWallet (app/v1/service/wallet_link_service.ts:153).

Send wallet switch OTP

Send a verification code for switching to the account that owns the wallet.

Method	URL path	Required access
POST	/api/v1/brand/wallet/switch/send-otp	Origin + Brand key + Customer

Request fields:

Field	Type	Required	Rules / meaning
body.payload	object	yes	—
body.payload.walletAddress	string	yes	Whitespace trimmed
body.payload.provider	string	optional	Whitespace trimmed

Example:

curl -X POST "$BASE_URL/api/v1/brand/wallet/switch/send-otp" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-raw '{"payload":{"walletAddress":"<WALLET_ADDRESS>"}}'

Response: JSON with success: true and result containing the operation’s service data. Result fields/details: message, maskedEmail.

Source: app/v1/controller/wallet_link_controller.ts:102 → sendWalletSwitchOtp; routes: routes/v1/wallet_link_route.ts:40; service: _sendWalletSwitchOtp (app/v1/service/wallet_link_service.ts:222).

Verify wallet switch OTP

Verify the wallet-switch code and return a customer token for the owning account.

Method	URL path	Required access
POST	/api/v1/brand/wallet/switch/verify-otp	Origin + Brand key + Customer

Request fields:

Field	Type	Required	Rules / meaning
body.payload	object	yes	—
body.payload.walletAddress	string	yes	Whitespace trimmed
body.payload.otp	string	yes	Whitespace trimmed

Example:

curl -X POST "$BASE_URL/api/v1/brand/wallet/switch/verify-otp" \
  -H "Origin: $ORIGIN" \
  -H "api-key: $API_KEY" \
  -H "Authorization: Bearer $CUSTOMER_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-raw '{"payload":{"walletAddress":"<WALLET_ADDRESS>","otp":"123456"}}'

Response: JSON with success: true and result containing the operation’s service data. Result fields/details: message, token, userId.

Source: app/v1/controller/wallet_link_controller.ts:126 → verifyWalletSwitchOtp; routes: routes/v1/wallet_link_route.ts:50; service: _verifyWalletSwitchOtp (app/v1/service/wallet_link_service.ts:280).

Lifecycle

Linking and unlinking are forwarded to the web3 service. The account switch — for a wallet that belongs to another customer — is handled here:

• 409 carries result.status: "owned_by_other_account" and the owner's maskedEmail.
• send-otp emails the code to the owning account. It is refused if the wallet is not linked to any account, is already linked to the caller, or the owner is banned or has no email address.
• verify-otp checks the code, marks the owning account verified, and returns a customer token for it. The page replaces its token with this one: from here on it is acting as the wallet's owner.

Related pages

• Batch Commerce API overview
• Wallets and NFT prizes
• Implementation notes