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

# Payment Streams: Real-Time On-Chain Escrow on Stellar

> Payment streams lock funds on Stellar and release them in real time, giving clients full control and workers guaranteed, verifiable pay as work progresses.

A payment stream is an on-chain escrow that continuously releases funds to a worker at a defined rate as Stellar ledgers close (approximately every 5 seconds). Instead of paying upfront and hoping work gets delivered — or waiting until the end of a project to receive any money — Aven aligns payment with progress. The client deposits the total amount once, and the worker earns it ledger by ledger as they contribute.

## What Is a Stream?

When you create a stream, the `stream_contract` on Stellar locks the full deposit on-chain and begins releasing funds to the recipient at the agreed rate per ledger (approximately every 5 seconds). The worker can claim their earned balance at any time. Unearned funds are never accessible to the worker — and if the stream is cancelled, they are returned to the client automatically.

Streams are denominated in either **USDC** or **native XLM**, are divided into checkpoint periods for milestone-based release, and use an approval window that auto-releases funds to the worker if the client does not act within the timeout.

## Stream Parameters

<ParamField path="recipient" type="string" required>
  The worker's Stellar address. This is the only address authorized to claim streamed funds.
</ParamField>

<ParamField path="total_deposited" type="integer" required>
  The total amount to deposit into the stream, in the chosen asset (USDC or XLM). This is locked in the contract at creation and must be at least `rate_per_second × 5 × duration_ledgers` (the contract converts the per-second rate to a per-ledger rate using a factor of 5 ledgers per unit).
</ParamField>

<ParamField path="rate_per_second" type="integer" required>
  The amount the worker earns for each active second of stream time. The contract stores this internally as a per-ledger rate (multiplied by 5, since each Stellar ledger closes approximately every 5 seconds).
</ParamField>

<ParamField path="duration_ledgers" type="integer" required>
  The intended length of the stream measured in Stellar ledgers. At approximately 5 seconds per ledger, a one-week stream is roughly 120,960 ledgers. This value must be evenly divisible by `checkpoint_count`.
</ParamField>

<ParamField path="asset" type="string" required>
  The asset used for payment. Accepted values are `USDC` or `XLM`.
</ParamField>

<ParamField path="checkpoint_count" type="integer" required>
  The number of milestone checkpoints that divide the stream's duration. Must be between 1 and 30. Setting this to 1 means the entire stream is a single checkpoint period.
</ParamField>

<ParamField path="withdrawable_cap_percent" type="integer" required>
  The percentage of an in-progress checkpoint period's earned amount that the worker can withdraw before the checkpoint is finalized. Set to 100 to allow full withdrawal at any time.
</ParamField>

<ParamField path="approval_timeout_ledgers" type="integer" required>
  How many ledgers the client has to approve or dispute a withdrawal request before it is automatically released to the worker.
</ParamField>

<ParamField path="category" type="string" required>
  The type of work this stream represents. Determines which bucket of the worker's reputation score is incremented. Accepted values: `Freelance`, `Salary`, `Bounty`, `Grant`, `AgentTask`, `Subscription`.
</ParamField>

<ParamField path="title" type="string">
  An optional human-readable label for the stream (up to 80 characters). Appears in the dashboard and on attestations.
</ParamField>

## Stream Lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> Active: Client creates stream
    Active --> Paused: Client pauses
    Paused --> Active: Client resumes
    Active --> Cancelled: Client cancels
    Paused --> Cancelled: Client cancels
    Active --> Completed: All funds claimed
    Paused --> Completed: All funds claimed while paused
```

The client controls the stream state. Workers earn only while the stream is `Active`. Pausing halts the earning clock without losing progress; cancelling terminates the stream and returns the unearned portion to the client automatically.

## Stream Status

| Status      | Description                                                                    |
| ----------- | ------------------------------------------------------------------------------ |
| `Active`    | The stream is running and funds are being earned in real time                  |
| `Paused`    | The stream is temporarily halted by the client; no new funds accrue            |
| `Cancelled` | The stream was terminated; all unearned funds have been returned to the client |
| `Completed` | All allocated funds have been claimed by the worker                            |

## USDC vs XLM

Both **Stellar USDC** and **native XLM** are fully supported as stream assets.

* **USDC** is a USD-pegged stablecoin issued on Stellar. Because it is a non-native asset, the recipient's Stellar account must have an active **trustline** for USDC before they can receive payment. If the trustline is missing, the transfer will fail.
* **XLM** is Stellar's native currency and requires no trustline. It is available on any funded Stellar account and is the simpler choice for new workers.

If you are setting up a stream for a worker who does not yet have a USDC trustline, ask them to add one via [Lobstr](https://lobstr.co) or [Freighter](https://freighter.app) before the stream begins.

<Note>
  All payment streams are settled on the Stellar blockchain. Every deposit, pause, cancellation, and withdrawal is a verifiable on-chain transaction. You can inspect any stream's full history using [Stellar Expert](https://stellar.expert) by searching for the stream contract address.
</Note>