# Corvo Edge, Base MCP custom plugin

Corvo Edge is a self-custody trading terminal on Base. This plugin teaches a Base MCP
agent to use Corvo as its safety oracle and market brain, and, with a key, to prepare
swaps the user signs in their own wallet. Corvo never holds keys and cannot execute
anything on anyone's behalf.

## STOP, onboarding gate

Before any call here, complete Base MCP onboarding: run `get_wallets` and confirm a
wallet is connected. Every prepared transaction below is signed by that wallet through
`send_calls`, never by Corvo.

## Read endpoints, no key, GET only

Base URL: `https://app.corvoedge.xyz`

- `GET /api/public/token/safety?address=0x…`
  Honeypot, buy and sell tax, holder count, open source, tradeability. Treat
  `tradeability.can_sell: false` as a stop, not a warning.
- `GET /api/public/edge-tokens`
  The curated tradeable token set with addresses, decimals and chains.
- `GET /api/public/chains`
  Supported chains and their ids.
- `GET /api/public/prices`
  Live prices for the listed set.
- `GET /api/public/pulse`
  Market pulse, movers and recent launches.

Call safety BEFORE preparing any trade for a token the user did not explicitly verify.

## Prepare endpoint, key required

Free key at `https://app.corvoedge.xyz` via /keys. Pass it as `Authorization: Bearer <key>`.

- `GET /api/swap/route?tokenIn=0x…&tokenOut=0x…&amountIn=<baseUnits>` (no key)
  Returns `data.routeSummary` with `amountOut` and `gas`.
- `POST /api/swap/build` with `{ routeSummary, sender, slippageTolerance }` (key)
  Returns `data.routerAddress` and `data.data`, the exact router calldata for the
  sender. Where a client cannot POST, use Corvo's MCP server at
  `https://app.corvoedge.xyz/mcp` (tool `edge_swap_prepare`), which wraps both steps
  and returns a ready `send_calls` envelope.

## send_calls mapping

The prepare response maps to one call:

```json
{
  "chainId": 8453,
  "calls": [
    { "to": "<routerAddress>", "value": "<amountIn as hex when tokenIn is ETH, else 0x0>", "data": "<data>" }
  ]
}
```

For a token-in swap the wallet may first need a one-time ERC-20 approval to the
router, sent as its own call before the swap call.

Responses may include `simulated: { ok, status, gas_used }`, an eth_simulateV1
preview of the exact calldata. A `revert` preview means do not send.

## Rules

- Never skip the safety read on an unlisted token.
- Never modify returned calldata. Sign it exactly or drop it.
- Amounts are base units. USDC has 6 decimals, most tokens 18, B20 stocks 8.
- A 4xx with a reason is the API working. Show the reason to the user.