Attribution

Sweepster supports two attribution modes. You can use either or both.

Mode 1 — Off-chain API key (recommended for most integrations)

Pass your builder API key in the POST /quote request body:

const response = await fetch("https://api.sweepster.xyz/quote", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    owner: "0x...",
    tokenIn: "0x...",
    amountIn: "1000000",
    tokenOut: "0x...",
    destination: "0x...",
    destChainId: 42161,
    tier: "tier1",
    subscriptionActive: false,
    userId: "user_abc",
    apiKey: "sk_live_...",   // <-- your builder API key
  }),
});

The orchestrator reads your API key from the request body, calls the builder-backend /attribute endpoint (using the x-api-key header internally), and embeds your builderId and builderFee into the unsigned order.

Important: The orchestrator forwards your API key to the builder-backend via the x-api-key HTTP header — not the JSON body. This is enforced in the orchestrator's buildAttributor. When calling /attribute directly, always pass the key as an HTTP header.

Verifying attribution

Call POST /attribute on the builder-backend to confirm your key is active:

const res = await fetch("https://builders.sweepster.xyz/attribute", {
  method: "POST",
  headers: { "x-api-key": "sk_live_..." },
});
const attribution = await res.json();
// { builderId, builderBps, maxBuilderBps, payoutAddress }

Mode 2 — On-chain signed fields

For maximum trustlessness, embed the builder address and builderFee amount directly in the SweepOrder that the user signs. The contract reads these fields from the signed order and enforces them atomically.

The user's signature covers:

SweepOrder.builder     = "0xYourBuilderAddress"
SweepOrder.builderFee  = <fee amount in token units>

Because these fields are signed via EIP-712, they cannot be changed by the relayer. The on-chain contract will skim exactly builderFee and route it to the builder address.

When to use on-chain attribution

• White-label apps where the builder wants immutable on-chain proof of attribution
• Situations where the relayer is untrusted and the builder wants the signed order to be self-enforcing

Hybrid attribution

You can use both modes simultaneously:

• API key → enables the builder-backend accrual ledger and off-chain analytics
• On-chain fields → immutable settlement proof and atomic on-chain split

The orchestrator reconciles both when the order is settled.

Attribution precedence

If both apiKey and on-chain builder are set, the on-chain fields take precedence for fee skimming. The accrual ledger records both.

Related

• Builder Program Overview
• Payouts
• Builder Backend API