Handling Transactions

XMTP transactions

Send and receive token transactions using wallet_sendCalls (EIP-5792) specification.

When to apply

Reference these guidelines when:

• Sending USDC or other tokens
• Creating transaction requests
• Handling transaction confirmations
• Checking token balances
• Working with smart contract wallets

Rule categories by priority

Quick reference

Send (CRITICAL)

• send-usdc-transfer - Create USDC transfer requests
• send-wallet-calls - Send wallet_sendCalls messages

Receive (CRITICAL)

• receive-transaction-reference - Handle transaction confirmations

Balance (HIGH)

• balance-check - Check USDC balance

Supported networks

Quick start

import { validHex } from "@xmtp/agent-sdk";

// Check balance using viem
const balance = await getUSDCBalance("base-sepolia", validHex(address));

// Create USDC transfer calls (EIP-5792)
const calls = createUSDCTransferCalls(
  "base-sepolia",
  validHex(fromAddress),
  validHex(toAddress),
  1000000 // 1 USDC (6 decimals)
);
await ctx.conversation.sendWalletSendCalls(calls);

Implementation snippets

USDC token config:

const USDC_TOKENS: Record<string, { address: string; decimals: number }> = {
  "base-sepolia": { address: "0x036CbD53842c5426634e7929541eC2318f3dCF7e", decimals: 6 },
  "base-mainnet": { address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", decimals: 6 },
};

Get USDC balance:

import { createPublicClient, formatUnits, http } from "viem";
import { baseSepolia, base } from "viem/chains";

const getUSDCBalance = async (networkId: string, address: HexString): Promise<string> => {
  const token = USDC_TOKENS[networkId];
  const client = createPublicClient({
    chain: networkId === "base-mainnet" ? base : baseSepolia,
    transport: http(),
  });
  const balance = await client.readContract({
    address: token.address as HexString,
    abi: [{ inputs: [{ name: "account", type: "address" }], name: "balanceOf", outputs: [{ type: "uint256" }], stateMutability: "view", type: "function" }],
    functionName: "balanceOf",
    args: [address],
  });
  return formatUnits(balance, token.decimals);
};

Create USDC transfer calls:

import { toHex } from "viem";

const createUSDCTransferCalls = (
  networkId: string, from: HexString, to: string, amount: number
): WalletSendCalls => {
  const token = USDC_TOKENS[networkId];
  const data = `0xa9059cbb${to.slice(2).padStart(64, "0")}${BigInt(amount).toString(16).padStart(64, "0")}`;
  return {
    version: "1.0",
    from,
    chainId: toHex(networkId === "base-mainnet" ? 8453 : 84532),
    calls: [{ to: token.address as HexString, data: validHex(data) }],
  };
};

How to use

Read individual rule files for detailed explanations:

rules/send-usdc-transfer.md
rules/receive-transaction-reference.md
rules/balance-check.md