Skip to content

Quickstart

By the end of this guide your agent will have a smart account on Avalanche Fuji, a KUMPLY attestation, and a transaction on-chain whose gas was paid by 0xGasless. Your account never holds AVAX.

Time: about 10 minutes. Cost: nothing; everything runs on testnet.

  • Node.js 18 or newer. Check with node --version.
  • The KUMPLY lane URL. The KUMPLY team shares it with workshop participants. It looks like https://paymaster.0xgasless.com/v1/43113/rpc/<lane API key>.
  • A terminal and a code editor.
  1. Create the project folder

    Make an empty folder for the quickstart and open it:

    Terminal window
    mkdir kumply-fuji-quickstart
    cd kumply-fuji-quickstart
  2. Add package.json

    Create package.json with this content. It pins the 0xGasless smart account SDK and adds four scripts you will run in the next steps.

    package.json
    {
    "name": "kumply-fuji-quickstart",
    "version": "1.0.0",
    "private": true,
    "type": "module",
    "description": "Send a gasless transaction on Avalanche Fuji, sponsored by 0xGasless for KUMPLY-attested agents",
    "scripts": {
    "address": "tsx quickstart.ts address",
    "verify": "tsx quickstart.ts verify",
    "send": "tsx quickstart.ts send",
    "dry-run": "tsx quickstart.ts send --dry"
    },
    "dependencies": {
    "@0xgasless/smart-account": "0.0.13",
    "dotenv": "^16.4.5",
    "viem": "^2.21.0"
    },
    "devDependencies": {
    "tsx": "^4.19.0"
    }
    }

    Then install the dependencies:

    Terminal window
    npm install
  3. Add your settings in .env

    Create a file named .env and paste the lane URL you received into PAYMASTER_URL. Leave PRIVATE_KEY empty: the next step creates it for you.

    .env
    PAYMASTER_URL=https://paymaster.0xgasless.com/v1/43113/rpc/<lane API key>
    BUNDLER_URL=https://bundler.0xgasless.com/43113
    RPC_URL=https://api.avax-test.network/ext/bc/C/rpc
    PRIVATE_KEY=
  4. Add quickstart.ts

    Create quickstart.ts and paste the full script below. It contains everything the remaining steps need: the Fuji contract addresses, the attestation check and the sponsored send.

    Show quickstart.ts
    quickstart.ts
    // Gasless transaction on Avalanche Fuji, sponsored by the 0xGasless paymaster
    // for agents that hold a KUMPLY attestation.
    //
    // npm run address create (or load) your signer and print your smart account address
    // npm run verify read your attestation from KUMPLY's AttestationStore
    // npm run send send a sponsored transaction (npm run dry-run asks the paymaster without sending)
    import "dotenv/config";
    import { existsSync, readFileSync, writeFileSync } from "node:fs";
    import { createPublicClient, createWalletClient, http, parseAbi } from "viem";
    import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
    import { avalancheFuji } from "viem/chains";
    import {
    createECDSAOwnershipValidationModule,
    createSmartAccountClient,
    PaymasterMode,
    } from "@0xgasless/smart-account";
    // 0xGasless smart account contracts on Fuji. The SDK defaults to mainnet
    // addresses, so Fuji needs these overrides.
    const FUJI = {
    factory: "0xF0b3f5146c2725e36d78F5029bc560eDfc67ADe0",
    implementation: "0x8aF33bE7af021A6075aeB19b076fC75Bfbd2c5c3",
    fallbackHandler: "0xdA62055b0730d1d0621aD0A446DcD6057a6d951E",
    ecdsaModule: "0xcfb0BA514aa398085D63eC70cfEa6EC7f1094E8F",
    } as const;
    // KUMPLY AttestationStore on Fuji. verify() is a free view call.
    const KUMPLY_REGISTRY = "0xa3Bc5564A18e107807aF41fF2a5215Db050b22dD";
    const KUMPLY_ABI = parseAbi([
    "function verify(address _subject) view returns (bool verified, uint32 tier, uint64 timestamp, uint64 expiry)",
    ]);
    const RPC_URL = process.env.RPC_URL || "https://api.avax-test.network/ext/bc/C/rpc";
    const BUNDLER_URL = process.env.BUNDLER_URL || "https://bundler.0xgasless.com/43113";
    const PAYMASTER_URL = process.env.PAYMASTER_URL ?? "";
    function loadOrCreateKey(): `0x${string}` {
    if (process.env.PRIVATE_KEY) return process.env.PRIVATE_KEY as `0x${string}`;
    const key = generatePrivateKey();
    let env = existsSync(".env") ? readFileSync(".env", "utf8") : existsSync(".env.example") ? readFileSync(".env.example", "utf8") : "";
    env = /^PRIVATE_KEY=.*$/m.test(env) ? env.replace(/^PRIVATE_KEY=.*$/m, `PRIVATE_KEY=${key}`) : `${env}\nPRIVATE_KEY=${key}\n`;
    writeFileSync(".env", env);
    process.env.PRIVATE_KEY = key;
    console.log("Created a new signer key and saved it to .env (keep it private).");
    return key;
    }
    async function smartAccount() {
    const signer = createWalletClient({
    account: privateKeyToAccount(loadOrCreateKey()),
    chain: avalancheFuji,
    transport: http(RPC_URL),
    });
    const ecdsaModule = await createECDSAOwnershipValidationModule({ signer, moduleAddress: FUJI.ecdsaModule });
    const account = await createSmartAccountClient({
    signer,
    chainId: avalancheFuji.id,
    rpcUrl: RPC_URL,
    bundlerUrl: BUNDLER_URL,
    paymasterUrl: PAYMASTER_URL,
    factoryAddress: FUJI.factory,
    implementationAddress: FUJI.implementation,
    defaultFallbackHandler: FUJI.fallbackHandler,
    defaultValidationModule: ecdsaModule,
    activeValidationModule: ecdsaModule,
    });
    return { account, address: (await account.getAccountAddress()) as `0x${string}`, owner: signer.account.address };
    }
    async function verify(address: `0x${string}`) {
    const client = createPublicClient({ chain: avalancheFuji, transport: http(RPC_URL) });
    const [verified, tier, , expiry] = await client.readContract({
    address: KUMPLY_REGISTRY,
    abi: KUMPLY_ABI,
    functionName: "verify",
    args: [address],
    });
    return { verified, tier: Number(tier), expiry: Number(expiry) };
    }
    async function main() {
    const command = process.argv[2] ?? "address";
    const dry = process.argv.includes("--dry");
    const { account, address, owner } = await smartAccount();
    if (command === "address") {
    console.log(`Signer (EOA): ${owner}`);
    console.log(`Smart account: ${address}`);
    console.log("\nGet your KUMPLY attestation for the SMART ACCOUNT address above, then run: npm run verify");
    return;
    }
    const att = await verify(address);
    console.log(`Smart account ${address}`);
    console.log(
    att.verified
    ? `KUMPLY attestation: verified, tier ${att.tier}, expires ${new Date(att.expiry * 1000).toISOString().slice(0, 10)}`
    : "KUMPLY attestation: none. The paymaster will refuse to sponsor this account.",
    );
    if (command === "verify") return;
    if (command !== "send") throw new Error(`Unknown command "${command}". Use address, verify or send.`);
    if (!PAYMASTER_URL || PAYMASTER_URL.includes("KUMPLY_LANE_API_KEY")) {
    throw new Error("Set PAYMASTER_URL in .env to the KUMPLY lane URL from the workshop hosts.");
    }
    // A harmless 0-value call to your own account. The first one also deploys the account.
    const tx = { to: address, data: "0x" as const, value: 0n };
    const sponsored = { paymasterServiceData: { mode: PaymasterMode.SPONSORED } };
    try {
    if (dry) {
    const op = await account.buildUserOp([tx], sponsored);
    console.log(`Paymaster: SPONSORED (signed ${String(op.paymasterAndData).length / 2 - 1} bytes). Nothing was sent.`);
    return;
    }
    const res = await account.sendTransaction(tx, sponsored);
    console.log(`Paymaster: SPONSORED. userOpHash ${res.userOpHash}, waiting for the bundler...`);
    const receipt = await res.wait();
    const hash = receipt.receipt?.transactionHash;
    console.log(`Mined: https://testnet.snowtrace.io/tx/${hash}`);
    console.log("Gas was paid by the 0xGasless paymaster. Your account holds no AVAX.");
    } catch (err) {
    const e = err as Error & { details?: string };
    const reason = (e.details ?? e.message).split("\n")[0].replace(/^"|"$/g, "").replace(/^Error coming from Paymaster: /, "");
    console.log(`Paymaster: REFUSED. ${reason}`);
    process.exitCode = 1;
    }
    }
    main().catch((err) => {
    console.error(err instanceof Error ? err.message : err);
    process.exit(1);
    });
  5. Create your agent’s smart account

    Terminal window
    npm run address

    This creates a signing key, saves it to .env, and prints two addresses:

    Created a new signer key and saved it to .env (keep it private).
    Signer (EOA): 0x78D7…b4F1
    Smart account: 0x395B…D43B
    • The signer is the key that controls the account.
    • The smart account is your agent’s on-chain address. It is created on-chain by your first transaction, but its address is fixed from now on.
  6. Get the smart account attested by KUMPLY

    Send the smart account address from step 5 to the KUMPLY team. At a workshop they issue a demo Tier 5 attestation on Fuji for it.

  7. Check the attestation

    Terminal window
    npm run verify

    This reads KUMPLY’s AttestationStore directly. It’s a free read, so no gas is used.

    Smart account 0x395B…D43B
    KUMPLY attestation: verified, tier 5, expires 2027-09-25
  8. Send your gasless transaction

    First ask the paymaster without sending anything:

    Terminal window
    npm run dry-run
    Paymaster: SPONSORED (signed 276 bytes). Nothing was sent.

    Then send it for real:

    Terminal window
    npm run send
    Paymaster: SPONSORED. userOpHash 0x…, waiting for the bundler...
    Mined: https://testnet.snowtrace.io/tx/0x…
    Gas was paid by the 0xGasless paymaster. Your account holds no AVAX.

    Open the Snowtrace link to see the transaction. The first one also deploys your smart account, and the paymaster pays for both.

  1. Your smart account built a UserOperation: a harmless 0-value call to itself.
  2. The 0xGasless paymaster read verify() on KUMPLY’s AttestationStore for your smart account.
  3. The account is attested at Tier 5, so the paymaster signed the sponsorship and the bundler put the operation on-chain.

An account without an attestation stops at step 2:

Paymaster: REFUSED. Sponsorship refused by attestation gate: sender 0x… has no KUMPLY attestation