# santyvv-data-mcp

**Market and on-chain data for AI agents.** A local (stdio) bridge to the
`santyvv-data` remote MCP server: crypto prices from several venues, token
facts, OHLC candles, market overview, DeFi TVL and wallet balances.

Eight tools, no API keys and no accounts. Two are free; the other six are paid
**per call in USDC on Base** through the [x402](https://x402.org) protocol, so
you pay for what you use and nothing else.

## Install

```bash
npx -y santyvv-data-mcp
```

You normally don't run it by hand: your MCP client starts it. Add this to your
client's config (Claude Desktop, Cursor, VS Code, Cline…):

```json
{
	"mcpServers": {
		"santyvv-data": {
			"command": "npx",
			"args": ["-y", "santyvv-data-mcp"]
		}
	}
}
```

Without any configuration the two **free** tools work right away:

| Tool             | What it gives you                                             |
| ---------------- | ------------------------------------------------------------- |
| `catalogo`       | everything for sale, its price and its parameters              |
| `estado_fuentes` | live status of every upstream source (so you know before paying) |

## Paying for the paid tools (optional)

To let the bridge pay the six paid tools automatically, give it a wallet with
USDC on Base (the bridge signs the exact amount of each call; it never sends
funds anywhere else):

```json
{
	"mcpServers": {
		"santyvv-data": {
			"command": "npx",
			"args": ["-y", "santyvv-data-mcp"],
			"env": {
				"X402_PRIVATE_KEY": "0x…",
				"X402_MAX_PRICE_USDC": "0.05"
			}
		}
	}
}
```

| Variable               | Default                        | What it does                                          |
| ---------------------- | ------------------------------ | ----------------------------------------------------- |
| `X402_PRIVATE_KEY`     | *(none)*                       | wallet that pays each call (USDC on Base)             |
| `X402_MAX_PRICE_USDC`  | `0.05`                         | refuses to pay anything above this price per call      |
| `SANTYVV_MCP_URL`      | `https://mcp.santyvv.com/mcp`  | the remote server to bridge to                         |

Paid tools, with their price per call: `precio` ($0.02), `ficha_token`
($0.03), `velas` ($0.01), `mercado` ($0.03), `tvl_protocolo` ($0.01), `saldo`
($0.03).

## Notes

- **The key stays local.** It is read from your environment, used to sign one
  payment per call and never sent anywhere else. Use a dedicated wallet with a
  small balance.
- **This package does not reimplement anything.** It asks the remote server for
  its tool list and forwards calls, so the tools, their prices and the data are
  always the ones actually served.
- **No accounts, no tracking.** No sign-up, no API keys, no cookies.
- Privacy policy: <https://mcp.santyvv.com/privacy> · HTTP API with the same
  data: <https://x402.santyvv.com/api> · Registered as `com.santyvv/tienda` in
  the official MCP Registry.

## Develop

```bash
npm install
npm run build     # bundles src/index.ts into dist/index.mjs
npm run probar    # starts the bridge over stdio and calls a free tool
npm run probar:publicado   # installs the published package from npm and runs it
```

This repository is the source of the package published to npm. The same engine also serves the
HTTP API (40 routes, same data, same per-call pricing) and is registered as `com.santyvv/tienda` in
the official MCP Registry.

MIT.