> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macropay.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Stream Strategy

> Meter bytes flowing through any Node Readable or Writable stream — no manual event calls

If you bill by data volume — file transfers, log shipping, media transcoding, model output streamed token by token — the number you care about is **bytes moved**. The Stream Strategy wraps any Node `Readable` or `Writable` stream and counts those bytes for you, emitting a metered event to Macropay as the data flows. No counters to maintain, no `track()` calls sprinkled through your handler.

Every byte you meter rolls up into a [meter](/features/usage-based-billing/meters) you can attach to a metered price. And because Macropay is your [Merchant of Record](/features/usage-based-billing/introduction), the tax and VAT on whatever you charge for that usage is calculated, collected, and remitted for you — globally.

## Install

```bash theme={null}
pnpm add @macropayments/ingestion
```

## Wrap a stream

Construct an ingestion client with a `StreamStrategy`, hand it the stream you want to measure, and consume the returned wrapper exactly as you would the original. The strategy tallies bytes transparently and ships them to the meter you name in `.ingest()`.

```typescript theme={null}
import { createReadStream } from "node:fs";
import { Ingestion } from "@macropayments/ingestion";
import { StreamStrategy } from "@macropayments/ingestion/strategies/Stream";

const exportStream = createReadStream("./reports/q2-export.csv");

// Bind the Stream strategy to a meter named "data-export"
const exportIngestion = Ingestion({ accessToken: process.env.MACROPAY_ACCESS_TOKEN })
  .strategy(new StreamStrategy(exportStream))
  .ingest("data-export");

export async function GET(request: Request) {
  try {
    // Wrap the stream and attribute usage to a specific customer.
    // The customer id keeps every byte tied to the right account for billing.
    const stream = exportIngestion.client({
      customerId: request.headers.get("X-Macropay-Customer-Id") ?? "",
    });

    // Use the wrapper just like the original stream —
    // bytes are metered as they pass through.
    stream.on("data", () => {
      /* pipe to the response, transform, etc. */
    });

    return Response.json({});
  } catch (error) {
    return Response.json({ error: error.message });
  }
}
```

<Tip>
  Always pass a `customerId`. It attributes the metered bytes to the right account so usage shows up on the correct invoice and customer portal.
</Tip>

## What gets ingested

When the stream finishes, the strategy posts a single event to your meter. The `bytes` field carries the total moved through the stream:

```json theme={null}
{
  "customerId": "123",
  "name": "data-export",
  "metadata": {
    "bytes": 100
  }
}
```

That `bytes` value is what your meter aggregates. Point a metered price at the meter — say, \$0.10 per GB transferred — and Macropay turns the raw counts into a billable line item.

## Billing agents and AI workloads

Streaming is where a lot of AI cost lives: a model response piped straight to the client, embeddings written to object storage, a retrieval pipeline fanning out documents. Wrap those streams to capture the real data volume an agent consumes.

If you bill agents on **activity or outcome** rather than raw bytes, pair stream metering with [prepaid credits](/features/usage-based-billing/credits) to draw down a balance per event — then compare billed revenue against AI cost to see the **agentic margin** on every run.

## Related strategies

* [Strategy introduction](/features/usage-based-billing/ingestion-strategies/ingestion-strategy) — when to reach for each one
* [LLM Strategy](/features/usage-based-billing/ingestion-strategies/llm-strategy) — meter token usage from model calls
* [S3 Strategy](/features/usage-based-billing/ingestion-strategies/s3-strategy) — meter bytes uploaded to object storage
* [Delta Time Strategy](/features/usage-based-billing/ingestion-strategies/delta-time-strategy) — meter the duration of arbitrary execution