API reference
A small REST API over the velapay rail. Open and close channels, submit
signed per-action receipts, request Receipt Aggregate Vouchers, and settle on-chain at
threshold. Every write request is signed with your channel key; responses are JSON.
Base URL https://api.velapay.xyz.
Open a stateless one-way payment channel to a counterparty, inspect its state, and close it to release escrow.
Open a new one-way channel from the payer to a named counterparty and lock escrow.
Fetch a channel's state: escrow, unpaid balance, receipt count, and settlement count.
Begin closing a channel; remaining escrow thaws and is returned after the delay.
POST /v1/channels { "to": "agent:search-tool.v2", "escrow": "500.00", "threshold": "250.00" } // 201 Created { "id": "chn_9f3a21", "status": "open", "unpaid": "0.00", "receipts": 0 }
Submit signed per-action receipts against an open channel and list the receipts a channel has tallied.
Submit a signed receipt for one metered action; the receiver verifies and tallies it.
List receipts for a channel, paginated by nonce, with the running unpaid balance.
POST /v1/receipts { "channel": "chn_9f3a21", "action": "tools/web.search", "units": 1, "nonce": 812441, "sig": "0x7c…e10" } // 202 Accepted { "accepted": true, "unpaid": "324.97", "tallied": 812441 }
Request a Receipt Aggregate Voucher that collapses a channel's tallied receipts into a single redeemable claim.
Request a RAV for a channel once its unpaid balance has crossed the threshold.
Fetch a RAV's amount, the receipts it aggregates, and whether it has been settled.
POST /v1/rav { "channel": "chn_9f3a21" } // 200 OK { "id": "rav_18c44e", "amount": "324.97", "receipts": 812441, "status": "redeemable" }
Settle one or more RAVs on-chain in a single transaction once balances cross their thresholds, and track the result.
Settle redeemable RAVs on-chain at threshold, batching many receipts into one tx.
Fetch a settlement's transaction hash, block, redeemed amount, and confirmation state.
POST /v1/settlements { "ravs": ["rav_18c44e", "rav_18c451"] } // 200 OK { "id": "stl_4421a0", "tx": "0x3d…91f", "block": 19442071, "redeemed": "2215.37", "status": "confirmed" }
Authenticate with an API key in the Authorization header. Every write
request must also be signed with your channel key, and the receiver verifies that
signature before tallying, so a leaked API key alone cannot mint receipts. New to the
rail? Start with the quickstart.