Builder Revenue

Build an app on the V2 main pool, earn a share of protocol fees, and claim your revenue in FWA.

Build a storefront, game interface, or community app that lets people purchase from FWA's main pool. Your contract forwards the purchase, FWA handles allocation and settlement, and your app earns a share of the protocol fees generated by that purchase.

The default builder share is 15% of eligible protocol fees. Revenue accrues as an ETH allowance that your contract spends to claim FWA tokens. The share comes out of protocol proceeds; it adds no protocol charge to the purchase and does not reduce the purchaser's payout or the depositor's return. Routing adds gas.

How your app gets credited

The builder is the immediate caller of FWAV2.acquire, provided that caller differs from the named purchaser. For a typical app, the path is customer wallet → your contract → FWA main pool. Your contract passes the customer's address as the purchaser.

No builder registration or approval is required. A website that sends the customer directly to the pool does not earn this share, and a referral link alone does not establish attribution. The allowance belongs to the calling contract, so it needs a way to claim and deliver its rewards to your treasury.

What you earn

After allocation. A successful allocation credits your share of the gross protocol acquisition fee. The separate VRF service fee is excluded. Expired or refunded requests earn nothing.
After settlement. The same builder can earn a second credit from the actual protocol fee when that listing is resolved. The original caller keeps attribution even if someone else submits the settlement transaction.

Read builderRewardBps() on the pool's linked FWAV2Rewards contract for the current share. Its owner can configure 0% through 25%; 1,500 basis points means 15%. Each request records its eligible share when submitted, so later changes do not alter that request's acquisition or settlement share. The settlement fee itself uses the fee actually charged when the listing resolves.

For example, with a 1% protocol acquisition cut and a 15% builder share, a 1 ETH acquisition fee generates a 0.01 ETH gross protocol fee. Your app receives a 0.0015 ETH FWA-buy allowance, and the protocol retains 0.0085 ETH. VRF and transaction gas are separate. This is 0.15% of the acquisition fee under those assumed settings.

Each reward is the eligible protocol fee multiplied by the recorded builder share, rounded down to whole wei. These examples describe fee settings, rather than a guaranteed amount of FWA; token output depends on the market price, trading fees, and price impact when you claim.

Which settlements pay a share

Keep or relist the NFT. Your share comes from the NFT-outcome protocol fee, including equivalent depositor and timeout resolutions. Recognized FWAIR listings have no NFT-outcome fee, so those outcomes add no builder revenue.
Take ETH or FWA. Your share comes from retained backing only when it becomes protocol income. If retained backing is distributed to active depositors, there is no builder share. The empty-pool fallback routes it to the protocol and makes it eligible. These rules also apply to FWAIR cashouts.

If an eligible cashout retains 0.1 ETH for the protocol, a recorded 15% share adds 0.015 ETH to your allowance. The purchaser's cashout stays the same. Each listing pays at most once on final settlement. Relisting closes the old listing; the new listing gets its own attribution if it is later purchased successfully.

Build your integration

Choose the target chain and use the FWAV2 main pool from the deployment list. Read its linked rewards contract and current settings.
Start from the builder reference contracts and integration guide. FWAV2BuilderBase handles purchase forwarding, customer overpayments, and owner-controlled rewards. The deployable FWAV2BuilderExample adds a purchase method for the calling wallet. Deploy your own instance with the pool, its compatible FWATokenTransfer helper, and your owner or multisig. These examples are not part of the protocol deployment.
Have your frontend read pool.quoteAcquisitionPrice() for the per-request acquisition fee, VRF fee, and total. Quote with the intended transaction gas price because the VRF charge depends on it. Send count × total to your contract's purchase method with the customer's accepted price and slippage bounds and a Unix timestamp deadline.
Track the request IDs and successful allocation. Let the named purchaser settle directly with the pool, and let your contract's owner claim builder revenue as it accrues.

In a contract inheriting the reference base, the forwarding method is:

function purchase(
    uint256 count,
    uint256 maxAcquisitionFee,
    uint256 minWeightedValue,
    uint256 maxNegativeSlippageBps,
    uint256 deadline
) external payable returns (uint256[] memory) {
    return _purchaseFor(
        msg.sender,
        count,
        maxAcquisitionFee,
        minWeightedValue,
        maxNegativeSlippageBps,
        deadline
    );
}

The base calls acquire with the customer as purchaser and preserves the pool's guards. maxAcquisitionFee caps the per-request fee excluding VRF; minWeightedValue protects the observed weighted pool value; maxNegativeSlippageBps limits downward drift at processing. Keep the base's refund handling and reentrancy protection when extending it. A relayer integration must explicitly authorize its intended purchaser instead of assuming the caller is the user.

The purchaser retains NFT rights, settlement choices, purchaser epoch rewards, and failed-request refund credits. The example holds immediate overpayments separately for the payer to recover with withdrawPurchaseRefund(recipient). They are customer funds, excluded from builder withdrawals.

Claim revenue to your treasury

Read rewards.tokenBuyAllowance(builderAddress) to see the settled ETH budget available to buy FWA. Acquisition and settlement credits accumulate in this same balance. You can claim the first credit before the purchaser settles, then claim the later credit when it arrives.

As the reference contract's owner, call claimAndQueueBuilderRewards(treasury, minFWAOut, deadline). It spends the allowance on FWA and queues the newly received tokens in the transfer helper for your treasury. Use a current quote, a meaningful minimum output, and a deadline.
Starting in the next block, anyone can call transferHelper.claim(treasury). The tokens go to the named treasury regardless of who submits the transaction.

FWA's transfer rules prevent a normal transfer from an unprivileged builder contract to an ordinary treasury wallet. The reference helper path handles this: the helper must be an enabled distributor with deposits open; your builder contract needs no distributor or hook registration. The reward purchase requires a configured rewards module and available market liquidity.

Normal claims deliver FWA. Recovering the allowance as ETH is an emergency exit available only when the core is in withdraw-only mode and has no unsettled acquisitions.

Test and track

Use the Sepolia deployment and testing guide to check forwarding, successful allocation, expired requests, settlement, customer refunds, and treasury claims against the target deployment's available dependencies. This mechanism belongs to the V2 main pool; custom pools have separate interfaces and fee rules.

For attribution, read acquisitionBuilderRewardBps(requestId) and settlementRewards(listingId) on Rewards. Track AcquisitionTokenAccrued and SettlementBuilderRewardAccrued events for credits, and reconcile them with the current allowance after claims. Index request and listing IDs together with the pool address.