Agent skill

Token Integration Safety

by ccashwell in ccashwell/evm-cortex

Safe integration patterns for non-standard ERC-20 tokens. An agent skill from ccashwell/evm-cortex.

MITAuto-check passedBackend & APIs

Install Token Integration Safety

skills CLI
$ npx skills add ccashwell/evm-cortex --skill token-integration-safety -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install ccashwell/evm-cortex token-integration-safety --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/ccashwell/evm-cortex.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/token-integration-safety .claude/skills/token-integration-safety && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
token-integration-safety
GitHub stars
131
Token cost
~2k tokens
SKILL.md length
326 words
Files
1
Skills in repo
89
Repo updated
First seen
Licence
MIT

At a glance

Safe integration patterns for non-standard ERC-20 tokens. An agent skill from ccashwell/evm-cortex.

  • Building protocols that accept arbitrary tokens
  • SKILL.md covers Always Use SafeERC20, USDT — No Return Value, USDC — 6 Decimals and Blacklist and Fee-on-Transfer Tokens, plus 7 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
  • Tasks that involve Third-party API integration

What it does

Token Integration Safety is an agent skill from ccashwell/evm-cortex. Safe integration patterns for non-standard ERC-20 tokens. Use when building protocols that accept arbitrary tokens. Covers USDT (no return value), USDC (6 decimals, blacklist), fee-on-transfer, rebasing tokens, ERC-777 callbacks, pausable tokens, and Permit2.

Its SKILL.md is about 2k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Backend & APIs, covering Third-party API integration. It works with Circle USDC and Ethereum. The repository describes itself as: Ethereum protocol engineering squad for AI coding assistants. The licence is MIT.

When your agent uses it

  • Building protocols that accept arbitrary tokens
  • Tasks that involve Third-party API integration

Example prompts

  • “/token-integration-safety”

What it can do on your machine

Read from SKILL.md and the folder at commit f8f3301. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are solidity).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Token Integration Safety loads about 2k tokens when it runs. Until then it costs about 71 tokens; SKILL.md has 326 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~71
When it runs · the whole SKILL.md, loaded when a task matches
~2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from ccashwell/evm-cortex at commit f8f3301, republished under its MIT licence (© ccashwell). 326 words, ~1,976 tokens.

