Skip to content

xmtplabs/xmtp-agent-examples / skills/handling-transactions

handling-transactions

Verified

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.

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

PriorityCategoryImpactPrefix
1SendCRITICALsend-
2ReceiveCRITICALreceive-
3BalanceHIGHbalance-

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

NetworkChain IDUSDC Address
Base Sepolia845320x036CbD53842c5426634e7929541eC2318f3dCF7e
Base Mainnet84530x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

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
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 319kUpdated Claude CodeCodexVerifiedInstall