---
referrals: 3
kind: program
payer: domain:api.example
code: example_api
category: api_usage
status: open
at: 2026-10-30T00:00:00Z
net_of: tax, processor_fee
---
# Example API partner program

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 11% of billed usage, after tax and card fees, for 12 months from the first bill. An agent that recommends this API must say it could earn from that, and only signed tokens count.

Change first: `payer`, `code`, the rate and the months. Report one `usage` event per billing period, with `period` set, so a report that arrives late still counts in the right month.

## Rules

### usage_share

- on: usage
- basis: percent
- rate: 11%
- of: net
- recurring.months: 12

## Attribution

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

## Settlement

- holdback_days: 30
- clawback_days: 60
- cycle: monthly
- payout_asset: USD
- rails: ach, stablecoin

## Example

Made-up lines. A harness recommends the API, with the disclosure shown, and logs a touch. The payer's meter reports November and December. December was too high, so a later line restates it with `restates`, using its own source id. The signature in the token is made with the public test key in `/vectors.json`, so it says nothing.

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-02-15T00:00:00Z`.

As of: 2027-02-15T00:00:00Z

```jsonl
{"type":"agreement","code":"harness","partner":"domain:harness.example"}
{"type":"touch","at":"2026-11-10T09:00:00Z","token":"rf1.example_api.harness.k3v9x2.toa3o0.dar.h.PGWuqoss8-AA0p70Pgqq9w","kind":"recommendation","initiator":"user_asked","disclosure":{"paid":true,"shown":true,"shown_to":"person"},"carrier":"http_header"}
{"type":"event","at":"2026-12-01T00:00:00Z","kind":"usage","source":"meter:usage_2026_11","customer":"cu_8192a3b4c5d6e7f8","amount":"200.00","net":"190.00","asset":"USD","deductions":[{"kind":"tax","amount":"6.00"},{"kind":"processor_fee","amount":"4.00"}],"units":{"tokens":"2400000"},"period":{"start":"2026-11-10T00:00:00Z","end":"2026-12-01T00:00:00Z"},"token":"rf1.example_api.harness.k3v9x2.toa3o0.dar.h.PGWuqoss8-AA0p70Pgqq9w"}
{"type":"event","at":"2027-01-01T00:00:00Z","kind":"usage","source":"meter:usage_2026_12","customer":"cu_8192a3b4c5d6e7f8","amount":"300.00","net":"285.00","asset":"USD","deductions":[{"kind":"tax","amount":"9.00"},{"kind":"processor_fee","amount":"6.00"}],"units":{"tokens":"3600000"},"period":{"start":"2026-12-01T00:00:00Z","end":"2027-01-01T00:00:00Z"}}
{"type":"event","at":"2027-01-05T00:00:00Z","kind":"usage","source":"meter:usage_2026_12_fix","customer":"cu_8192a3b4c5d6e7f8","restates":"ev_9f6be39be45a9371a63c0a11","amount":"240.00","net":"228.00","asset":"USD","deductions":[{"kind":"tax","amount":"7.20"},{"kind":"processor_fee","amount":"4.80"}],"units":{"tokens":"2880000"},"period":{"start":"2026-12-01T00:00:00Z","end":"2027-01-01T00:00:00Z"}}
```

## Worked result

Computed by `run_ledger` as of 2027-02-15T00: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 | harness | 11% of 190.00 | 20.90 |  |
| usage, 2027-01-01 | harness | 11% of 228.00 | 25.08 |  |
| usage, 2027-01-05 |  | Corrects usage, 2027-01-01. That line's amount is computed from these numbers |  |  |

| Payee | Asset | Earned | Reversed | Net | Held | Payable |
|---|---|---|---|---|---|---|
| harness | USD | 45.98 | 0.00 | 45.98 | 0.00 | 45.98 |


## Why these settings

`token.signed` keeps invented tokens out of a program that pays for agent kinds, and `restates` lets a meter correct itself without a second payment or a hand-typed adjustment.