# vishwa-ondo-mcp

An MCP server that puts the Vishwa exchange API in reach of any MCP-capable agent
(Claude, ChatGPT, Copilot…). It wraps the USDC→USDY flow on Solana — quote,
prepare, submit, status — so an agent can price and draft a real subscription by
tool call instead of a bespoke integration.

It is a thin wrapper by design:

- **Never signs, never holds funds.** `prepare_swap` returns an *unsigned*
  transaction; the signature happens in the user's own wallet.
- **Eligibility is not implied.** `prepare_swap` requires an explicit
  acknowledgement that the beneficial owner is a non-US, non-restricted person
  eligible to hold USDY (Reg S). The API enforces this server-side and refuses to
  build a transaction without it; geo restrictions apply on submit.
- **No credentials in this repo.** The API key and agent ID come from the
  environment.

## Tools

| Tool | What it does |
|---|---|
| `get_quote` | Live USDC→USDY price via Jupiter routing: estimated out, minimum at slippage, price impact, route |
| `prepare_swap` | Builds an unsigned Solana transaction (requires `eligibilityAck: true`) |
| `submit_signed` | Broadcasts a wallet-signed transaction, returns the signature |
| `get_status` | Reads on-chain status: pending / confirmed / finalized / failed |

## Requirements

An instance of the `exchange` service from
[`vishwanetwork/agent-api`](https://github.com/vishwanetwork/agent-api)
(`apps/exchange`), plus an API key and agent ID issued by its auth service.

## Run

```bash
npm install
EXCHANGE_BASE_URL=http://localhost:36002 \
VETA_APIKEY=<your key> \
VETA_AGENTID=<your agent id> \
node server.js
```

Smoke test (lists the tools and fetches a live quote):

```bash
node test-client.js
```

## Add to Claude Code

```bash
claude mcp add vishwa-ondo \
  -e EXCHANGE_BASE_URL=http://localhost:36002 \
  -e VETA_APIKEY=<your key> \
  -e VETA_AGENTID=<your agent id> \
  -- node /absolute/path/to/server.js
```

Then just ask: *"quote 1000 USDC into USDY"*.

## Environment

| Variable | Default | Notes |
|---|---|---|
| `EXCHANGE_BASE_URL` | `http://localhost:36002` | Where the exchange service is reachable |
| `VETA_APIKEY` | — | Required. Sent as the `VETA-APIKEY` header |
| `VETA_AGENTID` | — | Required. Must match the key's agent, or auth fails |