RevRule API Reference

OpenAPI 3.1: payload-rail.fly.dev/openapi.json — 2 paths (the x402 machine-commerce endpoints), import into Postman, Insomnia, or generate a client.

LLM docs: payload-rail.fly.dev/llms.txt — the whole API in one plain-text file for agents and coding assistants.

x402 manifest: /.well-known/x402 — machine payment metadata for the paid endpoints.

Graphs

POST /v1/graphs — create a Revenue Graph (id, projectId, ownerId, participants, rules).
GET /v1/graphs/{id} — fetch a graph.
POST /v1/graphs/{id}/activate — activate a graph for production events.

Events & entitlements

POST /v1/graphs/{id}/events — post an economic event (validated envelope: eventId, graphId, type, occurredAt, amountMicros, currency, rail, processingCostMicros, raw). Idempotent on eventId: replays return the original result.
POST /v1/graphs/{id}/simulate — dry-run an event, see entitlements without writing the ledger.
GET /v1/graphs/{id}/ledger — read ledger entries for a graph.

Crypto

GET /v1/crypto/config — accepted assets and receiving address.
POST /v1/purchases/orders — create a cryptographically-bound purchase order: {"product": "revrule"} returns the order id, exact USDC amount, recipient, and a message_to_sign.
POST /v1/purchases/redeem — redeem {order_id, tx_hash, signature} (personal_sign of the order message by the paying wallet) to buy a $99 RevRule license with USDC on Base; the rail verifies the transfer on-chain before issuing your API key.
POST /v1/crypto/fees/settle — settle accrued fees on-chain.
GET /v1/fees/balance — accrued fee balances.

x402 machine commerce

POST /v1/x402/event — pay-per-call event endpoint (402 + payment requirements when unpaid).
GET|POST /v1/x402/public/evaluate — paid public evaluation: $0.01 USDC on Base, no API key. An unpaid call returns an x402 v2 402 payment challenge; after paying, POST {event, txHash} to evaluate your event against the fixed public demo graph.

# 1. Get a free API key — creates a free-tier account; the key is shown once.
#    (Or use the console: https://payload-rail.fly.dev/revrule-console/)
curl -X POST https://payload-rail.fly.dev/v1/access-keys \
  -H "Content-Type: application/json" \
  -d '{"label":"quickstart"}'
# -> {"key":"...","accountId":"..."} — save the key as $KEY below.

# 2. Create a graph. This is the public demo graph spec: platform 5% of gross,
#    creator 70% of the remainder, referrer 25% of the remainder (only when the
#    event carries attribution), creator takes what is left. A graph spec must
#    name an ownerId, and that participant must carry the "owner" role.
curl -X POST https://payload-rail.fly.dev/v1/graphs \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "x402-public",
    "projectId": "x402-public",
    "ownerId": "creator",
    "participants": [
      {"id": "payload_platform", "kind": "company", "roles": ["platform"], "payoutDestinations": []},
      {"id": "creator", "kind": "person", "roles": ["creator", "owner"], "payoutDestinations": []},
      {"id": "referrer", "kind": "person", "roles": ["referrer"], "payoutDestinations": []}
    ],
    "revenueSources": [
      {"id": "x402", "kind": "x402", "config": {}, "eventTypes": ["API_PAYMENT"]}
    ],
    "rules": [
      {"id": "platform-fee", "type": "percentage", "priority": 1,
       "params": {"rateBps": 500, "subjectParticipantId": "payload_platform", "base": "gross"}},
      {"id": "creator-share", "type": "percentage", "priority": 2,
       "params": {"rateBps": 7000, "subjectParticipantId": "creator", "base": "remaining"}},
      {"id": "referrer-share", "type": "percentage", "priority": 3,
       "params": {"rateBps": 2500, "subjectParticipantId": "referrer", "base": "remaining"},
       "conditions": {"requireAttribution": true}},
      {"id": "creator-remainder", "type": "remainder", "priority": 4,
       "params": {"subjectParticipantId": "creator"}}
    ]
  }'

# 3. Activate it (new graphs start as drafts)
curl -X POST https://payload-rail.fly.dev/v1/graphs/x402-public/activate \
  -H "Authorization: Bearer $KEY"

# 4. Dry-run an event — no ledger entries are written, no state changes.
#    Amounts are integer micro-units (1_000_000 = 1.00), never strings.
curl -X POST https://payload-rail.fly.dev/v1/graphs/x402-public/simulate \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"event":{"eventId":"sale-1","graphId":"x402-public","type":"API_PAYMENT","occurredAt":"2026-01-15T00:00:00Z","amountMicros":25000000,"currency":"USD","rail":"x402","processingCostMicros":0,"raw":{}}}'

# 5. Post the same event for real: POST /v1/graphs/x402-public/events
#    with the identical body.

# 6. Read the ledger
curl https://payload-rail.fly.dev/v1/graphs/x402-public/ledger \
  -H "Authorization: Bearer $KEY"

Postman: fork the Payload public workspace — the RevRule collection runs the whole quickstart with one click per request.

CSV import: npx revrule-csv-import revenue.csv --graph GRAPH_ID --api-key $KEY --dry-run — turn a Stripe export or payout CSV into events. GitHub.

Console: revrule-console — visual sandbox, free, no credit card.

RevRule computes entitlements; it never moves money. Amounts are integers in micro-units (6 decimals). Events are idempotent on eventId. A free key can create, activate, simulate, and post events to your own graphs; the $99 one-time license adds the entitlement-gated surfaces (payout evidence).