DEV Community

Payload
Payload

Posted on

Payload Flow is live: a hosted API that computes who gets paid, not who moves the money

#api #opensource #web3 #tutorial

Payment rails move money. Nobody computes who is owed what as infrastructure.

That is the gap Payload Flow fills. It is Payload Flow as a hosted API: the open-source programmable revenue engine, running and ready to call. You define a Revenue Graph (participants, rules, versions). You send economic events (a Stripe sale, an x402 settlement, a royalty statement row). It returns auditable entitlements: who is owed what, with a human-readable reason for every line, on a hash-chained ledger.

The core thesis: the royalty belongs to the Revenue Graph, not the payment rail. Change processors, keep the economics.

It is live right now

Base URL: https://payload-rail.fly.dev

Get a free API key with one call. No signup form, no credit card:

curl -s -X POST https://payload-rail.fly.dev/v1/access-keys \
  -H 'Content-Type: application/json' -d '{"label":"my first key"}'
Enter fullscreen mode Exit fullscreen mode

Define a graph. This one pays a developer 2% and the owner the remainder:

KEY=<your key>
BASE=https://payload-rail.fly.dev

curl -s -X POST $BASE/v1/graphs -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -d '{
    "id": "g1", "projectId": "p1", "ownerId": "owner",
    "participants": [
      {"id":"owner","kind":"person","roles":["owner"],
       "payoutDestinations":[{"rail":"stripe","address":"acct_owner"}]},
      {"id":"dev","kind":"person","roles":["contributor"],
       "payoutDestinations":[{"rail":"stripe","address":"acct_dev"}]}
    ],
    "rules": [
      {"id":"r_fee","type":"payload_fee","priority":1,"params":{"licenseTier":"free"}},
      {"id":"r_dev","type":"percentage","priority":2,
       "params":{"rateBps":200,"subjectParticipantId":"dev"}},
      {"id":"r_rem","type":"remainder","priority":3,
       "params":{"subjectParticipantId":"owner"}}
    ]
  }'

curl -s -X POST $BASE/v1/graphs/g1/activate -H "Authorization: Bearer $KEY"
Enter fullscreen mode Exit fullscreen mode

Send a $10.00 event:

curl -s -X POST $BASE/v1/graphs/g1/events -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' -d '{
    "event": {
      "eventId": "evt_001", "graphId": "g1", "type": "SALE_COMPLETED",
      "occurredAt": "2026-10-04T00:00:00.000Z",
      "amountMicros": 10000000, "currency": "USD", "rail": "stripe",
      "processingCostMicros": 330000, "raw": {}
    }
  }'
Enter fullscreen mode Exit fullscreen mode

You get back entitlements that conserve the pool exactly (net in equals net out, verified to the micro-unit), each with a reason, plus ledger entries you can audit:

curl -s $BASE/v1/graphs/g1/ledger -H "Authorization: Bearer $KEY"
Enter fullscreen mode Exit fullscreen mode

simulate dry-runs an event with zero side effects. State persists: recoupment balances survive restarts.

On-chain validation

The engine processed two x402 settlements on Base Sepolia (0.10 test USDC each, valid EIP-3009 signatures, settled on-chain), splitting each into 0.002 developer + 0.0098 referrer + 0.0882 operator with exact conservation and a valid ledger hash chain. x402 events enter the same economic architecture as Stripe sales, royalty rows, and every other supported event type: one graph, one ledger, one source of truth for who earned what.

How Payload Flow fits into your stack

Payment infrastructure answers how value moves. Payload Flow answers why it moves, who participates, what they are entitled to, and how those economics evolve over time.

Every distribution the API computes carries status: "proposed": Flow determines who is owed what, and your Stripe Connect account, facilitator, or payroll system executes the payouts. Flow never holds funds and never takes custody, so you can change processors, add rails, or go multi-rail without rebuilding your economics. The Revenue Graph outlives the payment rail.

Open source

The engine is MIT-licensed: github.com/Payloadhq/payload-flow. Self-host it, fork the rules, embed it. The hosted API is the convenience layer: same engine, zero ops. There is also a browser sandbox that runs the real engine client-side if you want to play with revenue graphs without an API key.

The rule language covers percentages, fixed amounts, per-use, referrals, recoupment waterfalls, caps, time limits, milestones, attribution, and remainders, with versioned graphs and an approval gate on rule changes. Rules are generic primitives; agent micropayments, marketplace splits, and royalty waterfalls are configurations, not branches.

If you are building agent commerce, marketplaces, or anything where money needs a programmatic memory of who earned it, try the Flow API and tell me where the model breaks. That feedback is the product roadmap.

Quickstart and docs: payloadhq.github.io/flow-rail.html

Top comments (0)