RevRule API Reference

RevRule by Payload: a programmable revenue rules engine. Define a Revenue Graph, send economic events, get auditable entitlements. Your payment rail moves the money. RevRule determines the economics.

Base URL

https://payload-rail.fly.dev

Authentication

All /v1 endpoints except /health, /v1/access-keys, and /v1/crypto/config require a Bearer API key:

Authorization: Bearer YOUR_API_KEY

Get a free key with one call (no credit card). Five keys per IP per 24 hours.

Quickstart: first economic event in 3 calls

1. Get an API key

curl -X POST https://payload-rail.fly.dev/v1/access-keys \
  -H "Content-Type: application/json" \
  -d '{"label":"quickstart"}'
# → {"key":"...","accountId":"acct_...","tier":"free"}

2. Create a Revenue Graph

curl -X POST https://payload-rail.fly.dev/v1/graphs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "marketplace-v1",
    "participants": [
      {"id":"seller","type":"person"},
      {"id":"platform","type":"platform"},
      {"id":"referrer","type":"person"}
    ],
    "rules": [
      {"id":"platform-fee","type":"percentage","value":10,"payee":"platform"},
      {"id":"referral","type":"percentage","value":5,"payee":"referrer"},
      {"id":"seller-remainder","type":"remainder","payee":"seller"}
    ]
  }'
# → 201 {"graph":{...}}

3. Process an economic event

curl -X POST https://payload-rail.fly.dev/v1/graphs/marketplace-v1/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": {
      "eventId": "evt-001",
      "graphId": "marketplace-v1",
      "amountMicros": 100000000,
      "currency": "USD",
      "occurredAt": "2026-10-04T12:00:00Z"
    }
  }'
# → {"eventId":"evt-001","entitlements":[
#      {"participantId":"platform","amountMicros":10000000},
#      {"participantId":"referrer","amountMicros":5000000},
#      {"participantId":"seller","amountMicros":85000000}
#    ], ...}

Amounts are in micro-units (1,000,000 micros = 1.00). The response is a proposed distribution. RevRule never moves money.

Endpoint reference

GET /health public

Service status.

curl https://payload-rail.fly.dev/health
# → {"ok":true}

POST /v1/access-keys public

Issue a free API key. Rate limited: 5 per IP per 24 hours. The key is shown once.

Field	Type	Description
`label`	string, optional	Human-readable label, max 200 chars.

POST /v1/graphs auth

Define a Revenue Graph (created in draft status). Graph IDs must be unique per account.

Field	Type	Description
`id`	string, required	Unique graph identifier.
`participants`	array, required	Participants with `id` and `type`.
`rules`	array, required	Ordered rules: `percentage`, `fixed`, `remainder`, referral, recoupment, waterfall, caps.

GET /v1/graphs/:id auth

Fetch a graph definition with its current version and status.

POST /v1/graphs/:id/activate auth

Activate a draft graph so it can process live events. Rule changes create new versions behind an approval gate.

POST /v1/graphs/:id/events auth

Process a live economic event. Computes entitlements, writes ledger entries, accrues the Payload infrastructure fee. Idempotent on eventId: replays return the original result.

Field	Type	Description
`event.eventId`	string, required	Unique event ID (idempotency key).
`event.graphId`	string, required	Must match the URL graph ID.
`event.amountMicros`	integer, required	Event value in micro-units.
`event.currency`	string, required	ISO currency code.
`event.occurredAt`	string, required	ISO 8601 timestamp.

Response includes entitlements, fees, distributions (proposed), and ledgerEntries.

POST /v1/graphs/:id/simulate auth

Dry run. Same computation as /events with zero side effects: no ledger writes, no state changes. Use it to preview rule changes.

GET /v1/graphs/:id/ledger auth

Read ledger entries with hash-chain verification. Filter by ?eventId=, ?participantId=, ?type=.

GET /v1/crypto/config public

Machine-readable payment configuration: network, asset, contract, destination, prices.

curl https://payload-rail.fly.dev/v1/crypto/config
# → {"enabled":true,"network":"eip155:8453","asset":"USDC",
#     "purchasePriceUsdc":"99","eventPriceUsdc":"0.01",...}

POST /v1/crypto/purchase public

Register a $99 one-time production purchase paid in USDC on Base. Send 99 USDC to the configured destination, then POST the transaction hash. Verified on-chain; replay-protected.

curl -X POST https://payload-rail.fly.dev/v1/crypto/purchase \
  -H "Content-Type: application/json" \
  -d '{"txHash":"0x...","accountId":"acct_..."}'

GET /v1/fees/balance auth

Accrued Payload infrastructure fee balance for the account.

POST /v1/crypto/fees/settle auth

Settle accrued infrastructure fees in USDC on Base. POST the settlement transaction hash; verified on-chain.

POST /v1/x402/event auth

Machine-commerce entry point. Accepts x402 payment proofs and converts them into RevRule economic events: the agent pays, RevRule programs who participates. Returns HTTP 402 with machine-readable payment requirements when payment is missing.

Errors

All errors return JSON with error.code and error.message:

{"error":{"code":"GRAPH_NOT_FOUND","message":"graph \"x\" not found"}}

Code	Meaning
`UNAUTHORIZED`	Missing or invalid Bearer key.
`INVALID_BODY`	Request body failed validation.
`GRAPH_NOT_FOUND`	No graph with that ID for this account.
`DUPLICATE_GRAPH`	Graph ID already exists.
`EVENT_GRAPH_MISMATCH`	Event graphId does not match the URL.
`RATE_LIMITED`	Too many requests; check `Retry-After`.
`INVALID_GRAPH_SPEC`	Graph definition failed validation.

Rate limits

Key issuance: 5 per IP per 24 hours.
Authenticated endpoints: per-key rate limiting; 429 with Retry-After when exceeded.

What RevRule does not do

RevRule computes who is entitled to what. It never holds funds, never executes payouts, never moves money. Your Stripe account, crypto wallet, or payment rail executes the distributions RevRule proposes. The ledger is an auditable record of entitlements, not a money-movement log.

Support: kyler.simmons.partners@gmail.com.