Quick Start

This quick start shows how a referrer dapp can create and follow a task on testnet using the official Exec402 SDKs.

1. Prerequisites

• An EVM wallet (e.g. MetaMask) with testnet funds (Base Sepolia or Optimism Sepolia).
• A React app using wagmi / viem (or compatible).
• Node.js and a package manager.

2. Install the SDKs

Exec402 exposes a JavaScript/TypeScript client (@exec402/core) and a small React wrapper (@exec402/react):

npm install @exec402/core @exec402/react wagmi viem

@exec402/core contains the ExecClient and core types.
@exec402/react provides a context and hooks on top of it.

3. Wrap your app with ExecProvider

In your root component, create an Exec402 context. The network="testnet" setting points to the currently supported testnets (Base Sepolia, Optimism Sepolia).

import { ExecProvider } from "@exec402/react";
 
export function App() {
  return (
    <ExecProvider network="testnet">
      {/* your existing app, with wagmi provider etc. */}
    </ExecProvider>
  );
}

Inside this tree you can access the underlying ExecClient via hooks.

4. Create a call task

When a user triggers an action that should be executed on-chain and paid via Exec402, call the Exec canister using the useCall hook.

import { useCall } from "@exec402/react";
 
function PayAndExecuteButton() {
  const { mutateAsync: call, isPending } = useCall();
 
  async function onClick() {
    const result = await call({
      chainId: 84532,                 // Base Sepolia
      target: "0xTargetContract",     // contract you ultimately want to call
      data: "0x...",                  // encoded calldata (via viem/ethers)
      amount: "1000000",              // 1 USDC, smallest unit
      token: "0xUsdcTokenOnBaseSepolia",
      referrer: "0xYourDappAddress",  // where referrer fees should go
      description: "Demo Exec402 call",
    });
 
    console.log("Task created:", result.taskId, "payer:", result.payer);
  }
 
  return (
    <button onClick={onClick} disabled={isPending}>
      {isPending ? "Creating task..." : "Pay & Execute via Exec402"}
    </button>
  );
}

Behind the scenes:

• The SDK sends a POST /call request to the Exec canister.
• If payment is required, the canister returns an HTTP 402 response with x402 payment requirements.
• The SDK’s x402 interceptor asks the user’s wallet to sign the payment, retries the request with an X-PAYMENT header, and receives a taskId.

5. Observe task status

You can read a single task or list tasks using hooks like useTask / useTasks from @exec402/react, or directly via ExecClient:

import { useTask } from "@exec402/react";
 
function TaskStatus({ taskId }: { taskId: string }) {
  const { data: task } = useTask(taskId);
 
  if (!task) return null;
  return <div>Status: {task.status}</div>; // Pending / Executed / Expired
}

On the backend or in a script, you can use ExecClient.getTask / listTasks from @exec402/core to inspect tasks programmatically.

6. Executors handle on-chain execution

Once a task is created:

• The user is done—they signed once, and can close the app.
• Executors (such as the reference executor-bot in the Exec402 GitHub org) continuously poll the Exec canister for pending tasks.
• For each profitable task, an executor:
  • calls ExecCore.call or ExecCore.transfer on the target chain,
  • uses the stored permit to pull tokens from the payer,
  • pays gas and receives its share of the fee.

You do not need to run an executor to use Exec402 as a referrer, but you can if you want to earn execution fees.

7. Verify final status (optional)

If you want a single helper that checks both the canister and the chain, use ExecClient.verify:

import { ExecClient } from "@exec402/core";
import { createPublicClient, http } from "viem";
import { baseSepolia } from "viem/chains";
 
const publicClient = createPublicClient({
  chain: baseSepolia,
  transport: http(),
});
 
const execClient = new ExecClient({ network: "testnet", signer: walletClient });
 
const task = await execClient.verify(publicClient, taskId as `0x${string}`);
console.log(task.status, task.txHash);

From here you can:

• Read the Referrers guide to design how Exec402 fits into your product.
• Check Executors if you want to run an executor-bot and see links to the reference implementation.
• Dive into the Protocol Overview for roles, tasks, and fee mechanics.
• Try the refuel402  for a live example dapp built on Exec402.