> For the complete documentation index, see [llms.txt](https://docs.shredpay.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shredpay.xyz/developers/agent-wallet/mcp-tools.md).

# MCP Tools

ShredPay Agent Wallet exposes 17 tools over the [Model Context Protocol](https://modelcontextprotocol.io/). Every tool maps 1:1 to a REST endpoint — pick whichever surface fits your client.

## Endpoint

```
https://agent-api.shredpay.xyz/mcp
```

Transport: **streamable-http**. Auth: `X-Api-Key` header on every request.

## Read tools (no `trade` permission required)

### `get_supported_chains`

List supported blockchain networks and whether each has the Router contract deployed.

| Param | Type | Required |
| ----- | ---- | -------- |
| —     |      |          |

### `get_wallet_address`

Get the agent's wallet addresses (one EVM address shared across all chains).

| Param | Type | Required |
| ----- | ---- | -------- |
| —     |      |          |

### `get_balance`

Query an ERC-20 token balance on a specific chain.

| Param      | Type   | Required | Description                     |
| ---------- | ------ | :------: | ------------------------------- |
| `chain_id` | number |    yes   | Chain ID (e.g. `8453` for Base) |
| `token`    | string |    yes   | Token contract address          |

### `get_native_balance`

Query the native token balance (ETH / BNB / POL).

| Param      | Type   | Required | Description |
| ---------- | ------ | :------: | ----------- |
| `chain_id` | number |    yes   | Chain ID    |

### `get_token_balances`

List all ERC-20 balances and the native balance on a chain (powered by Alchemy).

| Param      | Type   | Required | Description |
| ---------- | ------ | :------: | ----------- |
| `chain_id` | number |    yes   | Chain ID    |

### `get_limits`

Query daily and monthly spend limits and current usage.

| Param | Type | Required |
| ----- | ---- | -------- |
| —     |      |          |

### `get_transaction_status`

Look up the status of a previously submitted transaction.

| Param   | Type   | Required | Description                                   |
| ------- | ------ | :------: | --------------------------------------------- |
| `tx_id` | string |    yes   | Transaction ID returned by `send_transaction` |

### `gas_estimate`

Estimate current gas price and recommended ETH amount for a chain.

| Param      | Type   | Required | Description |
| ---------- | ------ | :------: | ----------- |
| `chain_id` | number |    yes   | Chain ID    |

### `get_defi_markets`

Get the catalog of available DeFi vaults.

| Param | Type | Required |
| ----- | ---- | -------- |
| —     |      |          |

### `get_positions`

Get the wallet's open DeFi positions (shares, USD value, market info, APY).

| Param | Type | Required |
| ----- | ---- | -------- |
| —     |      |          |

### `get_swap_quote`

Get a swap quote via the Li.Fi aggregator. Useful for previewing a price before calling `execute_swap`.

| Param        | Type   | Required | Description               |
| ------------ | ------ | :------: | ------------------------- |
| `chain_id`   | number |    yes   | Chain ID                  |
| `from_token` | string |    yes   | Source token address      |
| `to_token`   | string |    yes   | Destination token address |
| `amount`     | string |    yes   | Amount in smallest unit   |

## Trade tools (require `trade` permission)

### `send_transaction`

Sign and broadcast an arbitrary on-chain transaction. **Agent pays gas** — sub-wallet must hold native token.

| Param       | Type   | Required | Description                                    |
| ----------- | ------ | :------: | ---------------------------------------------- |
| `chain_id`  | number |    yes   | Target chain ID                                |
| `to`        | string |    yes   | Destination address                            |
| `data`      | string |    yes   | Transaction calldata (hex)                     |
| `value`     | string |    no    | Value in wei (hex or decimal). Defaults to `0` |
| `gas_limit` | string |    no    | Override gas limit                             |

### `simulate_transaction`

Simulate a transaction without broadcasting. Runs validation and address screening — useful for pre-flighting an expensive call.

| Param      | Type   | Required | Description                |
| ---------- | ------ | :------: | -------------------------- |
| `chain_id` | number |    yes   | Target chain ID            |
| `to`       | string |    yes   | Destination address        |
| `data`     | string |    yes   | Transaction calldata (hex) |
| `value`    | string |    no    | Value in wei               |

### `gas_swap`

Swap USDC to ETH for gas. **Sponsored** by ShredPay (you don't need ETH to obtain ETH). Base only today.

| Param         | Type   | Required | Description                               |
| ------------- | ------ | :------: | ----------------------------------------- |
| `amount_usdc` | string |    yes   | USDC amount in smallest unit (6 decimals) |
| `chain_id`    | number |    yes   | Chain ID (currently must be `8453`)       |

### `execute_swap`

Execute a token swap via the Router contract. **Sponsored** — ShredPay pays gas, collects a small fee.

| Param        | Type   | Required | Description                             |
| ------------ | ------ | :------: | --------------------------------------- |
| `chain_id`   | number |    yes   | Chain ID (must have `has_router: true`) |
| `from_token` | string |    yes   | Source token address                    |
| `to_token`   | string |    yes   | Destination token address               |
| `amount`     | string |    yes   | Amount in smallest unit                 |
| `slippage`   | string |    no    | Slippage tolerance (default `0.5%`)     |

### `defi_deposit`

Deposit into a curated DeFi vault via Router. **Sponsored**.

| Param       | Type   | Required | Description                                      |
| ----------- | ------ | :------: | ------------------------------------------------ |
| `chain_id`  | number |    yes   | Chain ID                                         |
| `market_id` | string |    yes   | Market ID from `get_defi_markets`                |
| `amount`    | string |    yes   | Amount in smallest unit (e.g. USDC = 6 decimals) |

### `defi_withdraw`

Withdraw from a DeFi vault via Router. **Sponsored**.

| Param       | Type   | Required | Description                                  |
| ----------- | ------ | :------: | -------------------------------------------- |
| `chain_id`  | number |    yes   | Chain ID                                     |
| `market_id` | string |    yes   | Market ID from `get_defi_markets`            |
| `shares`    | string |    yes   | Shares to redeem (read from `get_positions`) |

## Permission summary

| Permission | Tools                                                                                                                                                                                                                  |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `read`     | `get_supported_chains`, `get_wallet_address`, `get_balance`, `get_native_balance`, `get_token_balances`, `get_limits`, `get_transaction_status`, `gas_estimate`, `get_defi_markets`, `get_positions`, `get_swap_quote` |
| `trade`    | All `read` tools **plus** `send_transaction`, `simulate_transaction`, `gas_swap`, `execute_swap`, `defi_deposit`, `defi_withdraw`                                                                                      |

## Source of truth

The Skill manifest used by OpenClaw and other agent platforms lives at [`ShredPay/openclaw-skill`](https://github.com/ShredPay/openclaw-skill) — `shredpay-wallet.skill.yaml`. If that file disagrees with this page, the YAML wins.