List Active Payment Streams — GET /api/payments/stream

This endpoint returns all streams visible to your API key, enriched with real-time balance calculations. For each ACTIVE stream, the API computes currentStreamed (USDC paid out so far), remainingBalance (USDC still locked), secondsRemaining, and percentComplete from the stream’s start time and rate — no on-chain read required. The top-level metrics object gives you an instant dashboard view across all streams. You can narrow results using sender, receiver, status, or reference query parameters.

Endpoint

GET https://flarehq.xyz/api/payments/stream

Authentication

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

x-api-key: fhq_sec_...

Query Parameters

string

Filter by sender SCA wallet address. Returns only streams where senderSCA matches this value exactly.

string

Filter by receiver SCA wallet address. Returns only streams where receiverSCA matches this value exactly.

string

Filter by stream state. One of "ACTIVE", "STOPPED", or "COMPLETED". Omit to return all statuses.

string

Fetch a single stream by its exact reference ID — e.g. "stream_n2p4q8_f3g7h1".

Response

boolean

true when the query succeeded.

object

Aggregate statistics across the filtered result set.

Show metrics fields

number

Total number of streams matching the query.

number

Count of streams with status "ACTIVE".

number

Count of streams with status "STOPPED".

number

Count of streams with status "COMPLETED".

number

Sum of remainingBalance across all ACTIVE streams — total USDC currently locked in the contract.

number

Combined USDC-per-second rate across all ACTIVE streams.

array

Array of enriched stream objects, ordered by startedAt descending.

Show stream object fields

string

Stream reference ID.

string

"ACTIVE", "STOPPED", or "COMPLETED".

string

Payer’s SCA wallet address.

string

Recipient’s SCA wallet address.

number

USDC accrued per second.

number

Total USDC locked at stream creation.

number

USDC paid to the receiver as of the moment this response was generated (live calculation, to 6 decimal places).

number

USDC still locked in the contract — totalDeposited - currentStreamed.

number

Estimated seconds until the stream is exhausted. 0 for stopped or completed streams.

number

Percentage of totalDeposited that has been streamed, to 2 decimal places — e.g. 17.45.

string

ISO 8601 timestamp when the stream was created.

string | null

ISO 8601 timestamp when the stream was stopped or completed. null for active streams.

string

On-chain transaction hash for the stream creation transaction.

string | null

ArcScan link for the creation transaction.

string

Always "USDC".

string

The stream contract address holding the locked funds on Arc testnet.

Examples

curl "https://flarehq.xyz/api/payments/stream?sender=0xSenderSCAWalletAddress&status=ACTIVE" \
  -H "x-api-key: fhq_sec_YOUR_KEY"

curl "https://flarehq.xyz/api/payments/stream" \
  -H "x-api-key: fhq_sec_YOUR_KEY"

// Fetch all active streams and log remaining USDC
const response = await fetch(
  "https://flarehq.xyz/api/payments/stream?status=ACTIVE",
  { headers: { "x-api-key": "fhq_sec_YOUR_KEY" } }
);

const { metrics, streams } = await response.json();
console.log(`Active streams: ${metrics.active}`);
console.log(`Total locked USDC: ${metrics.totalLockedUSDC}`);

streams.forEach((s) => {
  console.log(`${s.reference}: ${s.remainingBalance} USDC remaining, ${s.secondsRemaining}s left`);
});

Success Response

{
  "success": true,
  "metrics": {
    "total":              3,
    "active":             2,
    "stopped":            1,
    "completed":          0,
    "totalLockedUSDC":    874.109231,
    "totalRatePerSecond": 0.000579
  },
  "streams": [
    {
      "reference":        "stream_n2p4q8_f3g7h1",
      "status":           "ACTIVE",
      "senderSCA":        "0xSenderSCAWalletAddress",
      "receiverSCA":      "0xReceiverSCAWalletAddress",
      "ratePerSecond":    0.000193,
      "totalDeposited":   500,
      "currentStreamed":  87.234512,
      "remainingBalance": 412.765488,
      "secondsRemaining": 2139978,
      "percentComplete":  17.45,
      "startedAt":        "2025-07-14T12:00:00.000Z",
      "stoppedAt":        null,
      "txHash":           "0xfff000eee111ddd222ccc333bbb444aaa555999888777666555444333222111",
      "explorerUrl":      "https://testnet.arcscan.app/tx/0xfff000eee111...",
      "currency":         "USDC",
      "contractAddress":  "0xc9BbeDFb142b6306c34838a39521c894F3dbc872"
    },
    {
      "reference":        "stream_p9r1s3_k2l5m8",
      "status":           "ACTIVE",
      "senderSCA":        "0xSenderSCAWalletAddress",
      "receiverSCA":      "0xAnotherReceiverSCA",
      "ratePerSecond":    0.000386,
      "totalDeposited":   500,
      "currentStreamed":  38.656257,
      "remainingBalance": 461.343743,
      "secondsRemaining": 1194672,
      "percentComplete":  7.73,
      "startedAt":        "2025-07-14T13:30:00.000Z",
      "stoppedAt":        null,
      "txHash":           "0x222bbb333ccc444ddd555eee666fff777888999000aaabbb111222333444555",
      "explorerUrl":      "https://testnet.arcscan.app/tx/0x222bbb333ccc...",
      "currency":         "USDC",
      "contractAddress":  "0xc9BbeDFb142b6306c34838a39521c894F3dbc872"
    },
    {
      "reference":        "stream_a1b2c3_d4e5f6",
      "status":           "STOPPED",
      "senderSCA":        "0xSenderSCAWalletAddress",
      "receiverSCA":      "0xOldReceiverSCA",
      "ratePerSecond":    0.001157,
      "totalDeposited":   100,
      "currentStreamed":  45.230000,
      "remainingBalance": 54.770000,
      "secondsRemaining": 0,
      "percentComplete":  45.23,
      "startedAt":        "2025-07-13T08:00:00.000Z",
      "stoppedAt":        "2025-07-13T19:05:00.000Z",
      "txHash":           "0x999ccc888ddd777eee666fff555000444aaa333bbb222ccc111ddd000eee999",
      "explorerUrl":      "https://testnet.arcscan.app/tx/0x999ccc888ddd...",
      "currency":         "USDC",
      "contractAddress":  "0xc9BbeDFb142b6306c34838a39521c894F3dbc872"
    }
  ]
}

currentStreamed and remainingBalance are computed server-side at response time using ratePerSecond × elapsedSeconds. For stopped or completed streams the calculation uses stoppedAt rather than the current time, so those values are stable.

Overview

Payments

Escrow

Streaming

x402

Agents

List Active Payment Streams — GET /api/payments/stream

Endpoint

Authentication

Query Parameters

Response

Examples

Success Response

​Endpoint

​Authentication

​Query Parameters

​Response

​Examples

​Success Response

Endpoint

Authentication

Query Parameters

Response

Examples

Success Response