---
referrals: 3
kind: program
payer: domain:compute.example
code: example_compute
category: api_usage
status: open
at: 2026-10-30T00:00:00Z
crit: cap
---
# Example compute referral

Rates, amounts and names in this file are placeholders, not recommendations or market rates. Each party sets its own terms.

In plain words: a referrer earns 7% of the margin on a referred customer's compute, up to 1,000.00 per customer in total. A refund makes room under the cap for later usage.

Change first: `payer`, `code`, the rate and the cap. Write down in your own terms how you compute `margin`, since it is your own number and the partner can't check it.

## Rules

### margin_share

- on: usage
- basis: percent
- rate: 7%
- of: margin
- recurring.months: 12
- cap.per: customer
- cap.amount: 1000.00
- cap.asset: USD

## Attribution

- model: last_touch
- window_days: 30
- allowed_kinds: recommendation, tool_call
- token.signed: signed

## Settlement

- holdback_days: 30
- clawback_days: 60
- cycle: monthly
- payout_asset: USD
- rails: ach
- audit.right: Partner may check margin by sample, once a year.
- audit.notice_days: 30
- audit.lookback_days: 365

## Example

Made-up lines. Each month has 8,000.00 of margin, so 560.00 before the cap. The second month reaches the cap and the third computes nothing. A refund of half the second month gives back room, and the fourth month uses it.

To run it, save this file as `REFERRALS.md` and these lines as `referrals.jsonl`, then run `node referrals.mjs run REFERRALS.md referrals.jsonl --as-of 2027-05-01T00:00:00Z`.

As of: 2027-05-01T00:00:00Z

```jsonl
{"type":"agreement","code":"router","partner":"domain:router.example"}
{"type":"event","at":"2026-12-01T00:00:00Z","kind":"usage","source":"meter:gpu_2026_11","customer":"cu_92a3b4c5d6e7f809","amount":"20000.00","margin":"8000.00","asset":"USD","units":{"gpu_hours":"6400"},"token":"rf1.example_compute.router.g7h2q.tosjk0.dat.h.7qMlZx1Nm3aKg7vIwtzX8w"}
{"type":"event","at":"2027-01-01T00:00:00Z","kind":"usage","source":"meter:gpu_2026_12","customer":"cu_92a3b4c5d6e7f809","amount":"20000.00","margin":"8000.00","asset":"USD","units":{"gpu_hours":"6400"}}
{"type":"event","at":"2027-02-01T00:00:00Z","kind":"usage","source":"meter:gpu_2027_01","customer":"cu_92a3b4c5d6e7f809","amount":"20000.00","margin":"8000.00","asset":"USD","units":{"gpu_hours":"6400"}}
{"type":"event","at":"2027-02-10T00:00:00Z","kind":"refund","source":"billing:re_gpu_12","customer":"cu_92a3b4c5d6e7f809","amount":"10000.00","margin":"4000.00","asset":"USD","reverses":"ev_66850f75c7ce548e5ad53e3e"}
{"type":"event","at":"2027-03-01T00:00:00Z","kind":"usage","source":"meter:gpu_2027_02","customer":"cu_92a3b4c5d6e7f809","amount":"20000.00","margin":"8000.00","asset":"USD","units":{"gpu_hours":"6400"}}
```

## Worked result

Computed by `run_ledger` as of 2027-05-01T00:00:00Z, on the made-up lines above. Computed amounts are arithmetic on the records and terms you sent. They do not say what anyone owes. Your contract decides that.

| Event | Who | Working | Computed | Note |
|---|---|---|---|---|
| usage, 2026-12-01 | router | 7% of 8000.00 | 560.00 |  |
| usage, 2027-01-01 | router | 7% of 8000.00 | 440.00 | capped:customer |
| usage, 2027-02-01 | router | 7% of 8000.00 | 0.00 | capped:customer |
| refund, 2027-02-10 | router | Reverses what was computed on usage, 2027-01-01 | -220.00 |  |
| usage, 2027-03-01 | router | 7% of 8000.00 | 220.00 | capped:customer |

`capped:customer`: A cap limited this amount, per customer.

| Payee | Asset | Earned | Reversed | Net | Held | Payable |
|---|---|---|---|---|---|---|
| router | USD | 1220.00 | -220.00 | 1000.00 | 0.00 | 1000.00 |


## Why these settings

A share of margin keeps a thin-margin product from paying out more than it keeps, and `audit` gives the partner a contract answer to the one number it can't check.