Withdraw — POST /api/merchant/withdraw

The withdraw endpoint moves USDC out of a Circle-managed merchant wallet to any external address the merchant controls. It is only available to merchants with a Circle-managed payout wallet — external-wallet merchants already hold the keys to their settlement wallet, so there is nothing to withdraw. On success the response returns the on-chain transaction hash and an explorer URL.

Endpoint

POST https://flarehq.xyz/api/merchant/withdraw

Request

Headers

Header	Value
`Cookie`	`merchant_token=...` — required
`Content-Type`	`application/json` — required

This is a browser/dashboard route authenticated by the merchant_token cookie set at login. It is additionally rate-limited on a stricter tier than other routes because it touches payout routing.

Body Parameters

string

required

A valid EVM 0x... address to receive the USDC. Validated with isAddress.

string | number

required

Withdrawal amount in USDC (human-readable units). Must be a positive number and must not exceed the wallet’s available balance.

Response

boolean

true on a successful transfer.

string

The on-chain transaction hash of the USDC transfer to the destination address.

string

Link to view the transaction on the Arc Mainnet block explorer: https://explorer.arc.io/tx/{txHash}

number

The withdrawal amount, echoed from the request.

string

Always "USDC".

string

The merchant’s Circle-managed payout wallet address the funds left from.

string

The destination address the funds were sent to.

Examples

curl -X POST https://flarehq.xyz/api/merchant/withdraw \
  -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{
    "destinationAddress": "0x9f2a1c3e5b7d4a6f8c0e2b9a1d3f5c7e9a0b2d4f",
    "amount": "150.00"
  }'

const res = await fetch('https://flarehq.xyz/api/merchant/withdraw', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    destinationAddress: '0x9f2a1c3e5b7d4a6f8c0e2b9a1d3f5c7e9a0b2d4f',
    amount: '150.00',
  }),
});

const { success, txHash, explorerUrl } = await res.json();

Success Response

{
  "success": true,
  "txHash": "0x5f1e0c8b7d99a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8",
  "explorerUrl": "https://explorer.arc.io/tx/0x5f1e0c8b7d99a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8",
  "amount": 150,
  "currency": "USDC",
  "from": "0x4a2F1b9c7dE03A6b8C5f2e9D1a4c7B6e3F9d2A8",
  "to": "0x9f2a1c3e5b7d4a6f8c0e2b9a1d3f5c7e9a0b2d4f"
}

Error Responses

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

{
  "success": false,
  "error": "Withdrawals are only available for Circle-managed payout wallets."
}

{
  "success": false,
  "error": "A valid destination address is required."
}

{
  "success": false,
  "error": "A valid withdrawal amount is required."
}

{
  "success": false,
  "error": "Insufficient balance. Available: 89.5 USDC."
}

Notes

The wallet balance is checked against Circle’s ledger before the transfer is broadcast. If the requested amount exceeds the available balance, the request fails with HTTP 400 and includes the exact available balance in the error message.

Withdrawals are irreversible on-chain once broadcast. Verify the destinationAddress carefully before signing — a mistyped address means permanently lost funds.

Overview

Payments

Escrow

Streaming

CCTP Bridge

Checkout

x402

Agents

Jobs

Merchant

Consumer

Payroll

Withdraw — POST /api/merchant/withdraw

Endpoint

Request

Headers

Body Parameters

Response

Examples

Success Response

Error Responses

Notes

​Endpoint

​Request

​Headers

​Body Parameters

​Response

​Examples

​Success Response

​Error Responses

​Notes

Endpoint

Request

Headers

Body Parameters

Response

Examples

Success Response

Error Responses

Notes