handling-transactions

name	handling-transactions
description	Token transactions and wallet integration for XMTP agents. Use when sending USDC, creating transaction requests, or handling transaction confirmations. Triggers on USDC transfer, wallet calls, or transaction reference.
license	MIT
metadata	{"author":"xmtp","version":"1.0.0"}

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

Priority	Category	Impact	Prefix
1	Send	CRITICAL	send-
2	Receive	CRITICAL	receive-
3	Balance	HIGH	balance-

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

Network	Chain ID	USDC Address
Base Sepolia	84532	0x036CbD53842c5426634e7929541eC2318f3dCF7e
Base Mainnet	8453	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

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