# erc20-mcp: Token Operations

The `erc20-mcp` server allows agents to **interact with ERC-20 tokens** across supported chains in a safe, modular, and non-custodial way.

This module enables LLM agents to:

* Check balances
* Transfer tokens
* Approve spending
* Prepare ERC-20 payloads for wallet signing

It operates as a **read/write utility layer** for token interactions, without ever signing or broadcasting on its own.

***

### What It Does

* Fetches token metadata and balances
* Prepares unsigned `transfer`, `approve`, or `permit` transactions
* Returns payloads ready for tools like `metamask-mcp` to sign
* Works across chains, using resolved RPCs via `chainlist-mcp`

***

### Tool 1: `erc20.balanceOf`

#### Request

```json
{
  "tool": "erc20.balanceOf",
  "args": {
    "wallet": "0x123...",
    "token": "USDC",
    "chain": "arbitrum"
  }
}
```

#### Response

```json
{
  "token": "USDC",
  "balance": "100.5",
  "decimals": 6,
  "chain": "arbitrum"
}
```

* `token`: Ticker or address (resolved internally)
* `wallet`: Wallet address to check
* `chain`: Optional — defaults to mainnet

***

### Tool 2: `erc20.transfer`

#### Request

```json
{
  "tool": "erc20.transfer",
  "args": {
    "to": "0xabc...",
    "amount": "50",
    "token": "USDC",
    "from": "0x123...",
    "chain": "optimism"
  }
}
```

#### Response

```json
{
  "unsignedTx": {
    "to": "0xA0b86991c...",
    "data": "0xa9059cbb00000000...",
    "value": "0x0",
    "gas": 60000
  },
  "chainId": 10,
  "explorer": "https://optimistic.etherscan.io"
}
```

This unsigned transaction can now be passed to `metamask-mcp` for signing.

***

### Tool 3: `erc20.approve`

#### Request

```json
{
  "tool": "erc20.approve",
  "args": {
    "spender": "0xrouter...",
    "amount": "100",
    "token": "USDC",
    "chain": "ethereum"
  }
}
```

#### Response

```json
{
  "unsignedTx": {
    "to": "0xA0b86991c...",
    "data": "0x095ea7b300000000...",
    "gas": 48000
  },
  "chainId": 1
}
```

***

### Server Setup

To run `erc20-mcp` locally:

```bash
git clone https://github.com/pilso-os/mcp-servers
cd mcp-servers/erc20-mcp
npm install
npm start
```

Default endpoint: `http://localhost:3040`

Update `pilso.config.json`:

```json
"tools": [
  "http://localhost:3040"
]
```

***

### Token Resolution Logic

`erc20-mcp` supports both:

* **Common token names** (e.g. `USDC`, `WETH`)
* **Full contract addresses**

If you provide a symbol, it auto-resolves via:

* Chain-specific token maps
* Internal token registry
* Chain ID via `chainlist-mcp`

To override or customize token maps, you can extend the internal JSONs in `/tokens/`.

***

### Test Call Locally

```bash
npx pilso call \
  --tool erc20.balanceOf \
  --args '{"wallet": "0x123...", "token": "USDC", "chain": "polygon"}'
```

***

### Security Best Practices

* Do not expose `erc20.transfer` to general-purpose roles
* Use role-level guardrails like `"Never transfer without confirmation"`
* Always preview the `unsignedTx` in the logs before signing
* Only allow trusted tokens or whitelisted contracts in production agents

***

### Future Additions

* Support for EIP-2612 `permit()` meta-transactions
* Multi-transfer batch support
* AI-assisted gas estimation per chain/token

***

### ✅ Summary

| Property            | Value                                                |
| ------------------- | ---------------------------------------------------- |
| **Tool names**      | `erc20.balanceOf`, `erc20.transfer`, `erc20.approve` |
| **Port**            | `3040` (default)                                     |
| **Signature**       | Only prepares payloads — does not sign or broadcast  |
| **Chain support**   | EVM-based chains only                                |
| **Integrates with** | `chainlist-mcp`, `metamask-mcp`                      |

`erc20-mcp` is the token layer of PILSO OS — enabling any role-scoped agent to interact with ERC-20 contracts in a safe, modular way.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pil.so/mcp-server-models/erc20-mcp-token-operations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.