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

> Learn to install and use the 0x ERC-20 token swap plugin for Claude. This skill facilitates seamless token swaps through the 0x API, simplifying your decentralized trading experience.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: how-to-guide
- Published: 2026-09-02

---

**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)](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)](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`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) `scripts` field (typically `scripts/` subdirectory) |

The plugin follows Claude's **Meta-Control Protocol (MCP)** pattern, where the skill definition in [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/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

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

```

### 2. Register the Plugin with Claude

```bash
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)](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

```bash
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`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json)) in the output.

## Usage Examples

### Basic Token Swap Intent

```python

# 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:

```python
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**:

```json
{
  "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

```python
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:

```bash

# 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)](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)](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)](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.