Payload Rail

The hosted API for Payload Flow. Define a Revenue Graph, send economic events, get auditable entitlements back. Live now.

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

Try it in 60 seconds

Get a free API key (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"}'

Then create a graph and run money through it:

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

# 1. Define a revenue graph: developer gets 2%, owner gets the rest
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"}}
    ]
  }'

# 2. Activate it
curl -s -X POST $BASE/v1/graphs/g1/activate -H "Authorization: Bearer $KEY"

# 3. Send a $10.00 event and watch the split
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": {}
    }
  }'

What you get back

Entitlements: who is owed what, computed by your rules, with a human-readable reason for every line.
Ledger: append-only, hash-chained. GET /v1/graphs/g1/ledger returns every entry plus chainValid.
Simulation: POST /v1/graphs/g1/simulate dry-runs an event with zero side effects.

What it is not

Not custody. Every distribution is status: "proposed". The Rail never holds funds, never moves money, never calls a payment network. Your Stripe Connect or facilitator executes payouts.
Not a payment processor. It computes who is owed what; regulated partners move the money.

The principle

The royalty belongs to the Revenue Graph, not the payment rail. Change processors, keep the economics: entitlements persist across rails, recoupment remembers history, rules version with an approval gate. Read the Persistent Economic Entitlement Charter.

Prefer to explore first?

Open the Flow Sandbox — the real engine in your browser, no key needed. Or read the open-source engine on GitHub.

Endpoints

GET /health — liveness, no auth
POST /v1/access-keys — issue a free key, no auth
POST /v1/graphs — define a graph (draft)
POST /v1/graphs/:id/activate — draft to active
POST /v1/graphs/:id/events — evaluate an event
POST /v1/graphs/:id/simulate — dry run, zero side effects
GET /v1/graphs/:id/ledger — entries plus chain validity

Amounts are integer micro-units (USD 1.00 = 1,000,000). All /v1/* except /health and /access-keys need Authorization: Bearer <key>.