Withdraw from Stream — POST /api/payments/stream/withdraw

While a stream is ACTIVE, USDC accrues to the receiver at ratePerSecond for every elapsed second. This endpoint lets the receiver claim the accrued, not-yet-withdrawn balance on-chain. When the claimed amount brings totalStreamed up to totalDeposited, the stream transitions to COMPLETED and is stopped. The route is strict about identity: the receiverSCA you pass must match the stream’s actual receiver, and the caller must prove they control that wallet (via the API key’s associated merchant wallet or the Circle-custodied receiver address).

The withdrawal is executed on-chain on Arc Mainnet. If the stream’s receiver is a merchant wallet, the route may require a signature approval (pendingSignature) before the transfer completes.

Endpoint

POST https://flarehq.xyz/api/payments/stream/withdraw

Request

Headers

Header	Value
`x-api-key`	`fhq_sec_test_...` — required
`Content-Type`	`application/json` — required

Body Parameters

string

required

The stream reference (e.g. "stream_n2p4q8_f3g7h1") returned by create stream.

string

required

SCA wallet address of the stream’s receiver. Must exactly match the stream’s receiverSCA, and the caller must control this wallet.

Response

boolean

true when the withdrawal was submitted on-chain.

object

The updated stream record.

Show stream fields

string

"COMPLETED" when totalStreamed has reached totalDeposited; otherwise stays "ACTIVE".

number

Cumulative USDC paid to the receiver after this withdrawal.

string

The stream reference.

string

The stream sender’s SCA address.

string

The stream receiver’s SCA address.

number

Per-second rate as a float — e.g. 0.000193.

number

Total USDC locked — e.g. 500.

string

Always "USDC".

string

The stream contract address on Arc Mainnet.

string

On-chain transaction hash for the withdrawal.

string

Arc Explorer link — https://explorer.arc.io/tx/{txHash}.

number

USDC claimed in this withdrawal, calculated as max(0, min(ratePerSecond * elapsedSeconds, totalDeposited) - totalStreamed).

number

Cumulative USDC paid to the receiver after this withdrawal (mirrors stream.totalStreamed).

boolean

true when this withdrawal exhausted the deposited balance and the stream transitioned to COMPLETED.

string

Human-readable confirmation, e.g. "0.500000 USDC withdrawn from stream.".

Examples

curl -X POST https://flarehq.xyz/api/payments/stream/withdraw \
  -H "x-api-key: fhq_sec_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "reference":   "stream_n2p4q8_f3g7h1",
    "receiverSCA": "0xReceiverSCAWalletAddress"
  }'

const res = await fetch('https://flarehq.xyz/api/payments/stream/withdraw', {
  method: 'POST',
  headers: {
    'x-api-key': 'fhq_sec_test_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    reference: 'stream_n2p4q8_f3g7h1',
    receiverSCA: '0xReceiverSCAWalletAddress',
  }),
});

const { amountWithdrawn, completed, txHash } = await res.json();
console.log(amountWithdrawn, completed, txHash);

Success Response

{
  "success": true,
  "stream": {
    "reference": "stream_n2p4q8_f3g7h1",
    "status": "COMPLETED",
    "senderSCA": "0xSenderSCAWalletAddress",
    "receiverSCA": "0xReceiverSCAWalletAddress",
    "ratePerSecond": 0.000193,
    "totalDeposited": 500,
    "totalStreamed": 500,
    "currency": "USDC",
    "contractAddress": "0xc9BbeDFb142b6306c34838a39521c894F3dbc872"
  },
  "txHash": "0xbbb222ccc333ddd444eee555fff666777888999000111222333444555666777",
  "explorerUrl": "https://explorer.arc.io/tx/0xbbb222ccc333ddd444eee555fff666777888999000111222333444555666777",
  "amountWithdrawn": 1.2,
  "totalStreamed": 500,
  "completed": true,
  "message": "1.200000 USDC withdrawn from stream."
}

Merchant Wallet — Pending Signature

{
  "success": true,
  "pendingSignature": true,
  "requestId": "sig_req_9f2c1d8e...",
  "message": "Your wallet needs to approve this withdrawal — check /api/merchant/wallet/sign-requests."
}

Error Responses

{
  "success": false,
  "error": "reference and receiverSCA are required."
}

{
  "success": false,
  "error": "Stream not found."
}

{
  "success": false,
  "error": "Stream is STOPPED."
}

{
  "success": false,
  "error": "receiverSCA is not the receiver of this stream."
}

{
  "success": false,
  "error": "You do not control the wallet named in receiverSCA."
}

{
  "success": false,
  "error": "No USDC available to withdraw yet."
}

Notes

The claimable amount is computed at call time as min(ratePerSecond * elapsedSeconds, totalDeposited) - totalStreamed. If nothing has accrued beyond what was already streamed, the request fails with HTTP 400 (“No USDC available to withdraw yet”).

When a withdrawal exhausts the deposited balance, the stream transitions to COMPLETED and a stream.completed webhook fires; otherwise a stream.withdrawn webhook fires. Both include reference, receiverSCA, amountWithdrawn, totalStreamed, txHash, and an explorerUrl.

Only the stream’s receiver may withdraw, and the caller must control the receiverSCA wallet. On-chain confirmation can take up to ~75 seconds — the route waits for confirmation before returning, so do not retry in parallel during that window.

Overview

Payments

Escrow

Streaming

CCTP Bridge

Checkout

x402

Agents

Jobs

Merchant

Consumer

Payroll

Withdraw from Stream — POST /api/payments/stream/withdraw

Endpoint

Request

Headers

Body Parameters

Response

Examples

Success Response

Merchant Wallet — Pending Signature

Error Responses

Notes

​Endpoint

​Request

​Headers

​Body Parameters

​Response

​Examples

​Success Response

​Merchant Wallet — Pending Signature

​Error Responses

​Notes

Endpoint

Request

Headers

Body Parameters

Response

Examples

Success Response

Merchant Wallet — Pending Signature

Error Responses

Notes