Stop Payment Stream — POST /api/payments/stream/stop

Stopping a stream immediately halts all further USDC accrual. The on-chain contract calculates how much USDC the receiver has earned up to that exact second, sends that amount to the receiver, and returns the remaining unstreamed balance to the sender. The stream record is updated to STOPPED. Only the sender’s SCA address may stop a stream.

The callerSCA must match the senderSCA recorded at stream creation. Attempting to stop a stream from a different address will cause the on-chain transaction to revert.

Endpoint

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

Authentication

Pass your API key in the x-api-key header.

x-api-key: fhq_sec_...

Request Body

string

required

The stream reference ID from POST /api/payments/stream — e.g. "stream_n2p4q8_f3g7h1".

string

required

The sender’s SCA wallet address. Must match the senderSCA recorded when the stream was created.

Response

boolean

true when the stream was stopped and the on-chain transaction confirmed.

object

The updated stream record.

Show stream fields

string

Always "STOPPED" on success.

number

Total USDC paid to the receiver before the stream was halted, to 6 decimal places.

string

ISO 8601 timestamp of when the stream was stopped.

string

On-chain transaction hash for the stream stop transaction.

string

ArcScan link — https://testnet.arcscan.app/tx/{txHash}.

number

USDC delivered to the receiver up to the stop point — e.g. 87.234512.

number

Unstreamed USDC returned to the sender’s wallet — totalDeposited - totalStreamed, e.g. 412.765488.

string

A human-readable summary showing how much was streamed and how much was refunded.

Examples

curl -X POST https://flarehq.xyz/api/payments/stream/stop \
  -H "x-api-key: fhq_sec_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "stream_n2p4q8_f3g7h1",
    "callerSCA": "0xSenderSCAWalletAddress"
  }'

const response = await fetch("https://flarehq.xyz/api/payments/stream/stop", {
  method: "POST",
  headers: {
    "x-api-key":    "fhq_sec_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    reference: "stream_n2p4q8_f3g7h1",
    callerSCA: "0xSenderSCAWalletAddress",
  }),
});

const data = await response.json();
console.log(`Streamed: ${data.totalStreamed} USDC`);
console.log(`Refunded: ${data.refundedToSender} USDC`);

Success Response

{
  "success": true,
  "stream": {
    "reference":     "stream_n2p4q8_f3g7h1",
    "status":        "STOPPED",
    "totalStreamed":  87.234512,
    "stoppedAt":     "2025-07-14T18:22:10.000Z"
  },
  "txHash":           "0x888aaa777bbb666ccc555ddd444eee333fff222111000999888777666555444",
  "explorerUrl":      "https://testnet.arcscan.app/tx/0x888aaa777bbb666...",
  "totalStreamed":     87.234512,
  "refundedToSender": 412.765488,
  "message":          "Stream stopped — 87.234512 USDC streamed, 412.765488 USDC refunded to sender."
}

Error — Stream Already Stopped

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

Error — Stream Not Found

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

Webhook Payload (`stream.stopped`)

When a webhookUrl was registered at stream creation, FlareHQ delivers the following event:

{
  "event":            "stream.stopped",
  "reference":        "stream_n2p4q8_f3g7h1",
  "totalStreamed":     87.234512,
  "refundedToSender": 412.765488,
  "txHash":           "0x888aaa777bbb666ccc555ddd444eee333fff222111000999888777666555444",
  "stoppedAt":        "2025-07-14T18:22:10.000Z",
  "explorerUrl":      "https://testnet.arcscan.app/tx/0x888aaa777bbb666..."
}

The receiver’s accrued balance is automatically sent to them when the stream is stopped on-chain — they do not need to call /withdraw separately after a stream is stopped.

Overview

Payments

Escrow

Streaming

x402

Agents

Stop Payment Stream — POST /api/payments/stream/stop

Endpoint

Authentication

Request Body

Response

Examples

Success Response

Error — Stream Already Stopped

Error — Stream Not Found

Webhook Payload (`stream.stopped`)

​Endpoint

​Authentication

​Request Body

​Response

​Examples

​Success Response

​Error — Stream Already Stopped

​Error — Stream Not Found

​Webhook Payload (stream.stopped)

Endpoint

Authentication

Request Body

Response

Examples

Success Response

Error — Stream Already Stopped

Error — Stream Not Found

Webhook Payload (`stream.stopped`)