Referrers Guide

This page describes how to use Exec402 in your product as a referrer — the agent, dapp, or UI that sources tasks and earns on-chain revenue from the fees it proposes and users confirm.

At a high level:

• You keep owning your product logic and UX.
• Exec402 takes over the “collect payment, create a task, and have executors settle it on-chain later” part.
• For every executed task, a fee that you propose (and the user confirms) is charged and then split on-chain between the protocol, executors, and your referrer address.

Integration patterns

There are several common ways to act as a referrer with Exec402.

1. Pay‑per‑action flows

You expose an action that should charge the user per use, for example:

• “run this on-chain strategy”,
• “mint this NFT”,
• “bridge and stake into this vault”.

With Exec402 and the SDKs:

1. Your frontend collects the parameters for the action.
2. You call the Exec canister (e.g. via ExecClient.call or the useCall hook), specifying:
   • which chain and contract will ultimately be called,
   • calldata,
   • amount, fee, token,
   • your own address as referrer.
3. The SDK handles any x402 402 Payment Required responses by asking the user’s wallet to sign the payment and retrying the request.
4. The Exec canister creates a task and returns a taskId.
5. You watch task status (or index events) and mark the action as completed when execution succeeds.

This pattern is ideal when:

• You want predictable per‑call billing.
• You don’t want users to worry about which chain or how much gas.
• Your own infra should stay as stateless as possible.

2. Usage‑based products and credits

If your product already has a notion of “credits” or “usage units”:

• Map each credit top‑up or usage event to an Exec402 task.
• Charge users in stablecoins or another liquid token on supported chains.
• Use task status and execution events as the canonical source of truth for internal accounting.

Exec402 does not dictate how you model your product, only how payment and execution are handled.

3. Wallet / agent / UI integrations

Wallets, agents, or UI layers can integrate Exec402 as:

• a gasless mode for specific flows,
• a way to route payments for partner dApps or protocols,
• a source of fee revenue via the referrer share.

In this case:

• The wallet or agent acts as the referrer.
• The underlying dApp or protocol can be largely unaware that Exec402 is used under the hood.

Example: minimal button

A minimal React component using @exec402/react might look like:

import { useCall } from "@exec402/react";
 
export function PayAndExecuteButton() {
  const { mutateAsync: call, isPending } = useCall();
 
  async function onClick() {
    const result = await call({
      chainId: 8453,                   // Base mainnet
      target: "0xTargetContract",
      data: "0x...",                   // encoded calldata
      amount: "1000000",               // 1 token in smallest unit
      fee: "300000",                   // 0.3 token fee
      token: "0xPaymentToken",
      referrer: "0xYourReferrerAddress",
      description: "Example Exec402 call",
    });
 
    console.log("Task created:", result.taskId);
  }
 
  return (
    <button onClick={onClick} disabled={isPending}>
      {isPending ? "Creating task..." : "Pay & Execute via Exec402"}
    </button>
  );
}

You are responsible for surfacing amount and fee in your own UI. The Exec canister and x402 layer then carry these values through into the 402 Payment Required response so wallets see the same numbers when asking the user to sign.

Minimal referrer checklist

As a referrer you need to:

1. Decide where Exec402 fits in your product:
   • single feature,
   • new product,
   • or global billing layer.
2. Choose which token(s) and chain(s) you want to start with (see Supported Chains and Permit Types).
3. Use the client SDKs to:
   • call the Exec canister (/call, /transfer) with your referrer address,
   • rely on x402 to handle wallet payments,
   • read tasks and statuses when you need them.
4. Store and display:
   • your referrer address,
   • task identifiers or hashes for support / debugging.
5. Optionally index Exec402 events so you can:
   • show history to users,
   • build analytics dashboards,
   • reconcile internal state.

Being a referrer

Every task includes a referrer address. Fees are split transparently on-chain:

• a fixed 10% protocol fee,
• a configurable referrer share (currently set to 60% of the total fee),
• and the remainder to executors (currently 30% of the total fee).

Referrer fees are paid directly on-chain to your address, which makes it straightforward to:

• share revenue with partners,
• run referral programs,
• attribute volume to different products or frontends.

For example, a dapp can embed a specific referrer address into an external link such as
https://refuel402.com/?referrer=0xYourReferrerAddress, making it easy to track and reward traffic from different partners.

Example flow (high‑level)

1. User clicks “Pay & Execute via Exec402” in your app.
2. Your frontend calls ExecClient.call / useCall with:
   • target chain and contract,
   • calldata,
   • amount, fee, token,
   • your referrer address.
3. The SDK:
   • receives a 402 response from the Exec canister,
   • guides the wallet to sign the x402 payment authorization,
   • retries the request and receives a taskId.
4. The Exec canister records the task and exposes it to executors.
5. An executor picks up the task and executes it on-chain via ExecCore.
6. Referrer and executor fees are paid on-chain according to the configured split.
7. Your app observes the updated task status or events and marks the action as completed in the UI.

For more details on executors and how they decide which tasks to execute, see Executors.