Held funds and their release
What you owe each held seller, line by line. Paid out in one transfer, signed from your dashboard.
A held seller's sales pay your organization's wallet, and QBitFlow records what you owe them: their share, your commission withheld. It stays there until you release it.
- Held in your walletA saleOwed to the seller: their share, your commission withheld
- A negative lineA refund, maybeSent from your wallet; what you owe drops
- heldFunds.released ✓You releaseEverything held, in one transfer, signed with your wallet
- Paid directlyYou trust themTheir new payments go straight to their wallet
What you hold
members-held-funds.sh
# What the organization holds for its members (their payments while untrusted), the longest held# first. One member's lines: GET /members/$MEMBER_UUID/held-funds.curl https://api.qbitflow.app/v2/members/held-funds \ -H "X-API-Key: $QBITFLOW_API_KEY"# 200: [ { "userUuid": "…", "totalAmount": 98.35, "count": 2, "oldestAt": "…" } ]// What the organization holds for its members (their payments while untrusted), the longest// held first.const all = await client.members.listHeldFunds();for (const owed of all) { console.log(`${owed.userUuid}: ${owed.totalUsd} USD owed over ${owed.count} lines`);} const held = await client. members. getHeldFunds( memberUuid);for (const ledger of held.ledgers) { // owed: what the line counts for in a release (negative for a refund). console.log( ` ${ledger.type} ${ledger.owed} ${ledger.currency.symbol} (${ledger.owedUsd} USD)` );}console.log(`held for this member: ${held.totalUsd} USD`);# Every member you hold funds for, the longest held first.for summary in client. members. list_held_funds( ): print(summary.user_uuid, f"{summary.total_usd} USD over {summary.count} lines") held = client. members. get_held_funds( member_uuid) # one member, line by lineprint(f"owed to the seller: {held.total_usd} USD over {len(held.ledgers)} lines")marketplace/main.go
// What the organization holds for its members (their payments while untrusted).// The longest held first.all, err := client. Members. ListHeldFunds( ctx)if err != nil { log.Fatal(err)}for _, s := range all { fmt.Printf("%s: %s USD over %d lines\n", s.UserUUID, s.TotalUSD, s.Count)} held, err := client.Members.GetHeldFunds(ctx, memberUUID)if err != nil { log.Fatal(err)}fmt.Printf("owed to %s: %s USD over %d lines\n", memberUUID, held.TotalUSD, len(held.Ledgers))foreach ( $client->members->listHeldFunds( ) as $owed) { // every member you owe, the longest held first echo "{$owed->userUuid}: {$owed->totalUsd} USD over {$owed->count} lines\n";} $held = $client->members->getHeldFunds( $memberUuid);printf("Owed to %s: %s USD over %d lines\n", $memberUuid, $held->totalUsd, count($held->ledgers));The sellers you hold funds for, longest held first, each with its totalUsd. One seller's
detail is ledgers: a line per payment held, oldest first, with what you still owe for it
(owedMinUnits, owedUsd). A refund of a held payment is a negative line of its own.
What the seller sees
The same, for their own space: on their dashboard's Payouts page, with their own key, or from yours acting for them.
members-own-held-funds.sh
# What the organization holds for the key's own space (a member's key, or On-Behalf-Of a member).# Empty for the organization.curl https://api.qbitflow.app/v2/held-funds \ -H "X-API-Key: $QBITFLOW_API_KEY"# 200: a HeldFunds// With a member's key, or a client.onBehalfOf(memberUuid) client. Empty for the organization.const held = await client. members. getOwnHeldFunds( );console.log(`held for me: ${held.totalUsd} USD over ${held.ledgers.length} lines`);# With a member's key, or a client acting on behalf of the member.held = client. members. get_own_held_funds( )print(f"held for me: {held.total_usd} USD over {len(held.ledgers)} lines")marketplace/main.go
// As the member: with their own key, or the organization's acting for them.own, err := client. OnBehalfOf( memberUUID). Members. GetOwnHeldFunds( ctx)if err != nil { log.Fatal(err)}fmt.Printf("held for me: %s USD over %d lines\n", own.TotalUSD, len(own.Ledgers))// With a member's key (or a client from $client->onBehalfOf($memberUuid)):$held = $client->members->getOwnHeldFunds( );printf("Held for me: %s USD over %d lines\n", $held->totalUsd, count($held->ledgers));Release it, from the dashboard
A release is a transfer from your wallet to the seller's, so your wallet signs it, in the dashboard. SDKs can't release yet.
From the contract · ledger.md § Releasing
- Held in your wallet: Each sale pays your organization's wallet; you owe the seller their share, your commission kept.
- You release, signed once: From the seller's page in the dashboard: pick a token, sign once with your organization's wallet.
- The seller's wallet: Everything held for them, at today's price, in one transfer to their wallet: heldFunds.released.
- Everything held for that seller in this mode, whatever chain each sale was on: converted at today's price into the token you pick, sent on that token's chain, signed once.
- The seller needs a wallet on that chain; yours must hold the amount.
- Refunds cancel out what's held? Nothing to pay: the dashboard offers to close the held funds.
Once it confirms, those lines leave the held funds, QBitFlow emails the seller what they received,
and the seller's heldFunds.released arrives:
heldFunds.released· the body your endpoint receives
{ "createdAt": "2026-10-01T12:00:00Z", "data": { "amount": "98.9068", "chain": "BASE", "currency": { "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "chain": "BASE", "code": "BASE:USDC", "decimals": 6, "id": 8, "mainCurrencyId": 3, "name": "USD Coin", "symbol": "USDC", "test": false }, "ledgers": […], … 13 more fields }, "id": "evt_620352e2-0285-52e8-adc1-64a9774278c1", "test": false, "type": "heldFunds.released", "userUuid": "019eca82-5680-7b00-8000-0000000000b1", "version": "v2"}data.chain: That token's chain, where the transfer was sent.data.currency: The token you picked to pay them in.userUuid: The seller's: it's their event.
Its ledgers (folded above) are the lines it settled.
Check it
Pay a held test seller's checkout: it's in what you hold, and in their Held funds in
Dashboard/Members. Release and sign: their held funds empty, and
heldFunds.released arrives with their userUuid.