Documentation

Stream your first receipt in minutes.

This quickstart walks a payer and a receiver through the whole loop: open a stateless one-way channel, sign per-action receipts, tally them off-chain, and redeem a RAV to settle on-chain only when the balance crosses your trust threshold.

1 · Install

Add the SDK to any payer or receiver service. It ships typed clients for both roles and has no chain dependencies in the call hot path.

shell · install the sdk
# node 18+ · works in payer and receiver services
npm i @velapay/sdk

2 · Open a channel

A payer opens a stateless one-way channel to whoever does the work. The payer keeps no running balance per counterparty, so one host can stream to a whole fleet.

payer.ts · open a channel
import { Payer } from "@velapay/sdk"

const payer = new Payer({ signer: process.env.VELA_KEY })

const channel = await payer.openChannel({
  to: "agent:search-tool.v2"
})

3 · Sign a per-action receipt

For every billable action, sign a receipt against the channel and fire it to the counterparty. Receipts are signed fire-and-forget, so no chain round-trip sits in the call path.

payer.ts · sign a receipt
const receipt = channel.sign({
  action: "tools/web.search",
  units:  1,          // one call · $0.0004
  nonce:  channel.next()
})

counterparty.send(receipt)  // returns a signed receipt

4 · Tally off-chain

The receiver verifies each receipt and accumulates its own unpaid balance locally, at web2 speed. Watch the tally climb toward the trust threshold you set for this payer.

receiver.ts · tally locally
import { Receiver } from "@velapay/sdk"

const receiver = new Receiver({ threshold: "$500" })

receiver.on("receipt", (r) => {
  receiver.tally(r)  // verify + accumulate, no chain call
})

5 · Redeem & settle on-chain

When the unpaid balance crosses the threshold, the receiver redeems a Receipt Aggregate Voucher (RAV) and the contract settles, collapsing millions of receipts into one cheap transaction.

receiver.ts · redeem a RAV
if (receiver.balance() >= receiver.threshold) {
  const rav = receiver.buildRAV()  // aggregate all receipts

  const tx = await receiver.settle(rav)
  console.log(tx.hash, rav.count)  // 1 tx · 812,440 receipts
}

Next steps

Go deeper

API reference

Every method on the Payer and Receiver clients, channel options, and the RAV schema, documented end to end.

Browse the API

Guides

Playbooks for swarm escrow, threshold tuning, and wiring receipts into tool servers and serving APIs.

Read the guides

Security

How escrow, threshold enforcement, and the thawing period keep settlement safe across counterparties you've never met.

See the security model