---
referrals: 3
kind: program
payer: domain:api.example
code: example_paid_api
category: api_usage
status: open
at: 2026-10-30T00:00:00Z
---
# Example paid API 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 0.40 per 1,000 paid calls from a customer whose calls carry its public builder code, in a stablecoin, for 12 months. A builder code is a public claim: anyone can copy it, the same as an unsigned link.

Change first: `payer`, `code`, the price and the asset. The asset below is a made-up address. Roll calls up by the hour or day, so you write one line per rollup rather than one per call.

## Rules

### per_call

- on: payment
- basis: per_unit
- price.amount: 0.40
- price.asset: caip19:eip155:8453/erc20:0x0000000000000000000000000000000000000001
- price.per: 1000
- price.unit: calls
- recurring.months: 12

## Attribution

- model: last_touch
- window_days: 30
- match: token, code
- allowed_kinds: builder_code

## Settlement

- holdback_days: 14
- clawback_days: 30
- cycle: weekly
- payout_asset: caip19:eip155:8453/erc20:0x0000000000000000000000000000000000000001
- rails: stablecoin

## Assets

| asset | scale |
|---|---|
| caip19:eip155:8453/erc20:0x0000000000000000000000000000000000000001 | 6 |

## Example

Made-up lines. Two rollups of paid calls carry the code `router_one`, which might have come from the `builder-code` extension of an x402 payment. That is a mapping this format proposes, and that project has not adopted it. One rollup is partly refunded, so a share of its amount reverses.

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

As of: 2026-12-15T00:00:00Z

```jsonl
{"type":"agreement","code":"router_one","partner":"domain:router.example"}
{"type":"event","at":"2026-11-03T00:00:00Z","kind":"payment","source":"ledger:rollup_1103","customer":"cu_a3b4c5d6e7f80912","amount":"12.500000","asset":"caip19:eip155:8453/erc20:0x0000000000000000000000000000000000000001","units":{"calls":"12500"},"codes":["router_one"],"carrier":"x402_extension"}
{"type":"event","at":"2026-11-04T00:00:00Z","kind":"payment","source":"ledger:rollup_1104","customer":"cu_a3b4c5d6e7f80912","amount":"7.300000","asset":"caip19:eip155:8453/erc20:0x0000000000000000000000000000000000000001","units":{"calls":"7300"},"codes":["router_one"],"carrier":"x402_extension"}
{"type":"event","at":"2026-11-06T00:00:00Z","kind":"refund","source":"ledger:refund_1104","customer":"cu_a3b4c5d6e7f80912","amount":"1.460000","asset":"caip19:eip155:8453/erc20:0x0000000000000000000000000000000000000001","reverses":"ev_141301a4c4bbc7d7e3e93c86"}
```

## Worked result

Computed by `run_ledger` as of 2026-12-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 |
|---|---|---|---|---|
| payment, 2026-11-03 | router_one | 12500 calls at 0.40 per 1000 | 5.000000 |  |
| payment, 2026-11-04 | router_one | 7300 calls at 0.40 per 1000 | 2.920000 |  |
| refund, 2026-11-06 | router_one | Reverses what was computed on payment, 2026-11-04 | -0.584000 |  |

| Payee | Asset | Earned | Reversed | Net | Held | Payable |
|---|---|---|---|---|---|---|
| router_one | caip19:eip155:8453/erc20:0x0000000000000000000000000000000000000001 | 7.920000 | -0.584000 | 7.336000 | 0.000000 | 7.336000 |


## Why these settings

`allowed_kinds: builder_code` keeps this program to the claim it can see, `match: code` connects bare codes to the agreement, and a scale of 6 keeps small call fees from rounding away.