Merchant Wallet — GET/PATCH /api/merchant/wallet

The wallet endpoint manages the merchant’s payout wallet. GET returns the currently configured wallet, and PATCH switches the payout wallet back to a freshly provisioned Circle-managed wallet. Switching to an external wallet (MetaMask, WalletConnect, Coinbase) is not handled here — it requires the signed SIWE flow at GET/POST /api/merchant/wallet/connect.

Endpoint

GET    https://flarehq.xyz/api/merchant/wallet
PATCH  https://flarehq.xyz/api/merchant/wallet

Request

Headers

Header	Value
`Cookie`	`merchant_token=...` — required

Both verbs are browser/dashboard routes authenticated by the merchant_token cookie set at login.

GET

No body or query parameters.

PATCH Body Parameters

string

required

Must be "CIRCLE". This endpoint only switches back to a Circle-managed wallet; any other value is rejected with HTTP 400.

Response

GET — Success

boolean

true on success.

object

The merchant’s current payout wallet.

Show wallet fields

string

Wallet provider, e.g. "CIRCLE" or an external kind.

string

The configured payout wallet address.

string | null

Circle wallet ID — set only when walletProvider is "CIRCLE", otherwise null.

PATCH — Success

boolean

true on success.

string

"A new Circle-managed wallet has been created for your payouts."

object

The newly created wallet.

Show wallet fields

string

Always "CIRCLE" after this call.

string

The new Circle-managed payout wallet address.

Examples

curl https://flarehq.xyz/api/merchant/wallet \
  -b cookies.txt

curl -X PATCH https://flarehq.xyz/api/merchant/wallet \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{ "walletProvider": "CIRCLE" }'

const res = await fetch('https://flarehq.xyz/api/merchant/wallet', {
  method: 'PATCH',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ walletProvider: 'CIRCLE' }),
});

const { success, message, wallet } = await res.json();

GET — Success Response

{
  "success": true,
  "wallet": {
    "walletProvider": "CIRCLE",
    "walletAddress": "0x4a2F1b9c7dE03A6b8C5f2e9D1a4c7B6e3F9d2A8",
    "circleWalletId": "wallet_01jb2k9x..."
  }
}

PATCH — Success Response

{
  "success": true,
  "message": "A new Circle-managed wallet has been created for your payouts.",
  "wallet": {
    "walletProvider": "CIRCLE",
    "walletAddress": "0x8bE2f7aD34C9b0d1e5F6a2c8B7d4E9f1A3c5D6b0"
  }
}

Error Responses

{
  "success": false,
  "error": "Not authenticated."
}

{
  "success": false,
  "error": "This endpoint only switches back to a Circle-managed wallet. To connect an external wallet (MetaMask, WalletConnect, Coinbase), use GET/POST /api/merchant/wallet/connect — it requires signing a message to prove ownership."
}

{
  "success": false,
  "error": "You already have a Circle-managed wallet."
}

Notes

PATCH provisions a brand-new Circle wallet. If you previously had a Circle wallet, switched away, and switch back, the old wallet is not restored — its wallet ID was overwritten when you switched away, so it is not recoverable through this flow.

Switching your payout wallet redirects where settlements land. Only call PATCH when you are ready for future payouts to go to the newly created Circle-managed address.

Overview

Payments

Escrow

Streaming

CCTP Bridge

Checkout

x402

Agents

Jobs

Merchant

Consumer

Payroll

Merchant Wallet — GET/PATCH /api/merchant/wallet

Endpoint

Request

Headers

GET

PATCH Body Parameters

Response

GET — Success

PATCH — Success

Examples

GET — Success Response

PATCH — Success Response

Error Responses

Notes

​Endpoint

​Request

​Headers

​GET

​PATCH Body Parameters

​Response

​GET — Success

​PATCH — Success

​Examples

​GET — Success Response

​PATCH — Success Response

​Error Responses

​Notes

Endpoint

Request

Headers

GET

PATCH Body Parameters

Response

GET — Success

PATCH — Success

Examples

GET — Success Response

PATCH — Success Response

Error Responses

Notes