Skip to main content
The ERC20 Transfer Ability enables Vincent Apps to send ERC20 tokens on behalf of Vincent Users using their Vincent Wallet (PKP). It performs thorough prechecks, enforces policy constraints, and executes transfers securely inside Lit Actions.

​
Key Features

  • Secure transaction signing with Vincent Wallets (PKP)
  • Automatic token decimals detection from the token contract
  • Balance checks for both native gas and token amounts
  • Policy integration (e.g., send-counter rate limiting)
  • Clear success and error result schemas

​
How It Works

The ERC20 Transfer Ability is built using the Vincent Ability SDK and operates in two phases:
1

Precheck Phase

Validates recipient address, token address, and amount:
  • Validates recipient address, token address, and amount
  • Requires a valid rpcUrl to connect to the network
  • Reads token decimals from the contract and parses the amount accordingly
  • Checks the Vincent Wallet token balance and estimates transfer gas, then verifies native balance is sufficient
2

Execution Phase

Executes the ERC20 transfer transaction:
  • Uses the provided chain name to obtain an RPC via Lit.Actions.getRpcUrl({ chain })
  • Reads token decimals and parses the amount to smallest units
  • Commits allowed policies (e.g., rate-limiting) before the transfer
  • Calls transfer(to, amount) on the ERC-20 contract via laUtils and returns the txHash

​
Getting Started

Depending on your role in the Vincent Ecosystem, you’ll be interacting with this Ability in different ways. Click on the link below that matches your role to see how to get started:
  • Vincent App Developers: If you’re building a Vincent App that needs to transfer ERC20 tokens, go here.
  • Vincent App Delegatees: If you’re executing this ability on behalf of Vincent App Users, go here.

​
Adding the Ability to your Vincent App

If you want to enable your App Delegatees to transfer ERC20 tokens on behalf of your Vincent App Users, you can add this Ability to your App. Adding Abilities to your Vincent App is done using the Vincent App Dashboard. Visit the Create Vincent App guide to learn more about how to add Abilities to your App during creation, or check out the Updating Your App guide to learn how to add Abilities to an existing App.

​
Executing the Ability as a Vincent App Delegatee

Before executing ERC20 transfer operations, the following conditions must be met. You can use the Ability’s precheck function to check if these conditions are met, or you can check them manually.
  • Gas Balance: The Vincent App User’s Vincent Wallet must have sufficient native tokens (ETH, MATIC, etc.) to pay for the transfer transaction gas fees.
  • Token Balance: The Vincent App User’s Vincent Wallet must have sufficient balance of the ERC20 token to cover the transfer amount.
  • Valid Addresses: The recipient address and token contract address must be valid Ethereum addresses.
To learn more about executing Vincent Abilities, see the Executing Abilities guide.

​
Executing the precheck Function

This Ability’s precheck function validates all prerequisites for executing an ERC20 token transfer and provides detailed validation information.
  • Parameters
  • Implementation
  • Response
Before executing the precheck function, you’ll need to provide the following parameters for the ERC20 transfer operation:
{
  /** RPC URL used for precheck validations */
  rpcUrl: string;
  /** Chain name used during execute (e.g., 'base', 'ethereum', 'polygon') */
  chain: string;
  /** Recipient address */
  to: string;
  /** ERC-20 token contract address */
  tokenAddress: string;
  /** Amount in human-readable string (e.g., "1.23") */
  amount: string;
}
Notes:
  • amount must be a positive decimal string
  • Token decimals are read from the token contract; you do not pass tokenDecimals

​
Executing the execute Function

This Ability’s execute function performs the actual ERC20 token transfer.
  • Parameters
  • Implementation
  • Response
The execute function expects the same parameters as the precheck function:
{
  /** RPC URL used for precheck validations */
  rpcUrl: string;
  /** Chain name used during execute (e.g., 'base', 'ethereum', 'polygon') */
  chain: string;
  /** Recipient address */
  to: string;
  /** ERC-20 token contract address */
  tokenAddress: string;
  /** Amount in human-readable string (e.g., "1.23") */
  amount: string;
}

​
Important Considerations

The Vincent Wallet must have enough native tokens to pay for gas. Precheck attempts to estimate gas and compare against the wallet’s native balance.
The ability reads decimals from the token contract; do not pass tokenDecimals.
The chain parameter is used to obtain an RPC during execution via Lit.Actions.getRpcUrl. Use supported EVM chain names (e.g., base, ethereum).
The ability commits allowed policy updates before executing the transfer (e.g., send-counter rate limiting).

​
Error Handling

  • Insufficient Gas Balance: The Vincent App User’s Vincent Wallet doesn’t have enough native tokens for gas fees
  • Insufficient Token Balance: The Vincent App User’s Vincent Wallet doesn’t have enough tokens to cover the transfer amount
  • Invalid Addresses: Invalid recipient address or token contract address
  • Invalid Amount: Transfer amount is not a valid positive number
  • Network Issues: RPC URL inaccessible or network connectivity problems
  • Policy Violations: Transfer violates configured policies (e.g., rate limiting)
⌘I