How to Install and Use the 0x ERC-20 Token Swap Plugin in Claude

The 0x ERC-20 token swap plugin is a Claude skill that enables pricing, approval, and execution of token swaps via the 0x API by orchestrating price quotes, allowance checks, and EIP-712 signed transactions.

The 0x ERC-20 token swap plugin (also referred to as the "Ox" plugin in community shorthand) is part of the anthropics/claude-plugins-community repository. This skill integrates Claude with the 0x Protocol's decentralized exchange aggregator, allowing users to swap ERC-20 tokens across EVM chains through natural language commands.

Plugin Architecture and Key Files

Understanding the source structure helps you configure and extend the plugin correctly. The implementation spans three primary configuration layers:

Component	Purpose	Source Path
Marketplace manifest	Describes the plugin's capabilities, 0x API integration flow, and metadata for discovery	[/.claude-plugin/marketplace.json](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json)
Plugin registration	Defines the skill name, entry points, and Claude MCP integration schema	[/.claude-plugin/plugin.json](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json)
Runtime scripts	Python modules that query the 0x API, build transactions, and handle cryptographic signing	Referenced in plugin.json scripts field (typically scripts/ subdirectory)

The plugin follows Claude's Meta-Control Protocol (MCP) pattern, where the skill definition in plugin.json maps user intents to a sequence of tool calls executed by Claude's runtime.

How the 0x Swap Flow Works

The 0x ERC-20 token swap plugin executes swaps through a five-step pipeline:

1. Price discovery – Queries https://api.0x.org/swap/v1/quote for the optimal route and expected output
2. Allowance verification – Checks token approval status for the 0x router contract (0x11111112542d85b3ef69ae05771c2dccff4faa26 on Ethereum mainnet)
3. Approval handling – Either submits a standard approve transaction or generates a gas-less Permit2 EIP-712 signature
4. Transaction signing – Presents the swap transaction as typed data for wallet signature
5. Broadcast – Submits the signed transaction to the target EVM chain's RPC endpoint

All steps are coordinated through the skill's run function, which maintains state across Claude's MCP server calls.

Installation Steps

1. Clone the Community Repository

git clone https://github.com/anthropics/claude-plugins-community.git
cd claude-plugins-community

2. Register the Plugin with Claude

claude plugin register .claude-plugin/plugin.json

This command reads the skill definition in [/.claude-plugin/plugin.json](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) and makes the 0x ERC-20 token swap plugin available in your Claude instance.

3. Verify Installation

claude plugin list | grep ox-erc20-swap

You should see ox-erc20-swap (or the exact skill name defined in the name field of plugin.json) in the output.

Usage Examples

Basic Token Swap Intent

# Request: swap 10 USDC for USDT on Ethereum mainnet

swap_request = {
    "action": "swap",
    "fromToken": "USDC",
    "toToken": "USDT",
    "amount": "10",
    "chain": "ethereum"
}

# Invoke through Claude's skill interface

result = claude.invoke_skill("ox-erc20-swap", swap_request)
print(result["message"])  # Displays quote, price impact, and confirmation prompt

Claude automatically handles the full flow:

• Calls the 0x API quote endpoint with parameters: sellToken, buyToken, sellAmount, and chainId
• Parses the response fields: price, guaranteedPrice, to (router address), data (calldata), and gas
• Validates user balance and existing allowances via RPC calls

Gas-Less Approval with Permit2

For tokens supporting Uniswap's Permit2 standard, the plugin avoids approval transactions:

permit_request = {
    "action": "permit2",
    "token": "USDC",
    "spender": "0x11111112542d85b3ef69ae05771c2dccff4faa26",
    "value": "1000000000000000000",  # 1 USDC in wei (6 decimals)

    "deadline": "9999999999"  # Unix timestamp for signature expiration

}

claude.invoke_skill("ox-erc20-swap", permit_request)

The skill generates the EIP-712 typed data:

{
  "types": {
    "PermitTransferFrom": [
      {"name": "permitted", "type": "TokenPermissions"},
      {"name": "spender", "type": "address"},
      {"name": "nonce", "type": "uint256"},
      {"name": "deadline", "type": "uint256"}
    ],
    "TokenPermissions": [
      {"name": "token", "type": "address"},
      {"name": "amount", "type": "uint256"}
    ]
  },
  "primaryType": "PermitTransferFrom",
  "domain": {
    "name": "Permit2",
    "chainId": 1,
    "verifyingContract": "0x000000000022d473030f116ddee9f6b43ac78ba3"
  },
  "message": { "...": "..." }
}

Your wallet signs this structure without broadcasting a transaction—saving gas and time.

Submitting Signed Transactions

final_submission = {
    "action": "submit",
    "tx": {
        "raw": "0x02f8a1a0..."  # Signed transaction hex from wallet

    }
}

receipt = claude.invoke_skill("ox-erc20-swap", final_submission)
print(f"Transaction hash: {receipt['txHash']}")

Configuration and Environment Variables

Based on standard patterns in claude-plugins-community, create a .env file in your working directory:

# Required: 0x API key for higher rate limits

ZEROEX_API_KEY=your_api_key_here

# Required: RPC endpoints for target chains

ETHEREUM_RPC=https://eth-mainnet.g.alchemy.com/v2/your_key
POLYGON_RPC=https://polygon-mainnet.g.alchemy.com/v2/your_key
ARBITRUM_RPC=https://arb-mainnet.g.alchemy.com/v2/your_key

# Optional: Private key for automated testing (not recommended for production)

# TEST_PRIVATE_KEY=0x...

The skill loader in [/.claude-plugin/plugin.json](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) references these environment variables to initialize the runtime scripts.

Troubleshooting Common Issues

Symptom	Cause	Solution
"No quote found"	Insufficient liquidity or unsupported token pair	Verify token addresses are checksummed and listed on 0x
"Allowance required" loop	Permit2 not supported by token	Fall back to standard approve flow
"Chain not supported"	Missing RPC configuration	Add the target chain's RPC URL to environment
Signature rejected	Wrong chain ID in typed data	Confirm wallet network matches chain parameter

Summary

• The 0x ERC-20 token swap plugin is registered in [/.claude-plugin/plugin.json](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) and described in [/.claude-plugin/marketplace.json](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json)
• Install via claude plugin register .claude-plugin/plugin.json after cloning the repository
• The skill orchestrates price quotes, allowance management (standard or Permit2), EIP-712 signing, and transaction broadcast
• Supports 20+ EVM chains through the 0x Protocol aggregator
• Configure ZEROEX_API_KEY and chain-specific RPC endpoints for optimal performance

Frequently Asked Questions

What chains does the 0x ERC-20 token swap plugin support?

The plugin supports all EVM chains where 0x Protocol operates, including Ethereum, Polygon, Arbitrum, Optimism, Base, and Avalanche. Chain selection is controlled by the chain parameter in swap requests, which maps to chain IDs in the skill's internal configuration. Ensure your environment includes the corresponding RPC endpoint.

Do I need a 0x API key to use this plugin?

Strictly speaking, no—the 0x API offers public endpoints with rate limits. However, production usage requires a ZEROEX_API_KEY for higher throughput and access to advanced features like RFQ liquidity. The plugin reads this key from environment variables and passes it as the 0x-api-key header in all quote requests.

How does the plugin handle transaction security?

The plugin never holds private keys. It constructs transactions and presents them as EIP-712 typed data or raw transaction objects for your wallet to sign. Claude's MCP architecture ensures the skill cannot execute state-changing operations without explicit user confirmation at each step—quote review, approval signing, and final swap submission.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}