Builder-code affiliation for x402
Give the apps that send you paying users a cut, enforced on-chain at settlement. One line on the client, no facilitator of your own to run.
npm install x402aff viem10%
default builder cut
1000 bps, set anywhere from 0 to 10000
1 line
on the buyer's client
one extension on the x402 client
0
contracts to run
nothing you write, deploy, or audit
7
mainnet-fork tests
5 of them adversarial
Before
You track referrals in a database, pay out monthly, and ask builders to trust your spreadsheet. You can change the rate, pause payouts, or forget.
After
The payment itself lands in an ownerless 0xSplits contract whose recipients and ratio are fixed at its address. Nobody, including you, can redirect the builder's cut.
Base Builder Codes put three tags on a paid request: a (you, the API), s (the builder that drove it), w (the facilitator). The kit turns s into money with one move.
The buyer's app calls your route with its builder code in an X-Builder-Code header.
Your server answers with payTo set to the (you, builder) split address. Deterministic CREATE2, same every time.
The stock CDP facilitator settles the buyer's gasless USDC payment straight into the split and writes a/s/w on-chain.
Anyone calls distribute. 10% to the builder, 90% to you. Nobody can change where it goes.
10%
Builder
90%
You
Both SDKs ship the same Affiliation facade and resolve the identical split address, asserted byte for byte.
import { Affiliation } from "x402aff";const aff = new Affiliation({ appCode: "bc_yourcode", sellerPayout: "0x..." });// drop-in x402 DynamicPayTo for express, hono, nextapp.use(paymentMiddleware({ payTo: aff.payTo, extensions: aff.extensions }));// release payouts later (permissionless)const { calls, balanceUnits } = await aff.release("bc_alice");Basis points, default 1000. Set X402_BUILDER_SHARE_BPS=1500 or pass it in. The ratio is baked into the address, so old funds stay safe at the old ratio.
Drag to change the cut. Each ratio gets its own split address.
X402_BUILDER_SHARE_BPS=1000Platform fee, partner, referrer. Any allocations that sum to 10000 work; address prediction and distribute follow.
SplitPlan(recipients, allocations)aff.pending() finds every builder who paid you straight from CDP's index. No local ledger.
aff.pending()
aff.splits_payload() returns every split, balance, and a permissionless claim, ready for a GET /splits route.
aff.splits_payload()See one running (opens in a new tab)The buyer extension stamps a shared x402aff marker, so one SQL query finds every kit-routed payment across all sellers.
WHERE builder_code = 'x402aff'Three view calls against two contracts. Port it to Go or Rust in an afternoon.
payoutAddress + isDeployedThe kit deploys no contracts of its own. It reads two canonical contracts and lets the stock CDP facilitator settle into them. Tested against live Base mainnet on a fork.
Attack on a funded split
Result
Trigger distribute and name yourself the distributor
Builder 10%, seller 90%, you get 0
Distribute with a tampered struct
The wallet hash-checks the struct
Deploy a hijacking split at the funded address
Different params, different CREATE2 address
updateSplit or setPaused to redirect or freeze
The split is ownerless
Front-run the deterministic deploy
Same address, same recipients, still pays builder and seller
