Skip to main content
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

​
recipient
string
required
The worker’s Stellar address. This is the only address authorized to claim streamed funds.
​
total_deposited
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).
​
rate_per_second
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).
​
duration_ledgers
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.
​
asset
string
required
The asset used for payment. Accepted values are USDC or XLM.
​
checkpoint_count
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.
​
withdrawable_cap_percent
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.
​
approval_timeout_ledgers
integer
required
How many ledgers the client has to approve or dispute a withdrawal request before it is automatically released to the worker.
​
category
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.
​
title
string
An optional human-readable label for the stream (up to 80 characters). Appears in the dashboard and on attestations.

​
Stream Lifecycle

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

​
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 or Freighter before the stream begins.
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 by searching for the stream contract address.