handling-transactions - SKILL.md Agent Skill

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

Use the SDK 2.2.0 transaction helpers with viem chains and bigint amounts:

import {
  createERC20TransferCalls,
  getERC20Balance,
  getERC20Decimals,
  validHex,
} from "@xmtp/agent-sdk";
import { formatUnits, parseUnits } from "viem";
import { base, baseSepolia } from "viem/chains";

const CHAIN = baseSepolia; // or base for mainnet
const USDC_ADDRESS = "0x036CbD53842c5426634e7929541eC2318f3dCF7e"; // Base Sepolia

// Get decimals (e.g. 6 for USDC)
const decimals = await getERC20Decimals({ chain: CHAIN, tokenAddress: USDC_ADDRESS });

// Check balance (returns bigint; format for display)
const balance = await getERC20Balance({
  chain: CHAIN,
  tokenAddress: USDC_ADDRESS,
  address: validHex(address),
});
await ctx.conversation.sendText(`Your balance: ${formatUnits(balance, decimals)} USDC`);

// Create USDC transfer calls (EIP-5792)
const calls = createERC20TransferCalls({
  chain: CHAIN,
  tokenAddress: USDC_ADDRESS,
  from: validHex(fromAddress),
  to: validHex(toAddress),
  amount: parseUnits("1", decimals), // 1 USDC
  description: `Transfer 1 USDC on ${CHAIN.name}`,
});
await ctx.conversation.sendWalletSendCalls(calls);

Implementation snippets

USDC addresses (viem chains):

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

const CHAIN = baseSepolia; // or base
const USDC_ADDRESS = CHAIN.id === 8453
  ? "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"   // Base Mainnet
  : "0x036CbD53842c5426634e7929541eC2318f3dCF7e";  // Base Sepolia

Get ERC-20 balance (SDK 2.2.0):

import { getERC20Balance, getERC20Decimals } from "@xmtp/agent-sdk";
import { formatUnits } from "viem";

const balance = await getERC20Balance({
  chain: CHAIN,
  tokenAddress: USDC_ADDRESS,
  address: validHex(address),
});
const decimals = await getERC20Decimals({ chain: CHAIN, tokenAddress: USDC_ADDRESS });
const formatted = formatUnits(balance, decimals);

Create ERC-20 transfer calls (SDK 2.2.0):

import { createERC20TransferCalls } from "@xmtp/agent-sdk";
import { parseUnits } from "viem";

const walletSendCalls = createERC20TransferCalls({
  chain: CHAIN,
  tokenAddress: USDC_ADDRESS,
  from: validHex(senderAddress),
  to: validHex(recipientAddress),
  amount: parseUnits("2.5", 6), // 2.5 USDC
  description: "Transfer 2.5 USDC",
});
await ctx.conversation.sendWalletSendCalls(walletSendCalls);

How to use

Read individual rule files for detailed explanations:

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