---
title: "x402aff: The affiliation layer for the agent economy"
description: "Make your x402 endpoint affiliate-ready in one line. Apps that send paying users get a cut, enforced on-chain at settlement."
canonical: https://www.x402aff.xyz/
last-updated: 2026-09-30
---

# x402aff: Split every payment.

> Builder-code affiliation for x402 sellers. Give the apps that send you paying users a cut, enforced on-chain at settlement through an ownerless, immutable 0xSplits contract.

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.

## When to use x402aff

- You run a paid API behind x402 and want other apps, agents, or builders to send you paying users in exchange for a cut of each payment.
- You want that affiliate cut enforced on-chain at settlement, not tracked in a database and paid out monthly.
- You build a client app or agent that calls x402 APIs and want to earn from the payments you drive (tag requests with your builder code).
- You need to find or release builder payouts: every split, balance, and permissionless claim for a seller.

Not for: networks other than Base mainnet, facilitators other than CDP, or custodial payout schemes. x402aff is a library; it has no hosted API to call for payments.

How to use it: install x402aff from npm (TypeScript, with viem) or PyPI (Python) and wire Affiliation into your x402 route; buyers add one builder-code extension. To answer questions about the kit, call the read-only MCP server at https://www.x402aff.xyz/api/mcp or follow the agent skill at https://www.x402aff.xyz/skills/x402aff/SKILL.md.

## Install

- npm: `npm install x402aff viem`
- pip: `pip install x402aff`

## The kit in four numbers

- 10% 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

## Off-chain affiliate promises vs. an on-chain split

Off-chain affiliate program: 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.

x402aff: 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.

## How payment works

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.

1. Request (Buyer's app): The buyer's app calls your route with its builder code in an X-Builder-Code header.
2. 402 (Your API): Your server answers with payTo set to the (you, builder) split address. Deterministic CREATE2, same every time.
3. Settle (CDP facilitator): The stock CDP facilitator settles the buyer's gasless USDC payment straight into the split and writes a/s/w on-chain.
4. Payout (0xSplits): Anyone calls distribute. 10% to the builder, 90% to you. Nobody can change where it goes.

## One Affiliation API in TypeScript and Python

Both SDKs ship the same Affiliation facade and resolve the identical split address, asserted byte for byte.

### TypeScript

```bash
npm install x402aff viem
```

```ts
import { Affiliation } from "x402aff";

const aff = new Affiliation({ appCode: "bc_yourcode", sellerPayout: "0x..." });

// drop-in x402 DynamicPayTo for express, hono, next
app.use(paymentMiddleware({ payTo: aff.payTo, extensions: aff.extensions }));

// release payouts later (permissionless)
const { calls, balanceUnits } = await aff.release("bc_alice");
```

### Python

```bash
pip install x402aff
```

```python
from x402aff import Affiliation

aff = Affiliation(app_code="bc_yourcode", seller_payout=YOUR_WALLET)

PaymentOption(..., pay_to=aff.pay_to)        # per-request split
RouteConfig(..., extensions=aff.extensions)  # declares your code a

calls, balance = aff.release("bc_alice")     # permissionless payout
```

Buyer side, one line: `extensions: [builderCode("bc_alice")]`. TypeScript uses the official @x402/extensions/builder-code. Python ships BuilderCodeClientExtension.

## Everything a seller needs, nothing to operate

- Change the cut: 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.
- More than two recipients: Platform fee, partner, referrer. Any allocations that sum to 10000 work; address prediction and distribute follow.
- Release payouts: aff.pending() finds every builder who paid you straight from CDP's index. No local ledger.
- Claims dashboard: aff.splits_payload() returns every split, balance, and a permissionless claim, ready for a GET /splits route.
- Find every kit payment: The buyer extension stamps a shared x402aff marker, so one SQL query finds every kit-routed payment across all sellers.
- Any language: Three view calls against two contracts. Port it to Go or Rust in an afternoon.

## Money in a split can only reach two addresses

The 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.

- Trigger distribute and name yourself the distributor: Pays out. Builder 10%, seller 90%, you get 0.
- Distribute with a tampered struct: Reverts. The wallet hash-checks the struct.
- Deploy a hijacking split at the funded address: Impossible. Different params, different CREATE2 address.
- updateSplit or setPaused to redirect or freeze: Reverts. The split is ownerless.
- Front-run the deterministic deploy: Pays out. Same address, same recipients, still pays builder and seller.

Contracts: 0xSplits PushSplit factory 0x8E8eB0cC6AE34A38B67D5Cf91ACa38f60bc3Ecf4, Base Builder Codes registry 0x000000BC7E6457e610fe52Dcc0ca5b3ce59C8E80.

## FAQ

### Which networks work?

Base mainnet with the CDP facilitator. The registry and factory the kit reads exist only there, and CDP writes the attribution.

### Do I need a private key?

No. Your server only puts an address in payTo. The buyer signs a gasless payment, and anyone can call distribute.

### What if the builder code is unknown?

payTo falls back to your wallet. The payment still succeeds, it just is not split.

### Who pays gas?

The buyer's payment is gasless. Distribute costs a few cents, and anyone can call it: you, a keeper, or the builder.

### Is the s tag proof of who drove the payment?

No. It is a self-asserted routing tag. It says where money goes, not who is entitled to it, which is the right level for an affiliate program.

### Why do payouts land a couple of units light?

A split keeps 1 base unit warm and floors each share, so about 2 base units stay behind.

### Which RPC should I use?

A paid one via X402_BASE_RPC. The public RPC rate-limits, and a failed resolve falls back to your wallet, unsplit.

## More

- [Developer docs](https://www.x402aff.xyz/developers)
- [About](https://www.x402aff.xyz/about)
- [Contact](https://www.x402aff.xyz/contact)
- [Privacy](https://www.x402aff.xyz/privacy)
- [GitHub](https://github.com/MiroShark/x402aff)
- [Claims dashboard](https://www.x402aff.xyz/dashboard)