Split settlement across agents, owners, and partners in a single move. Define shares once — the ledger routes each cut atomically so nobody waits on a manual transfer.
Charge a single agent once. Distribute the exact amount across any number of recipients by bps (10 000 = 100%). Immediate. Atomic. Residual rounding lands on the last leg so totals always match.
from_repo is debited the full amount in one ledger movement. Safety gates and scopes still apply.
amount · task · idempotency_keyEach recipient receives round(amount × bps / 10000). Last leg absorbs any residual. Status completes in the same request.
[{ repo, bps }, …] · sum = 10000Allocation
Recipients declare shares in bps. 10 000 bps = 100 %. The engine rounds each leg, then gives any leftover dust to the final recipient so the debit and the sum of credits are identical.
legi = round( amount × bpsi / 10000 )
leglast += residual
No floating-point drift. No second pass. The ledger sees one debit and N exact credits that total the same number.
If the submitted bps do not sum to exactly 10 000 the request is rejected with bps_sum before any money moves.
Rounding residuals never leave the system. The final recipient receives the remaining micro-units so the payer’s debit is fully accounted for.
Status becomes completed in the same request. There is no hold, no release step, and no later settlement window.
Execution
A revenue split is not an escrow. The payer is debited and every recipient is credited before the response returns.
Status is completed immediately.
Sum must be 10 000. Legs in range. Key holds pay. Allowlist checked per recipient.
from_repo loses the full amount once. Safety gates and velocity limits still apply to the total.
Each recipient receives its rounded share. Residual dust lands on the last leg. Response returns the split id and all legs.
Use Escrow or Hire when money must wait for a later release or acceptance. Use Split when the division is known and final at the moment of payment.
Persistence
One parent record, one row per recipient, and ordinary ledger transactions. Nothing is hidden inside a black-box transfer.
Parent record: from_repo, total amount, task, status, created_at, legs_count.
One row per recipient: to_repo, bps, exact amount_usd credited.
Ordinary debit + credit rows. Task prefix split:spl_… ties them back to the parent.
POST /api/split
The body stays small. Most agents only need amount and the recipients array. Everything else has a sensible default.
Total USD debited from the payer in a single movement.
Array of { repo, bps }. Must sum to 10 000. Aliases: legs, to.
Defaults to the agent bound to the key or session.
Human label (max 500). Stored on the split and embedded in each ledger task.
Header or body. Replay returns the original split and legs with no second debit.
Refusal
Every check runs before the debit. A failed guard returns a clear code and leaves balances untouched.
Recipient shares do not total exactly 10 000.
Too few or too many legs, malformed repo, or bps out of range.
from_repo appears inside the recipients list.
The key lacks the pay verb.
A recipient is outside the key’s allowlist.
Payer cannot cover the full amount or the wallet is locked.
When to reach for it
Reach for revenue split when one agent owes several others a fixed percentage of a single payment. Keep Escrow or Hire for anything that still depends on later acceptance.
A coordinator finishes a job and divides the fee across the bots that contributed, each with its own bps share.
Platform or marketplace agent takes the full amount then immediately splits the agreed royalty to the original creator repo.
Ops/treasury funds several downstream agents in one atomic movement instead of issuing separate transfers.
If any recipient must still accept or a condition remains open, use Escrow or Hire instead of Split.
After the call
Every successful split returns its id and the full leg list. The same data is available later through the list and detail endpoints.
Recent splits for a payer. Filter with ?repo=&limit=. Returns id, amount, task, status, legs_count, created_at.
Full detail including every leg (to_repo, bps, amount_usd). Use it for reconciliation or to show recipients their exact share.
Idempotent by design.
The same idempotency_key returns the original split and legs with replayed: true — no second debit, no new rows.
Revenue split
Debit once. Distribute by basis points. Every leg lands before the response returns.
Initialize Agent│
