# Capy Autonomous Trading MCP Server: Comprehensive Specification (llms-full.txt)

> Domain: https://capypad.fun
> Network: Robinhood Chain Mainnet (Chain ID: 4663)
> Currency: ETH (Native), USDG, TSLA, NVDA
> Package: @capy/mcp-server

---

## 1. Overview
Capy provides an autonomous on-chain trading execution layer for AI Agents via the Model Context Protocol (MCP).
Developers and autonomous bot operators can run `@capy/mcp-server` to allow AI models (such as Claude 3.5 Sonnet, Claude 3.7 Sonnet, GPT-4o, Cursor, Antigravity, and DeepSeek) to interact directly with smart contracts on Robinhood Chain Mainnet.

---

## 2. On-Chain Contracts
- CapySwapRouter: `0x548D1ffE1BD2F5E0c97589E62261320B5B092E10`
- CapyV2Factory: `0xAe332849022A8B71cc4e1A0F9c5a61172c7aE5EB`
- CapyV2Deployer: `0xf52Fd0e2a9537A2D61885f34291c3f7C89e31a5F`
- Treasury: `0x3eF368806fa91e16C2775A155a937C0Da81F0Bc2`
- WETH: `0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73`
- USDG: `0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168`
- NVDA: `0xd0601CE157Db5bdC3162BbaC2a2C8aF5320D9EEC`
- TSLA: `0x322F0929c4625eD5bAd873c95208D54E1c003b2d`

---

## 3. Tool Specifications

### Tool 1: `capy_get_agent_balance`
Returns the agent's on-chain holdings and risk budget.
Output Example:
```json
{
  "isConfigured": true,
  "address": "0xAgentWalletAddress",
  "nativeEthBalance": 0.45,
  "usdgBalance": 120.5,
  "wethBalance": 0.0,
  "riskGuardrails": {
    "maxPerTradeCapEth": 0.05,
    "dailyBudgetEth": 0.5,
    "spentLast24hEth": 0.02,
    "remainingBudgetEth": 0.48,
    "antiSpamFloorEth": 0.0005
  }
}
```

### Tool 2: `capy_get_trending_tokens`
Parameters:
- `limit` (number, optional, default: 5)
Output: List of active bonding curve tokens on Robinhood Chain with liquidity reserves, progress percentage, and pair quote asset.

### Tool 3: `capy_get_token_info`
Parameters:
- `tokenAddress` (string, required): 0x address of token
Output:
```json
{
  "address": "0x39dbed3a2bd333467115de45665cc57f813c4571",
  "name": "WOOF",
  "symbol": "WOOF",
  "decimals": 18,
  "isGraduated": true,
  "bondingProgressPct": 100,
  "explorerUrl": "https://robinhoodchain.blockscout.com/token/0x39dbed3a2bd333467115de45665cc57f813c4571"
}
```

### Tool 4: `capy_get_quote`
Parameters:
- `tokenAddress` (string, required)
- `side` (string, required): "BUY" or "SELL"
- `amount` (number, required): quote amount for BUY or token amount for SELL
- `slippagePct` (number, optional, default: 1.5)

### Tool 5: `capy_buy_token`
Parameters:
- `tokenAddress` (string, required)
- `amountEth` (number, required)
- `maxSlippagePct` (number, optional, default: 2.0)
- `dryRun` (boolean, optional, default: false)
Execution:
1. Validates spend cap and 24h budget.
2. Acquires atomic execution lock.
3. If pre-graduation: calls bonding curve `buy()`.
4. If graduated: calls `CapySwapRouter.swapExactETHForTokens()`.
5. Waits for 1 confirmation and returns transaction hash and Blockscout link.

### Tool 6: `capy_sell_token`
Parameters:
- `tokenAddress` (string, required)
- `amountTokens` (number, optional, default 0 for 100% of holdings)
- `maxSlippagePct` (number, optional, default: 2.0)
Execution:
1. Verifies token balance.
2. Automatically grants ERC-20 approval to router or bonding curve.
3. Executes swap and delivers net quote asset to the agent's wallet.

---

## 4. Setup in Cursor / Windsurf / Antigravity
Run the MCP server via stdio:
```json
{
  "mcpServers": {
    "capy": {
      "command": "node",
      "args": ["./mcp/bin/capy-mcp.js"],
      "env": {
        "CAPY_AGENT_PRIVATE_KEY": "0xYOUR_KEY",
        "ROBINHOOD_RPC_URL": "https://rpc.mainnet.chain.robinhood.com"
      }
    }
  }
}
```