> For the complete documentation index, see [llms.txt](https://gotts.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gotts.gitbook.io/docs/gotts-safe-mcp-server/mcp-server/08-tools-infra.md).

# Safety, Testnet, Utility

> **Package**: `packages/safe/` | **Prerequisites**: [02-architecture.md](/docs/gotts-safe-mcp-server/mcp-server/02-architecture.md)
>
> Safety tools, local testnet tools, and utility tools. For other tool categories, see the [README](/docs/gotts-safe-mcp-server/mcp-server.md).

***

## Safety Tools

#### `simulate_transaction`

Simulate any transaction via `eth_call` before broadcasting. Returns decoded results or revert reason.

**Parameters**:

| Name       | Type     | Required | Description                                       |
| ---------- | -------- | -------- | ------------------------------------------------- |
| `to`       | `string` | Yes      | Target contract address                           |
| `data`     | `string` | Yes      | Encoded calldata (hex)                            |
| `value`    | `string` | No       | ETH value to send (in wei). Default: "0".         |
| `chain`    | `string` | Yes      | Chain name or chain ID                            |
| `from`     | `string` | No       | Sender address. Default: configured agent wallet. |
| `blockTag` | `string` | No       | Block to simulate against. Default: "latest".     |

**Returns**:

```json
{
  "success": true,
  "result": "0x...",
  "decodedResult": {
    "amountOut": "154012000000000000",
    "amountOutHuman": "0.154012 WETH"
  },
  "gasEstimate": "150000",
  "gasEstimateUsd": "0.45",
  "stateChanges": [
    { "address": "0xA0b8...", "label": "USDC", "balanceChange": "-500.000000" },
    { "address": "0xC02a...", "label": "WETH", "balanceChange": "+0.154012" }
  ]
}
```

**On failure**:

```json
{
  "success": false,
  "revertReason": "STF",
  "decodedRevertReason": "SafeTransferFrom: transfer failed. Likely insufficient balance or allowance.",
  "gasEstimate": null
}
```

***

#### `validate_token`

Validate a token address: check if it is a legitimate ERC-20, whether it is on the allowlist, and basic scam detection.

**Parameters**:

| Name    | Type     | Required | Description                              |
| ------- | -------- | -------- | ---------------------------------------- |
| `token` | `string` | Yes      | Token address (full address, not symbol) |
| `chain` | `string` | Yes      | Chain name or chain ID                   |

**Returns**:

```json
{
  "address": "0x6982508145454Ce325dDbE47a25d4ec3d2311933",
  "chain": "ethereum",
  "isValidErc20": true,
  "name": "Pepe",
  "symbol": "PEPE",
  "decimals": 18,
  "totalSupply": "420690000000000000000000000000000",
  "onDefaultTokenList": true,
  "onAllowlist": false,
  "warnings": [
    "Token is NOT on the configured allowlist. Trading this token requires explicit allowlist override."
  ],
  "checks": {
    "hasTransferFunction": true,
    "hasApproveFunction": true,
    "hasBalanceOfFunction": true,
    "isProxy": false,
    "ownerCanMint": false,
    "ownerCanPause": false,
    "hasTransferFee": false
  }
}
```

***

#### `check_safety_status`

Return the current state of all safety systems: remaining spending limits, rate limit counters, circuit breaker status.

**Parameters**:

| Name    | Type     | Required | Description                                      |
| ------- | -------- | -------- | ------------------------------------------------ |
| `chain` | `string` | No       | Check for a specific chain. Default: all chains. |

**Returns**:

```json
{
  "timestamp": "2026-02-06T12:00:00Z",
  "wallet": "0x1234...",
  "spendingLimits": {
    "perTransaction": { "limit": 10000, "currency": "USD" },
    "daily": {
      "limit": 100000,
      "used": 2500,
      "remaining": 7500,
      "resetsAt": "2026-02-07T00:00:00Z"
    }
  },
  "rateLimit": {
    "maxOperationsPerWindow": 20,
    "windowSeconds": 3600,
    "operationsUsed": 5,
    "operationsRemaining": 15,
    "windowResetsAt": "2026-02-06T12:45:00Z"
  },
  "balanceCircuitBreaker": {
    "enabled": true,
    "thresholdEth": 0.01,
    "currentBalanceEth": 0.5,
    "status": "ok"
  },
  "allowlist": {
    "enabled": true,
    "tokenCount": 42,
    "source": "uniswap-default-token-list"
  },
  "noncesTracked": {
    "ethereum": { "pending": 0, "lastConfirmed": 145 },
    "base": { "pending": 1, "lastConfirmed": 89 }
  }
}
```

***

#### `audit_approvals`

Scan all ERC-20 token approvals granted by a wallet and identify stale, unlimited, or risky approvals. Optionally revoke specific approvals. Critical hygiene tool — unused approvals are an attack surface if the approved contract is compromised.

**Parameters**:

| Name        | Type      | Required | Description                                          |
| ----------- | --------- | -------- | ---------------------------------------------------- |
| `wallet`    | `string`  | No       | Wallet address. Default: configured agent wallet.    |
| `chain`     | `string`  | Yes      | Chain name or chain ID                               |
| `revokeAll` | `boolean` | No       | Revoke all non-essential approvals. Default: false.  |
| `revoke`    | `array`   | No       | Specific approvals to revoke: `[{ token, spender }]` |

**Returns**:

```json
{
  "wallet": "0x1234...",
  "chain": "base",
  "approvalCount": 12,
  "riskSummary": {
    "unlimited": 8,
    "stale": 3,
    "activelyUsed": 4,
    "riskScore": "MEDIUM"
  },
  "approvals": [
    {
      "token": { "symbol": "USDC", "address": "0xA0b8..." },
      "spender": {
        "address": "0x000000000022D473030F116dDEE9F6B43aC78BA3",
        "label": "Permit2"
      },
      "allowance": "unlimited",
      "lastUsed": "2026-02-18T10:00:00Z",
      "risk": "LOW",
      "recommendation": "Keep — actively used by Uniswap"
    },
    {
      "token": { "symbol": "USDC", "address": "0xA0b8..." },
      "spender": { "address": "0xDEAD...", "label": "Unknown contract" },
      "allowance": "unlimited",
      "lastUsed": "2025-08-15T00:00:00Z",
      "risk": "HIGH",
      "recommendation": "Revoke — unlimited approval to unverified contract, unused for 6 months"
    }
  ],
  "revoked": []
}
```

When `revokeAll` or `revoke` is set, the tool submits approval transactions setting allowance to 0 and includes the results in the `revoked` array. Revocations pass through the full safety pipeline.

**Data Source**: RPC `eth_getLogs` scanning for `Approval(address,address,uint256)` events from the wallet address, then reading current allowance via `allowance()` calls.

**Error Cases**:

* `WALLET_NOT_FOUND`: Invalid address
* `CHAIN_NOT_SUPPORTED`: Chain not supported
* `REVOKE_FAILED`: One or more revocation transactions failed

***

#### `batch_revoke_approvals`

Scan and batch-revoke ERC-20 token approvals across multiple chains in a single coordinated operation. Extends `audit_approvals` (single chain, individual revocations) with multi-chain support, mode-based filtering, Permit2 `lockdown()`, and one multicall transaction per chain. The "security sweep" power tool for approval hygiene.

**Parameters**:

| Name             | Type      | Required | Description                                                                                                                                            |
| ---------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `wallet`         | `string`  | No       | Wallet address. Default: configured agent wallet.                                                                                                      |
| `chains`         | `array`   | Yes      | Array of chain names or chain IDs to scan (e.g., `["ethereum", "base", "arbitrum"]`)                                                                   |
| `mode`           | `string`  | No       | `"risky"` (unlimited + stale only), `"all"` (revoke everything except `keep`), `"selective"` (only revoke items in `revoke` list). Default: `"risky"`. |
| `keep`           | `array`   | No       | Spender addresses to preserve (never revoke). Default: `["0x000000000022D473030F116dDEE9F6B43aC78BA3"]` (Permit2).                                     |
| `revoke`         | `array`   | No       | Specific approvals to revoke: `[{ token, spender, chain }]`. Required when mode is `"selective"`.                                                      |
| `includePermit2` | `boolean` | No       | Also revoke Permit2 sub-allowances via `lockdown()`. Default: true.                                                                                    |
| `staleDays`      | `number`  | No       | Approvals unused for this many days are considered stale (used in `"risky"` mode). Default: 90.                                                        |
| `dryRun`         | `boolean` | No       | Preview planned revocations without executing. Returns scan results and gas estimates. Default: false.                                                 |

**Returns**:

```json
{
  "status": "success",
  "wallet": "0x1234...",
  "chainsScanned": 3,
  "scan": {
    "totalApprovals": 34,
    "unlimited": 18,
    "stale": 12,
    "riskScore": "HIGH"
  },
  "revoked": [
    {
      "chain": "ethereum",
      "txHash": "0xREVOKE1...",
      "approvalsRevoked": 5,
      "details": [
        {
          "token": { "symbol": "USDC", "address": "0xA0b8..." },
          "spender": { "address": "0xDEAD...", "label": "Unknown contract" },
          "previousAllowance": "unlimited",
          "risk": "HIGH",
          "reason": "Unlimited approval to unverified contract, unused for 180 days"
        }
      ]
    },
    {
      "chain": "base",
      "txHash": "0xREVOKE2...",
      "approvalsRevoked": 3,
      "details": []
    }
  ],
  "permit2Lockdown": [
    {
      "chain": "ethereum",
      "txHash": "0xLOCKDOWN1...",
      "subAllowancesRevoked": 4
    }
  ],
  "kept": [
    {
      "token": "USDC",
      "spender": "Permit2",
      "chain": "ethereum",
      "reason": "In keep list"
    }
  ],
  "summary": {
    "totalRevoked": 12,
    "totalPermit2Revoked": 4,
    "totalKept": 3,
    "chainsAffected": 2,
    "totalGasCostUsd": 4.82
  }
}
```

**Implementation**: Scans ERC-20 `Approval(address,address,uint256)` events via `eth_getLogs` on each chain, reads current allowances, and reads Permit2 sub-allowances. In `"risky"` mode, filters to unlimited and stale (>`staleDays` since last use) approvals. Batch revokes via multicall: one `approve(spender, 0)` per approval, plus `Permit2.lockdown()` for sub-allowances. One transaction per chain. Reuses the approval scanner service extracted from `audit_approvals`.

**Risk Tier**: Standard (10 min Agent Proxy delay) — revocations reduce risk exposure.

**Error Cases**:

* `WALLET_NOT_FOUND`: Invalid address
* `CHAIN_NOT_SUPPORTED`: One or more chains not supported
* `BATCH_REVOKE_PARTIAL`: Some chains failed (partial results returned with per-chain status)
* `NO_APPROVALS_TO_REVOKE`: All approvals are in keep list or already zero

***

#### `detect_honeypot`

Detect honeypot tokens via simulation-based buy→sell verification. Simulates a small buy then an immediate sell via `eth_call` fork simulation. If the sell reverts or incurs an excessive tax, the token is flagged as a honeypot. More reliable than static analysis because it catches runtime-only traps.

**Parameters**:

| Name    | Type     | Required | Description                                              |
| ------- | -------- | -------- | -------------------------------------------------------- |
| `token` | `string` | Yes      | Token address to test                                    |
| `chain` | `string` | Yes      | Chain name or chain ID                                   |
| `pool`  | `string` | No       | Specific pool to test against. Auto-detected if omitted. |

**Returns**:

```json
{
  "token": "0x1234...",
  "chain": "base",
  "isHoneypot": false,
  "result": {
    "buySucceeded": true,
    "sellSucceeded": true,
    "buyTaxPct": 0,
    "sellTaxPct": 2.5,
    "transferTaxPct": 0,
    "maxTxAmount": null,
    "ownerCanPause": false,
    "ownerCanBlacklist": true,
    "ownerCanMint": false
  },
  "risk": {
    "rating": "CAUTION",
    "flags": ["Sell tax of 2.5% detected", "Owner has blacklist capability"]
  },
  "testedPool": "0xABCD...",
  "simulationBlock": 12345678,
  "timestamp": "2026-02-19T12:00:00Z"
}
```

**Implementation**: Uses `eth_call` with state overrides to simulate a buy (ETH→Token swap) then a sell (Token→ETH swap) against the highest-liquidity pool. Compares expected output vs actual simulated output to detect hidden taxes. Also reads contract storage slots for common honeypot patterns (owner pause, blacklist, max transaction limits).

**Risk Ratings**: `SAFE` (no flags), `CAUTION` (minor flags like small tax), `DANGER` (sell fails, high tax, or blacklist active), `HONEYPOT` (sell reverts completely).

**Error Cases**:

* `NO_POOL`: No pool exists for this token
* `TOKEN_NOT_FOUND`: Address is not an ERC-20 contract
* `SIMULATION_ERROR`: Fork simulation failed

***

## Session Key Tools

Tools for managing ERC-7715 scoped session keys. Session keys enable agents to operate with time-limited, permission-scoped credentials instead of full wallet access.

***

#### `provision_session_key`

Create a new ERC-7715 session key with scoped permissions. Session keys limit what an agent can do (specific contracts, methods, amounts, chains) and automatically expire.

**Parameters**:

| Name          | Type     | Required | Description                                                               |
| ------------- | -------- | -------- | ------------------------------------------------------------------------- |
| `permissions` | `array`  | Yes      | Array of permission objects: `[{ contract, methods, maxAmount, chains }]` |
| `expiry`      | `number` | Yes      | Expiry in seconds from now (e.g., 3600 for 1 hour, 86400 for 1 day)       |
| `label`       | `string` | No       | Human-readable label for this session key. Default: auto-generated.       |

**Returns**:

```json
{
  "sessionKeyId": "sk_abc123",
  "publicKey": "0x...",
  "permissions": [
    {
      "contract": "0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD",
      "contractLabel": "Universal Router",
      "methods": ["execute"],
      "maxAmountPerTx": "10000 USDC",
      "chains": ["base"]
    }
  ],
  "expiresAt": "2026-02-20T12:00:00Z",
  "label": "trading-session-v1",
  "status": "active"
}
```

**Error Cases**:

* `WALLET_NOT_SMART_ACCOUNT`: Session keys require a smart account (ERC-4337)
* `INVALID_PERMISSIONS`: Malformed permission array
* `EXPIRY_TOO_LONG`: Maximum session key expiry is 30 days

***

#### `revoke_session_keys`

Revoke one or more active session keys immediately. Revoked keys can no longer sign transactions.

**Parameters**:

| Name     | Type     | Required | Description                                                       |
| -------- | -------- | -------- | ----------------------------------------------------------------- |
| `keyIds` | `array`  | No       | Array of session key IDs to revoke. If omitted, revokes ALL keys. |
| `reason` | `string` | No       | Reason for revocation (logged for audit trail).                   |

**Returns**:

```json
{
  "revoked": ["sk_abc123", "sk_def456"],
  "revokedCount": 2,
  "remainingActive": 1,
  "timestamp": "2026-02-19T12:00:00Z"
}
```

***

#### `get_session_keys`

List all active session keys with their permissions, expiry, and usage stats.

**Parameters**: None (uses configured wallet).

**Returns**:

```json
{
  "wallet": "0x1234...",
  "activeKeys": [
    {
      "sessionKeyId": "sk_abc123",
      "label": "trading-session-v1",
      "permissions": [
        {
          "contract": "Universal Router",
          "methods": ["execute"],
          "chains": ["base"]
        }
      ],
      "expiresAt": "2026-02-20T12:00:00Z",
      "usageStats": {
        "transactionsExecuted": 12,
        "totalValueUsd": 4500,
        "lastUsed": "2026-02-19T11:30:00Z"
      },
      "status": "active"
    }
  ],
  "totalActive": 1,
  "totalExpired": 3,
  "totalRevoked": 2
}
```

***

## Wallet Management Tools

Tools for configuring wallet policies, funding wallets, and checking wallet health. These complement `provision_wallet` for ongoing wallet lifecycle management.

***

#### `configure_wallet_policy`

Update the signing policy for the configured wallet. Policies are enforced by the wallet provider (Privy) and cannot be bypassed by the agent.

**Parameters**:

| Name             | Type     | Required | Description                                                                       |
| ---------------- | -------- | -------- | --------------------------------------------------------------------------------- |
| `policyTemplate` | `string` | No       | Apply a preset: "vault-participant", "vault-manager", "defi-trading", "read-only" |
| `customPolicy`   | `object` | No       | Custom policy object with allowedContracts, spendingLimits, chainRestrictions     |

**Returns**:

```json
{
  "status": "updated",
  "wallet": "0x1234...",
  "provider": "privy",
  "policy": {
    "allowedContracts": 4,
    "transferLimitPerTx": "1000 USDC",
    "transferLimitPerDay": "5000 USDC",
    "chainRestrictions": ["base"],
    "allowedMethods": ["execute", "swap", "addLiquidity"]
  },
  "previousPolicy": "defi-trading",
  "timestamp": "2026-02-19T12:00:00Z"
}
```

**Error Cases**:

* `PROVIDER_NOT_CONFIGURED`: Wallet provider credentials not set
* `INVALID_POLICY`: Malformed policy object
* `POLICY_DOWNGRADE_BLOCKED`: Cannot weaken policy without admin approval

***

#### `fund_wallet`

Fund the agent wallet with tokens from an external source. Primarily used in testnet/development for seeding wallets with test tokens.

**Parameters**:

| Name     | Type     | Required | Description                                                                  |
| -------- | -------- | -------- | ---------------------------------------------------------------------------- |
| `tokens` | `array`  | Yes      | Array of `{ symbol: string, amount: string }` to fund                        |
| `chain`  | `string` | Yes      | Chain name or chain ID                                                       |
| `source` | `string` | No       | Funding source: "faucet" (testnet), "bridge", "transfer". Default: "faucet". |

**Returns**:

```json
{
  "funded": [
    { "symbol": "ETH", "amount": "1.0", "txHash": "0x...", "source": "faucet" },
    {
      "symbol": "USDC",
      "amount": "10000",
      "txHash": "0x...",
      "source": "faucet"
    }
  ],
  "wallet": "0x1234...",
  "chain": "base-sepolia"
}
```

**Error Cases**:

* `FAUCET_UNAVAILABLE`: Faucet not available for this chain
* `CHAIN_NOT_TESTNET`: `fund_wallet` with source "faucet" only works on testnets
* `RATE_LIMITED`: Faucet rate limit exceeded

***

#### `migrate_wallet`

Move all assets (ERC-20 tokens, LP NFTs, native ETH) from one wallet to another in a single coordinated operation. Execution order: ERC-20 transfers → NFT `safeTransferFrom` → native ETH transfer (last, to preserve gas for prior transfers). The "move everything" power tool for wallet rotation, key compromise response, or account consolidation.

**Parameters**:

| Name                | Type      | Required | Description                                                                      |
| ------------------- | --------- | -------- | -------------------------------------------------------------------------------- |
| `sourceWallet`      | `string`  | No       | Source wallet address. Default: configured agent wallet.                         |
| `destinationWallet` | `string`  | Yes      | Destination wallet address                                                       |
| `chain`             | `string`  | Yes      | Chain name or chain ID                                                           |
| `gasReserveEth`     | `string`  | No       | ETH to reserve in source for gas during migration. Default: "0.01".              |
| `includeNfts`       | `boolean` | No       | Include LP position NFTs (V3 NonfungiblePositionManager tokens). Default: true.  |
| `includeTokens`     | `boolean` | No       | Include ERC-20 token balances. Default: true.                                    |
| `tokens`            | `array`   | No       | Specific token addresses to migrate. Default: all non-zero balances.             |
| `minBalanceUsd`     | `number`  | No       | Skip token balances below this USD value (dust filter). Default: 0.01.           |
| `dryRun`            | `boolean` | No       | Preview planned operations with gas estimates without executing. Default: false. |

**Returns**:

```json
{
  "status": "success",
  "sourceWallet": "0x1234...",
  "destinationWallet": "0x5678...",
  "chain": "base",
  "operations": [
    {
      "type": "erc20_transfer",
      "token": { "symbol": "USDC", "address": "0xA0b8..." },
      "amount": "2500.000000",
      "amountUsd": 2500.0,
      "txHash": "0xTX1...",
      "status": "success"
    },
    {
      "type": "erc20_transfer",
      "token": { "symbol": "WETH", "address": "0xC02a..." },
      "amount": "1.200000000000000000",
      "amountUsd": 3894.8,
      "txHash": "0xTX2...",
      "status": "success"
    },
    {
      "type": "nft_transfer",
      "contract": "NonfungiblePositionManager",
      "tokenId": "456790",
      "txHash": "0xTX3...",
      "status": "success"
    },
    {
      "type": "native_transfer",
      "amount": "0.490000000000000000",
      "amountUsd": 1590.83,
      "txHash": "0xTX4...",
      "status": "success"
    }
  ],
  "summary": {
    "tokensTransferred": 2,
    "nftsTransferred": 1,
    "nativeTransferred": true,
    "totalValueMigratedUsd": 8485.63,
    "dustSkipped": 1,
    "dustSkippedUsd": 0.003,
    "gasReserveRemaining": "0.000000000000000000",
    "totalGasCostUsd": 0.12
  }
}
```

**Implementation**: Discovers assets via `get_agent_balance` (ERC-20 + native) and `get_positions_by_owner` (NFTs). Filters by `minBalanceUsd`. Executes in strict order: ERC-20 `transfer()` calls first, then ERC-721 `safeTransferFrom()` for LP NFTs, then native ETH transfer last (amount = balance - gasReserve - estimated remaining gas). Each transfer passes through the safety pipeline. Dry run returns planned operations with per-operation gas estimates.

**Risk Tier**: Elevated (1 hour Agent Proxy delay) — moves all assets, high blast radius.

**Error Cases**:

* `WALLET_NOT_FOUND`: Invalid source or destination address
* `CHAIN_NOT_SUPPORTED`: Chain not supported
* `MIGRATION_PARTIAL_FAILURE`: Some transfers failed (partial results returned with per-operation status)
* `DUST_FILTER_ALL_SKIPPED`: All balances below `minBalanceUsd` — nothing to migrate
* `INSUFFICIENT_GAS_RESERVE`: Source wallet ETH balance below `gasReserveEth`

***

#### `get_wallet_status`

Get comprehensive wallet health status: provider, balances, active session keys, pending transactions, and policy summary.

**Parameters**:

| Name    | Type     | Required | Description                                          |
| ------- | -------- | -------- | ---------------------------------------------------- |
| `chain` | `string` | No       | Check for a specific chain. Default: all configured. |

**Returns**:

```json
{
  "wallet": "0x1234...",
  "provider": "privy",
  "type": "smart_account",
  "health": "healthy",
  "balances": {
    "base": { "eth": "0.5", "usdc": "2500", "totalUsd": 4122.84 },
    "ethereum": { "eth": "0.01", "totalUsd": 32.46 }
  },
  "sessionKeys": { "active": 2, "expiringSoon": 1 },
  "pendingTxs": 0,
  "policy": {
    "template": "defi-trading",
    "spendingLimitDaily": { "limit": 100000, "used": 2500, "remaining": 97500 }
  },
  "identity": {
    "erc8004Registered": true,
    "agentId": "42",
    "tier": "Basic"
  }
}
```

***

## Safety Extension Tools

Additional safety tools for manual circuit breaker control and MCP integrity verification.

***

#### `set_circuit_breaker`

Manually trigger or reset a circuit breaker. Used by the `halt-agents` skill for emergency stops and by operators to resume after investigation.

**Parameters**:

| Name     | Type     | Required | Description                                                    |
| -------- | -------- | -------- | -------------------------------------------------------------- |
| `action` | `string` | Yes      | "trigger" (halt all operations) or "reset" (resume operations) |
| `scope`  | `string` | No       | "all" (default), "chain:", "agent:"                            |
| `reason` | `string` | No       | Reason for trigger/reset (logged for audit trail).             |

**Returns**:

```json
{
  "action": "trigger",
  "scope": "all",
  "status": "active",
  "affectedOperations": ["swaps", "lp", "approvals", "vault"],
  "reason": "Anomalous activity detected — manual halt",
  "triggeredAt": "2026-02-19T12:00:00Z",
  "toReset": "Call set_circuit_breaker with action='reset'"
}
```

***

#### `get_tool_definitions`

Return the full list of registered MCP tool definitions including names, descriptions, parameter schemas, and annotation hints. Used by the `verify-mcp-integrity` skill to detect tool poisoning, shadowing, or unexpected changes.

**Parameters**: None.

**Returns**:

```json
{
  "toolCount": 140,
  "profile": "full",
  "tools": [
    {
      "name": "get_quote",
      "description": "Get a price quote for a swap...",
      "annotations": {
        "readOnlyHint": true,
        "destructiveHint": false,
        "idempotentHint": true
      },
      "parameterCount": 7,
      "parameterHash": "sha256:abc123..."
    }
  ],
  "serverVersion": "1.0.0",
  "integrityHash": "sha256:def456...",
  "timestamp": "2026-02-19T12:00:00Z"
}
```

**Security Note**: The `integrityHash` is a SHA-256 hash of all tool definitions concatenated. Agents can compare this against a known-good baseline to detect tool poisoning attacks (MCP-Guard pattern, 96% detection accuracy).

***

## Local Testnet Tools

Tools for spinning up and managing local testnets with Uniswap V2/V3/V4 deployed, complete with LP tokens and mock liquidity that mirrors mainnet conditions. Enables agents to develop, test, and demo without real gas costs.

#### `setup_local_testnet`

Spin up a local Anvil testnet with Uniswap contracts deployed and pre-seeded liquidity. Returns connection details and contract addresses.

**Parameters**:

| Name             | Type       | Required | Description                                                                                                                      |
| ---------------- | ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `mode`           | `string`   | No       | `"fork"` (fork mainnet/testnet with real state) or `"mock"` (deploy mock contracts with synthetic liquidity). Default: `"fork"`. |
| `forkFrom`       | `string`   | No       | Chain to fork: `"ethereum"`, `"base"`, `"sepolia"`. Default: `"ethereum"`.                                                       |
| `blockNumber`    | `number`   | No       | Specific block to fork from. Default: latest.                                                                                    |
| `versions`       | `string[]` | No       | Uniswap versions to deploy/include: `["v2", "v3", "v4"]`. Default: all available on forked chain.                                |
| `seedLiquidity`  | `boolean`  | No       | Pre-seed pools with mock liquidity (fork mode: whale impersonation, mock mode: synthetic minting). Default: true.                |
| `fundedAccounts` | `number`   | No       | Number of test accounts to fund with ETH + tokens. Default: 3.                                                                   |

**Returns**:

```json
{
  "rpcUrl": "http://127.0.0.1:8545",
  "chainId": 31337,
  "mode": "fork",
  "forkedFrom": "ethereum",
  "forkedBlock": 19234567,
  "accounts": [
    {
      "address": "0xf39F...",
      "ethBalance": "10000",
      "usdcBalance": "1000000",
      "privateKey": "0xac09..."
    }
  ],
  "contracts": {
    "uniswapV2Router": "0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D",
    "uniswapV2Factory": "0x5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f",
    "uniswapV3Router": "0xE592427A0AEce92De3Edee1F18E0157C05861564",
    "uniswapV3Factory": "0x1F98431c8aD98523631AE4a59f267346ea31F984",
    "uniswapV4PoolManager": "0x...",
    "universalRouter": "0x...",
    "permit2": "0x000000000022D473030F116dDEE9F6B43aC78BA3",
    "usdc": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "weth": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
  },
  "pools": [
    {
      "pair": "WETH/USDC",
      "version": "v3",
      "fee": 500,
      "tvl": 245000000,
      "address": "0x88e6..."
    },
    {
      "pair": "WETH/USDC",
      "version": "v2",
      "reserves": { "token0": "50000", "token1": "15.38" },
      "address": "0xB4e1..."
    }
  ]
}
```

**Implementation**: In `fork` mode, runs `anvil --fork-url <rpc>` and uses whale impersonation (`cast send --unlocked`) to fund test accounts with ETH, USDC, WETH, etc. In `mock` mode, deploys `MockUniswapV2Router02`, `LocalTestToken` contracts, and synthetic V3/V4 pools with configurable liquidity depth.

***

#### `fund_test_account`

Fund a test account with tokens on the local testnet. Uses whale impersonation on forks or minting on mock deployments.

**Parameters**:

| Name      | Type       | Required | Description                                   |
| --------- | ---------- | -------- | --------------------------------------------- |
| `address` | `string`   | Yes      | Account to fund                               |
| `tokens`  | `object[]` | Yes      | Array of `{ symbol: string, amount: string }` |

**Returns**:

```json
{
  "funded": [
    { "symbol": "USDC", "amount": "100000", "txHash": "0x..." },
    { "symbol": "ETH", "amount": "100", "txHash": "0x..." }
  ]
}
```

***

#### `time_travel`

Fast-forward the local testnet's block timestamp. Essential for testing time-dependent operations (DCA cadences, LP fee accumulation, governance timelocks).

**Parameters**:

| Name         | Type     | Required | Description                                           |
| ------------ | -------- | -------- | ----------------------------------------------------- |
| `seconds`    | `number` | Yes      | Seconds to advance                                    |
| `mineBlocks` | `number` | No       | Number of blocks to mine after advancing. Default: 1. |

**Returns**:

```json
{
  "previousTimestamp": "2026-02-06T12:00:00Z",
  "newTimestamp": "2026-02-06T13:00:00Z",
  "advancedSeconds": 3600,
  "blocksMined": 1,
  "newBlockNumber": 19234568
}
```

**Implementation**: `cast rpc evm_increaseTime <seconds>` + `cast rpc evm_mine`.

***

#### `deploy_mock_pool`

Deploy a new liquidity pool on the local testnet with configurable parameters. Useful for testing agent interactions with specific pool conditions (thin liquidity, wide spreads, specific tick ranges).

**Parameters**:

| Name           | Type     | Required | Description                                                                 |
| -------------- | -------- | -------- | --------------------------------------------------------------------------- |
| `token0`       | `string` | Yes      | Token symbol or address                                                     |
| `token1`       | `string` | Yes      | Token symbol or address                                                     |
| `version`      | `string` | No       | `"v2"`, `"v3"`, `"v4"`. Default: `"v3"`.                                    |
| `fee`          | `number` | No       | Fee tier (V3/V4). Default: 3000 (0.3%).                                     |
| `initialPrice` | `number` | No       | Initial price of token1 in terms of token0. Default: current mainnet price. |
| `liquidityUsd` | `number` | No       | Initial liquidity to seed in USD terms. Default: 1000000.                   |
| `tickRange`    | `object` | No       | V3/V4 tick range: `{ lower: number, upper: number }`. Default: full range.  |

**Returns**:

```json
{
  "poolAddress": "0xNEW...",
  "version": "v3",
  "token0": { "symbol": "WETH", "address": "0xC02a..." },
  "token1": { "symbol": "USDC", "address": "0xA0b8..." },
  "fee": 3000,
  "initialPrice": 3245.67,
  "liquidity": "12345678901234567890",
  "tvlUsd": 1000000,
  "lpTokenId": "12345"
}
```

***

## Utility Tools

#### `get_supported_chains`

List all chains supported by this MCP server instance, with RPC status.

**Parameters**: None.

**Returns**:

```json
{
  "chains": [
    {
      "name": "ethereum",
      "chainId": 1,
      "rpcStatus": "connected",
      "blockNumber": 19234567,
      "nativeCurrency": "ETH",
      "explorerUrl": "https://etherscan.io",
      "uniswapVersions": ["v2", "v3", "v4"],
      "uniswapXSupported": true,
      "erc7683Supported": true
    },
    {
      "name": "base",
      "chainId": 8453,
      "rpcStatus": "connected",
      "blockNumber": 12345678,
      "nativeCurrency": "ETH",
      "explorerUrl": "https://basescan.org",
      "uniswapVersions": ["v2", "v3"],
      "uniswapXSupported": true,
      "erc7683Supported": true
    }
  ],
  "totalChains": 11
}
```

***

#### `get_agent_balance`

Get the configured agent wallet's token balances on a chain.

**Parameters**:

| Name     | Type     | Required | Description                                                                                                          |
| -------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| `chain`  | `string` | Yes      | Chain name or chain ID                                                                                               |
| `tokens` | `array`  | No       | Specific token symbols/addresses to check. Default: native currency + all allowlisted tokens with non-zero balances. |

**Returns**:

```json
{
  "wallet": "0x1234...",
  "chain": "ethereum",
  "nativeBalance": {
    "symbol": "ETH",
    "amount": "0.500000000000000000",
    "usd": 1622.84
  },
  "tokenBalances": [
    {
      "symbol": "USDC",
      "address": "0xA0b8...",
      "amount": "2500.000000",
      "usd": 2500.0
    },
    {
      "symbol": "WETH",
      "address": "0xC02a...",
      "amount": "1.200000000000000000",
      "usd": 3894.8
    }
  ],
  "totalValueUsd": 8017.64
}
```

***

#### `get_gas_price`

Get current gas prices on a chain with EIP-1559 breakdown.

**Parameters**:

| Name    | Type     | Required | Description            |
| ------- | -------- | -------- | ---------------------- |
| `chain` | `string` | Yes      | Chain name or chain ID |

**Returns**:

```json
{
  "chain": "ethereum",
  "chainId": 1,
  "baseFee": "2.5 gwei",
  "maxPriorityFee": {
    "slow": "0.5 gwei",
    "standard": "1.0 gwei",
    "fast": "2.0 gwei"
  },
  "estimatedTotalFee": {
    "slow": "3.0 gwei",
    "standard": "3.5 gwei",
    "fast": "4.5 gwei"
  },
  "estimatedSwapCost": {
    "slow": "$0.38",
    "standard": "$0.44",
    "fast": "$0.57"
  },
  "blockNumber": 19234567,
  "timestamp": "2026-02-06T12:00:00Z"
}
```

***

### `check_setup_health` — Verify Agent Setup Readiness

**Purpose**: Verify the entire agent setup chain in one call -- wallet connectivity, identity registration, policy enforcement, balance status, and tool access. Replaces the manual 10-item checklist from [shared/onboarding-workflow.md](/docs/prd-shared/onboarding-workflow.md) with an automated verification. Run this after completing onboarding or whenever troubleshooting agent issues.

**Parameters**:

```typescript
{
  // No parameters required. Uses the configured wallet and chain settings.
  chain: z.string().optional().describe(
    'Chain to check balance on. Defaults to all configured chains.'
  ),
  includeIdentity: z.boolean().optional().describe(
    'Whether to check ERC-8004 identity registration and guardian status. Default: true.'
  ),
}
```

**Returns**:

```typescript
{
  overall: 'ready' | 'degraded' | 'not_ready',
  checks: {
    wallet: {
      status: 'pass' | 'fail',
      provider: string,          // e.g., 'privy', 'local'
      address: string,           // Wallet address
      canSign: boolean,          // Successfully signed a test message
      error?: string,            // If failed, actionable error message
      fix?: string,              // Suggested fix
    },
    identity: {
      status: 'pass' | 'fail' | 'skipped',
      registered: boolean,       // ERC-8004 identity exists
      agentId?: string,          // ERC-8004 token ID
      guardianEnabled?: boolean, // Guardian protection active
      tier?: string,             // Current reputation tier
      error?: string,
      fix?: string,
    },
    policy: {
      status: 'pass' | 'fail' | 'skipped',
      tested: boolean,           // Attempted a disallowed operation
      rejected: boolean,         // The disallowed operation was correctly rejected
      error?: string,
      fix?: string,
    },
    balances: {
      status: 'pass' | 'warn' | 'fail',
      chains: Array<{
        chainId: number,
        chainName: string,
        nativeBalance: string,   // In human-readable units
        belowThreshold: boolean, // Below circuit breaker threshold
      }>,
      error?: string,
      fix?: string,
    },
    toolAccess: {
      status: 'pass' | 'info',
      availableTools: number,    // Tools accessible at current tier
      restrictedTools: number,   // Tools gated by higher tier
      tier: string,              // Effective tier for tool access
    },
  },
  summary: string,               // Human-readable one-line summary
}
```

**Example response**:

```json
{
  "overall": "degraded",
  "checks": {
    "wallet": {
      "status": "pass",
      "provider": "privy",
      "address": "0x1234...",
      "canSign": true
    },
    "identity": {
      "status": "pass",
      "registered": true,
      "agentId": "42",
      "guardianEnabled": true,
      "tier": "Basic"
    },
    "policy": { "status": "pass", "tested": true, "rejected": true },
    "balances": {
      "status": "warn",
      "chains": [
        {
          "chainId": 8453,
          "chainName": "Base",
          "nativeBalance": "0.003",
          "belowThreshold": false
        },
        {
          "chainId": 1,
          "chainName": "Ethereum",
          "nativeBalance": "0.001",
          "belowThreshold": true
        }
      ],
      "fix": "Fund Ethereum wallet with at least 0.005 ETH to prevent circuit breaker activation."
    },
    "toolAccess": {
      "status": "info",
      "availableTools": 57,
      "restrictedTools": 27,
      "tier": "Basic"
    }
  },
  "summary": "Setup is functional but Ethereum balance is below the circuit breaker threshold. Fund with 0.005+ ETH."
}
```

**Notes**:

* This is a **read-only** tool with one exception: it attempts to sign a test message (never broadcast) to verify wallet connectivity.
* Policy check creates a synthetic "disallowed" transaction request and verifies the safety middleware rejects it.
* Identity check reads from the ERC-8004 Identity Registry and IdentityGuardian contracts.
* Tool access check reads the configured ERC-8004 reputation tier and compares against the tool access matrix from [09-safety.md](/docs/gotts-safe-mcp-server/mcp-server/09-safety.md).

***

## Deployment and Setup Tools

#### `provision_wallet`

Programmatically create a wallet via the configured wallet provider. Enables Claude, OpenClaw, or any MCP-compatible agent to autonomously set up a wallet without the operator visiting a provider dashboard -- given the operator has already configured the provider's API credentials (e.g., `PRIVY_APP_ID` and `PRIVY_APP_SECRET`).

**This is a write operation restricted to `admin:wallet` scope.**

**Parameters**:

| Name             | Type     | Required | Description                                                                                                                            |
| ---------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `provider`       | `string` | No       | Wallet provider: `"privy"` (default). Must match the configured provider credentials in the environment.                               |
| `chainType`      | `string` | No       | Chain type for the wallet: `"ethereum"` (default), `"solana"`. EVM wallets work across all EVM chains.                                 |
| `policyTemplate` | `string` | No       | Apply a preset wallet policy after creation: `"vault-participant"`, `"vault-manager"`, `"defi-trading"`, `"read-only"`. Default: none. |

**Returns**:

```json
{
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "walletId": "wlt_abc123xyz",
  "provider": "privy",
  "chainType": "ethereum",
  "policyApplied": "vault-participant",
  "policyDetails": {
    "allowedContracts": 4,
    "transferLimitPerTx": "1000 USDC",
    "transferLimitPerDay": "5000 USDC",
    "chainRestrictions": ["base"]
  },
  "nextSteps": [
    "Fund wallet with gas: send 0.005 ETH to 0x1234... on Base",
    "Register ERC-8004 identity: call register_agent tool",
    "Verify setup: call check_setup_health tool"
  ]
}
```

**On failure**:

```json
{
  "error": "PROVIDER_NOT_CONFIGURED",
  "message": "Privy credentials not found. Set PRIVY_APP_ID and PRIVY_APP_SECRET in environment.",
  "suggestedAction": "Configure Privy credentials: create an app at console.privy.io, then set PRIVY_APP_ID and PRIVY_APP_SECRET."
}
```

**Implementation**:

* For Privy: calls `privy.wallets().create({ chainType })` via `@privy-io/node` SDK
* Policy application uses the Privy policy engine
* The wallet ID is persisted to Gotts Safe's config so subsequent tool calls use the new wallet
* Idempotent: if a wallet already exists for the configured provider, returns the existing wallet instead of creating a new one

**Security**:

* Requires `admin:wallet` OAuth scope (or bearer token with admin access)
* Rate limited: maximum 5 wallet creations per hour
* Wallet creation is logged with full audit trail (provider, address, policy, timestamp)
* Private keys never leave the provider's TEE -- only the wallet address and ID are returned

***

## Tool Count Summary

| Category                  | Tools   | Write Operations | PRD File                                                                 |
| ------------------------- | ------- | ---------------- | ------------------------------------------------------------------------ |
| Data and Analytics        | 9       | 0                | [03](/docs/gotts-safe-mcp-server/mcp-server/03-tools-data.md)            |
| Historical Data           | 5       | 0                | [03](/docs/gotts-safe-mcp-server/mcp-server/03-tools-data.md)            |
| Token Directory           | 4       | 0                | [03](/docs/gotts-safe-mcp-server/mcp-server/03-tools-data.md)            |
| Portfolio and P\&L        | 10      | 0                | [03b](/docs/gotts-safe-mcp-server/mcp-server/03b-tools-portfolio-pnl.md) |
| Trading                   | 5       | 3                | [04](/docs/gotts-safe-mcp-server/mcp-server/04-tools-trading.md)         |
| Approval and Permit       | 4       | 2                | [04](/docs/gotts-safe-mcp-server/mcp-server/04-tools-trading.md)         |
| Liquidity                 | 10      | 10               | [05](/docs/gotts-safe-mcp-server/mcp-server/05-tools-liquidity.md)       |
| LP Optimization           | 3       | 0                | [05](/docs/gotts-safe-mcp-server/mcp-server/05-tools-liquidity.md)       |
| Streaming (SSE/WS)        | 5       | 0                | [06](/docs/gotts-safe-mcp-server/mcp-server/06-tools-realtime.md)        |
| Protocol Fees             | 7       | 1                | [06](/docs/gotts-safe-mcp-server/mcp-server/06-tools-realtime.md)        |
| Order Flow Intelligence   | 3       | 0                | [07](/docs/gotts-safe-mcp-server/mcp-server/07-tools-advanced.md)        |
| CCA and Token Launch      | 9       | 5                | [07](/docs/gotts-safe-mcp-server/mcp-server/07-tools-advanced.md)        |
| Intelligence              | 13      | 1                | [07](/docs/gotts-safe-mcp-server/mcp-server/07-tools-advanced.md)        |
| External Data (x402)      | 8       | 0                | [07](/docs/gotts-safe-mcp-server/mcp-server/07-tools-advanced.md)        |
| DeFi Context (free APIs)  | 2       | 0                | [07](/docs/gotts-safe-mcp-server/mcp-server/07-tools-advanced.md)        |
| ERC-8004 (Agent Registry) | 10      | 0                | [07](/docs/gotts-safe-mcp-server/mcp-server/07-tools-advanced.md)        |
| Hook Evaluation           | 2       | 0                | [07](/docs/gotts-safe-mcp-server/mcp-server/07-tools-advanced.md)        |
| Hook Development          | 4       | 0                | [07](/docs/gotts-safe-mcp-server/mcp-server/07-tools-advanced.md)        |
| Token Security            | 1       | 0                | [07](/docs/gotts-safe-mcp-server/mcp-server/07-tools-advanced.md)        |
| Yield Discovery           | 2       | 0                | [07](/docs/gotts-safe-mcp-server/mcp-server/07-tools-advanced.md)        |
| Self-Improvement          | 6       | 2                | [07](/docs/gotts-safe-mcp-server/mcp-server/07-tools-advanced.md)        |
| Memory & Knowledge        | 4       | 1                | [07](/docs/gotts-safe-mcp-server/mcp-server/07-tools-advanced.md)        |
| Safety                    | 7       | 2                | [08](/docs/gotts-safe-mcp-server/mcp-server/08-tools-infra.md)           |
| Safety Extensions         | 2       | 1                | [08](/docs/gotts-safe-mcp-server/mcp-server/08-tools-infra.md)           |
| Session Key Management    | 3       | 2                | [08](/docs/gotts-safe-mcp-server/mcp-server/08-tools-infra.md)           |
| Wallet Management         | 4       | 3                | [08](/docs/gotts-safe-mcp-server/mcp-server/08-tools-infra.md)           |
| Deployment and Setup      | 1       | 1                | [08](/docs/gotts-safe-mcp-server/mcp-server/08-tools-infra.md)           |
| Local Testnet             | 4       | 3                | [08](/docs/gotts-safe-mcp-server/mcp-server/08-tools-infra.md)           |
| Utility                   | 3       | 0                | [08](/docs/gotts-safe-mcp-server/mcp-server/08-tools-infra.md)           |
| **Total**                 | **150** | **37**           |                                                                          |

All 37 write operations pass through the full safety middleware pipeline. The intelligence tools include 1 write operation (`submit_user_operation`). The safety tools include 2 write operations (`audit_approvals` with revoke, `batch_revoke_approvals`). Session key tools include 2 write operations (`provision_session_key`, `revoke_session_keys`). Wallet management includes 3 write operations (`configure_wallet_policy`, `fund_wallet`, `migrate_wallet`). Liquidity tools include 10 write operations (9 existing + `harvest_rewards`). The x402 external data tools (3 CoinGecko + 5 Elsa) make outbound micropayments but are read-only from the protocol perspective. The DeFi Context tools (DefiLlama, Hyperliquid) use free public APIs with no authentication. The `check_setup_health` tool is read-only (signs a test message that is never broadcast). The `provision_wallet` tool is restricted to `admin:wallet` scope and rate-limited to 5 creations/hour. The vault package (`packages/vault/`) adds 21 additional tools via its own MCP server, bringing the combined total to **171 tools**.

***