Download SKILL.mdSave it as .claude/skills/token-integration-safety/SKILL.md (or your agent's skills folder).
name
token-integration-safety
description
Safe integration patterns for non-standard ERC-20 tokens. Use when building protocols that accept arbitrary tokens. Covers USDT (no return value), USDC (6 decimals, blacklist), fee-on-transfer, rebasing tokens, ERC-777 callbacks, pausable tokens, and Permit2.

Token Integration Safety

Always Use SafeERC20

This is the single most important rule. Never call transfer, transferFrom, or approve directly.

solidity
import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
import {SafeERC20} from "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";

contract Vault {
    using SafeERC20 for IERC20;

    function deposit(IERC20 token, uint256 amount) external {
        token.safeTransferFrom(msg.sender, address(this), amount);
    }

    function withdraw(IERC20 token, uint256 amount) external {
        token.safeTransfer(msg.sender, amount);
    }

    function approve(IERC20 token, address spender, uint256 amount) external {
        token.forceApprove(spender, amount);
    }
}

USDT — No Return Value

USDT's transfer() and transferFrom() don't return a bool. Direct calls via the IERC20 interface will revert because Solidity expects return data.

solidity
// BROKEN with USDT:
IERC20(usdt).transfer(to, amount); // reverts — no return data

// WORKS with USDT:
IERC20(usdt).safeTransfer(to, amount); // SafeERC20 handles missing return

USDT also requires approval to be set to 0 before changing to a non-zero value:

solidity
// BROKEN with USDT:
IERC20(usdt).approve(spender, newAmount); // reverts if current approval != 0

// WORKS with USDT:
IERC20(usdt).forceApprove(spender, newAmount); // sets to 0 first, then newAmount

USDC — 6 Decimals and Blacklist

solidity
// USDC uses 6 decimals, not 18
// 1 USDC = 1_000_000 (1e6), NOT 1e18

// VULNERABLE: hardcoded 18 decimals
uint256 usdcAmount = ethAmount * ethPrice / 1e18; // wrong!

// SAFE: use actual decimals
uint8 decimals = IERC20Metadata(address(usdc)).decimals(); // returns 6
uint256 usdcAmount = ethAmount * ethPrice / (10 ** (18 - decimals + 18));

USDC has a blacklist. Blacklisted addresses cannot send or receive USDC. Your protocol must handle transfer failures gracefully.

solidity
// If a blacklisted user has funds in your vault, they cannot withdraw
// Consider: allow withdrawal to a different address (with proper auth)
function withdrawTo(address token, address recipient, uint256 amount) external {
    if (balances[msg.sender] < amount) revert InsufficientBalance();
    balances[msg.sender] -= amount;
    IERC20(token).safeTransfer(recipient, amount);
}

Fee-on-Transfer Tokens

Some tokens deduct a fee on every transfer. The received amount is less than the sent amount.

solidity
// VULNERABLE: assumes received amount equals sent amount
function deposit(IERC20 token, uint256 amount) external {
    token.safeTransferFrom(msg.sender, address(this), amount);
    balances[msg.sender] += amount; // WRONG: received less than amount
}

// SAFE: measure actual received amount
function deposit(IERC20 token, uint256 amount) external {
    uint256 balanceBefore = token.balanceOf(address(this));
    token.safeTransferFrom(msg.sender, address(this), amount);
    uint256 received = token.balanceOf(address(this)) - balanceBefore;

    balances[msg.sender] += received;
    emit Deposited(msg.sender, address(token), received);
}

Decision: Many protocols explicitly reject fee-on-transfer tokens for simplicity. Document this clearly if so.

Rebasing Tokens (stETH, aTokens)

Rebasing tokens change balances automatically. balanceOf() returns different values over time without transfers.

solidity
// PROBLEM: stored balance becomes stale
mapping(address => uint256) public balances;

function deposit(uint256 amount) external {
    stETH.safeTransferFrom(msg.sender, address(this), amount);
    balances[msg.sender] += amount; // balance will change via rebasing
}

// SOLUTION 1: Use the wrapped, non-rebasing version
// stETH → wstETH (wrapped stETH, non-rebasing)
// aUSDC → use share-based accounting internally

// SOLUTION 2: Share-based accounting (ERC-4626 pattern)
function deposit(uint256 assets) external returns (uint256 shares) {
    shares = convertToShares(assets);
    _mint(msg.sender, shares);
    stETH.safeTransferFrom(msg.sender, address(this), assets);
}

ERC-777 Callbacks

ERC-777 tokens call tokensToSend() on the sender and tokensReceived() on the recipient. This creates reentrancy vectors.

solidity
// Risk: any transfer of an ERC-777 token triggers a callback
// If your contract receives an ERC-777 token, tokensReceived() is called
// An attacker can exploit this callback for reentrancy

// Defense: ReentrancyGuard on all functions that transfer tokens
function deposit(IERC20 token, uint256 amount) external nonReentrant {
    token.safeTransferFrom(msg.sender, address(this), amount);
    _updateBalance(msg.sender, amount);
}

Tokens with Blocklists

USDC, USDT, and others can freeze/blocklist addresses. Your protocol should handle this.

solidity
// Consider: what happens if a user gets blocklisted after depositing?
// - They can't receive tokens back
// - Their position may become unliquidatable
// - Protocol accounting may break

// Mitigation: allow withdrawal to alternative addresses
// Mitigation: allow admin rescue for stuck funds (with timelock)

Pausable Tokens

Some tokens (USDC, USDT) can be paused globally by their admin, blocking all transfers.

solidity
// If the underlying token is paused:
// - deposits fail
// - withdrawals fail
// - liquidations fail (potentially dangerous)

// Mitigation: emergency mode that accounts for paused underlying
// Mitigation: alternative settlement paths

Permit2 Integration

Permit2 provides a universal approval mechanism for all ERC-20 tokens (even those without EIP-2612).

solidity
import {IPermit2} from "permit2/interfaces/IPermit2.sol";

contract VaultWithPermit2 {
    IPermit2 public immutable PERMIT2;

    function depositWithPermit2(
        address token,
        uint256 amount,
        uint256 nonce,
        uint256 deadline,
        bytes calldata signature
    ) external {
        PERMIT2.permitTransferFrom(
            IPermit2.PermitTransferFrom({
                permitted: IPermit2.TokenPermissions({token: token, amount: amount}),
                nonce: nonce,
                deadline: deadline
            }),
            IPermit2.SignatureTransferDetails({
                to: address(this),
                requestedAmount: amount
            }),
            msg.sender,
            signature
        );

        _recordDeposit(msg.sender, token, amount);
    }
}

Token Quirks Reference

TokenDecimalsReturn BoolBlocklistPausableFee-on-TransferRebasing
USDT6NoYesYesNoNo
USDC6YesYesYesNoNo
DAI18YesNoNoNoNo
WETH18YesNoNoNoNo
WBTC8YesNoNoNoNo
stETH18YesNoNoNoYes
PAXG18YesYesYesYes (0.02%)No

Token Integration Checklist

  • SafeERC20 used for all token operations
  • forceApprove used instead of approve (USDT compatibility)
  • No assumption of 18 decimals — query decimals()
  • Fee-on-transfer handled (measure balance diff) or explicitly rejected
  • Rebasing tokens: use wrapped version or share-based accounting
  • ERC-777 callbacks: ReentrancyGuard on all token-handling functions
  • Blocklist handling: alternative withdrawal paths
  • Pausable token failure paths considered
  • Permit2 supported for gasless approvals
  • Token behavior documented in protocol docs

© ccashwell, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/token-integration-safety of ccashwell/evm-cortex.

Open the folder on GitHubat commit f8f3301

Compare with similar skills

Token Integration Safety next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Token Integration Safety compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Token Integration Safety this skillccashwell/evm-cortex131—~2kAutomated safety check: PassMIT
Deposit QrSuperior-Trade/superior-skills214—~1.1kAutomated safety check: PassMIT
Alchemy Agentic Gatewaymoonpay/skills113—~2.1kAutomated safety check: NotesMIT
NEAR Intents Swap Integrationinternet-court/internet-court-skill6.5k1 repos~939Automated safety check: PassCustom licence
Uniswap V3 Swapkeypo-us/keypo-cli182—~3.2kAutomated safety check: PassMIT
Payram Crypto PaymentsPayRam/payram-mcp158—~2kAutomated safety check: NotesNone

Similar skills

  • Deposit Qr

    Superior-Trade/superior-skills

    A skill your agent uses when a user needs a QR code or wallet payment URI to fund a Superior-managed EVM wallet on a specific chain before using Lighter, Polymarket, Hyperliquid, or other Superior…

    214 GitHub stars~1.1k tokensUpdated 29 days ago
    Backend & APIsAuto-check passed
  • A skill your agent uses when accessing Alchemy APIs for RPC calls, token balances, NFT metadata, asset transfers, transaction simulation, or Alchemy-specific features.

    113 GitHub stars~2.1k tokensUpdated 29 days ago
    Backend & APIsAuto-check: notes
  • NEAR Intents Swap Integration

    internet-court/internet-court-skill

    Builds cross-chain token swaps and bridge flows with the NEAR Intents 1Click API: quotes, deposit addresses, per-chain deposits and status polling.

    6.5k GitHub starsUsed in 1 repo~939 tokens
    Backend & APIsAuto-check passed
  • Uniswap V3 Swap

    keypo-us/keypo-cli

    A skill your agent uses when the user wants to swap tokens on Base Sepolia (or Base mainnet) using Uniswap V3.

    182 GitHub stars~3.2k tokensUpdated 6 mo ago
    Backend & APIsAuto-check passed
  • Payram Crypto Payments

    PayRam/payram-mcp

    Self-hosted crypto and stablecoin payment gateway. An agent skill from PayRam/payram-mcp.

    158 GitHub stars~2k tokensUpdated yesterday
    Backend & APIsAuto-check: notes
  • Helius for Solana

    internet-court/internet-court-skill

    Guides building Solana apps on Helius: sending transactions, asset and NFT queries, live streaming, webhooks, priority fees, wallet analysis and API key onboarding.

    6.5k GitHub starsUsed in 1 repo~2.7k tokens
    Backend & APIsAuto-check passed

More from ccashwell/evm-cortex

All 89 skills in this repo
  • Xray Pre Audit

    ccashwell/evm-cortex

    A skill your agent uses when preparing for a security audit, performing reconnaissance on a new codebase, or creating a protocol overview.

    131 GitHub stars~25k tokensUpdated 9 days ago
    Auto-check passed
  • Aave Integration

    ccashwell/evm-cortex

    A skill your agent uses when integrating with Aave V3 for lending, borrowing, flash loans, or building on top of Aave markets.

    131 GitHub stars~1.3k tokensUpdated 9 days ago
    Auto-check passed
  • Access Control Patterns

    ccashwell/evm-cortex

    Access control design patterns for Solidity protocols. An agent skill from ccashwell/evm-cortex.

    131 GitHub stars~1.8k tokensUpdated 9 days ago
    Auto-check passed
  • Anvil Patterns

    ccashwell/evm-cortex

    A skill your agent uses when running a local Ethereum node with Anvil.

    131 GitHub stars~1.3k tokensUpdated 9 days ago
    Auto-check passed
  • Audit Breadth Scan

    ccashwell/evm-cortex

    A skill your agent uses when performing systematic breadth-first review of all contracts during a security audit.

    131 GitHub stars~1.4k tokensUpdated 9 days ago
    Auto-check passed
  • Audit Depth Analysis

    ccashwell/evm-cortex

    A skill your agent uses when performing deep analysis of specific findings or high-risk areas during a security audit.

    131 GitHub stars~1.6k tokensUpdated 9 days ago
    Auto-check passed

Categories

Questions about Token Integration Safety

What does Token Integration Safety do?

Safe integration patterns for non-standard ERC-20 tokens. An agent skill from ccashwell/evm-cortex. Token Integration Safety is an agent skill from ccashwell/evm-cortex. Safe integration patterns for non-standard ERC-20 tokens.

When should I use Token Integration Safety?

Token Integration Safety fits situations like: building protocols that accept arbitrary tokens; tasks that involve Third-party API integration.

How do I install Token Integration Safety in Claude Code?

Run `npx skills add ccashwell/evm-cortex --skill token-integration-safety -a claude-code`. Or copy the skill folder (skills/token-integration-safety in ccashwell/evm-cortex) into .claude/skills/token-integration-safety in your project. Claude Code loads it when a task matches its description.

How do I install Token Integration Safety in Codex?

Run `npx skills add ccashwell/evm-cortex --skill token-integration-safety -a codex`. Or copy the skill folder (skills/token-integration-safety in ccashwell/evm-cortex) into .agents/skills/token-integration-safety in your project. Codex loads it when a task matches its description.

Can I use Token Integration Safety in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add ccashwell/evm-cortex --skill token-integration-safety -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/token-integration-safety, .gemini/skills/token-integration-safety, .github/skills/token-integration-safety and .opencode/skills/token-integration-safety in your project.

What does Token Integration Safety need to run?

SKILL.md names no scripts, command-line tools or credentials: Token Integration Safety is instructions for the agent only.

Does Token Integration Safety access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Token Integration Safety safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Token Integration Safety use?

Token Integration Safety is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Token Integration Safety use?

About 2k tokens (SKILL.md is roughly 7.9k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Token Integration Safety?

Skills that share tags, products or a category with Token Integration Safety: Deposit Qr (Superior-Trade/superior-skills, 214 stars), Alchemy Agentic Gateway (moonpay/skills, 113 stars), NEAR Intents Swap Integration (internet-court/internet-court-skill, 6.5k stars) and Uniswap V3 Swap (keypo-us/keypo-cli, 182 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Token Integration Safety?

ccashwell (a GitHub user) maintains it in ccashwell/evm-cortex, which has 131 GitHub stars. The repository holds 89 skills in this directory. The repository was last updated on September 30, 2026.

Source: ccashwell/evm-cortex on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.