---
name: starkshield
description: "Private AI agent wallet on Starknet. Manages DeFi operations (swaps, transfers, balances) with ZK privacy via Tongo SDK. Auto-generates self-custodial wallets for AI agents. Uses StarkZap SDK for wallet lifecycle and AVNU for DEX aggregation. Discoverable via MCP server and REST API. Use when an agent needs to hold funds, swap tokens, or shield positions on Starknet."
license: MIT
metadata:
  author: starkshield
  version: "1.0.0"
  api_base: "https://starkshield-jade.vercel.app"
compatibility: "Node.js 20+, Starknet Sepolia"
keywords:
  - starknet
  - wallet
  - privacy
  - defi
  - swap
  - shield
  - agent-wallet
  - mev-protection
  - starkzap
  - avnu
  - tongo
  - mcp
allowed-tools:
  - Bash
  - Read
  - Write
---

# Starkshield

Privacy-first AI agent wallet on Starknet. Any AI agent can hold funds, swap tokens, and shield positions from front-runners — all via MCP tools or REST API.

## Skill Files

| File | Purpose |
|------|---------|
| [SKILL.md](https://starkshield-jade.vercel.app/skill.md) | This file — capability discovery |
| [README.md](https://github.com/ayushsrivastava55/starkshield) | Full documentation + StarkZap SDK usage |
| `references/privacy-pool.md` | How the Tongo ZK privacy layer works |
| `references/mcp-integration.md` | MCP server setup for Claude Desktop |

## Setup

The wallet auto-generates its own Stark keypair. No private keys needed.

```bash
git clone https://github.com/ayushsrivastava55/starkshield.git
cd starkshield
npm install --legacy-peer-deps
npm run mcp:build
```

### Claude Desktop MCP Config

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "starkshield": {
      "command": "node",
      "args": ["/path/to/starkshield/dist/mcp-server.cjs"],
      "env": {
        "STARKNET_RPC_URL": "https://starknet-sepolia.g.alchemy.com/starknet/version/rpc/v0_10/YOUR_KEY"
      }
    }
  }
}
```

Restart Claude Desktop. You'll see 8 `starkshield_*` tools.

## Everything You Can Do

| Priority | Action | MCP Tool | REST Endpoint |
|----------|--------|----------|---------------|
| 🔴 Core | Check balances | `starkshield_check_balance` | `GET /api/balances` |
| 🔴 Core | Get wallet info | — | `GET /api/wallet` |
| 🟠 Important | Swap tokens | `starkshield_swap_tokens` | `POST /api/command` |
| 🟠 Important | Transfer tokens | `starkshield_transfer` | `POST /api/command` |
| 🟡 Privacy | Shield assets | `starkshield_shield_assets` | `POST /api/command` |
| 🟡 Privacy | Unshield assets | `starkshield_unshield_assets` | `POST /api/command` |
| 🟢 Status | Privacy score | `starkshield_get_privacy_status` | `GET /api/privacy/status` |
| 🟢 Status | Get viewing key | `starkshield_get_viewing_key` | `GET /api/privacy/viewing-key` |
| 🔵 Audit | Reveal with key | `starkshield_reveal_with_key` | `POST /api/privacy/reveal` |
| 🔵 Audit | Action history | — | `GET /api/actions` |
| 🔵 Audit | Active strategies | — | `GET /api/strategies` |

## MCP Tools

### starkshield_check_balance

Check the balance of ETH, STRK, or ALL tokens in the agent wallet.

```json
{ "token": "ALL" }
```

**Fields:**
- `token` (required) — `"ETH"`, `"STRK"`, or `"ALL"`

**Response:**
```json
{
  "publicBalances": { "ETH": "0.05", "STRK": "142.3" },
  "shieldedBalances": { "STRK": "50.0" },
  "walletAddress": "0x07a3...4f2e"
}
```

### starkshield_swap_tokens

Swap tokens via AVNU aggregator. Routes through Ekubo, JediSwap for best price. Real on-chain execution on Sepolia.

```json
{ "sell_token": "ETH", "buy_token": "STRK", "amount": "0.01" }
```

**Fields:**
- `sell_token` (required) — `"ETH"` or `"STRK"`
- `buy_token` (required) — `"ETH"` or `"STRK"`
- `amount` (required) — Amount to sell, e.g. `"0.01"`

**Response:**
```json
{
  "txHash": "0x...",
  "sold": "0.01 ETH",
  "bought": "23.5 STRK",
  "explorerUrl": "https://sepolia.starkscan.co/tx/0x..."
}
```

### starkshield_transfer

Transfer tokens to a Starknet address. Uses StarkZap `wallet.transfer()`.

```json
{ "token": "STRK", "to": "0xRECIPIENT", "amount": "10" }
```

**Fields:**
- `token` (required) — `"ETH"` or `"STRK"`
- `to` (required) — Recipient Starknet address `0x...`
- `amount` (required) — Amount to transfer

### starkshield_shield_assets

Deposit tokens into Tongo's confidential pool. Encrypted with ElGamal on the Stark curve. External observers cannot see the shielded balance.

```json
{ "token": "STRK", "amount": "10" }
```

**Fields:**
- `token` (required) — `"ETH"` or `"STRK"`
- `amount` (required) — Amount to shield

**Response:**
```json
{
  "txHash": "0x...",
  "token": "STRK",
  "amount": "10",
  "commitment": "abc123...",
  "message": "10 STRK is now shielded"
}
```

### starkshield_unshield_assets

Withdraw from the privacy pool with a ZK proof and send to a recipient.

```json
{ "token": "STRK", "amount": "5", "recipient": "0xRECIPIENT" }
```

### starkshield_get_privacy_status

Returns privacy score (0-100) and shielded balances.

```json
{}
```

**Response:**
```json
{ "privacyScore": 65, "shieldedBalances": { "STRK": "50.0" } }
```

### starkshield_get_viewing_key

Returns the viewing key for selective disclosure to auditors.

```json
{}
```

**Response:**
```json
{ "viewingKey": "e8d43a327fc7af69..." }
```

### starkshield_reveal_with_key

Reveal full privacy pool state using a viewing key. For auditing and compliance.

```json
{ "viewing_key": "e8d43a327fc7af69..." }
```

## REST API

All endpoints are at `https://starkshield-jade.vercel.app`.

### Get wallet info

```bash
curl https://starkshield-jade.vercel.app/api/wallet
```

**Response:**
```json
{
  "address": "0x07a3...4f2e",
  "publicKey": "0x5ed4ac...",
  "note": "This is the agent's own wallet. Send funds here to let the agent operate."
}
```

### Check balances

```bash
curl https://starkshield-jade.vercel.app/api/balances
```

### Send a natural language command

```bash
curl -X POST https://starkshield-jade.vercel.app/api/command \
  -H "Content-Type: application/json" \
  -d '{"message": "swap 0.01 ETH for STRK and then shield it"}'
```

**Response:**
```json
{
  "response": "I've swapped 0.01 ETH for 23.5 STRK and shielded the STRK...",
  "actions": [...]
}
```

### Privacy status

```bash
curl https://starkshield-jade.vercel.app/api/privacy/status
```

### Get viewing key

```bash
curl https://starkshield-jade.vercel.app/api/privacy/viewing-key
```

### Reveal with viewing key

```bash
curl -X POST https://starkshield-jade.vercel.app/api/privacy/reveal \
  -H "Content-Type: application/json" \
  -d '{"viewingKey": "e8d43a327fc7af69..."}'
```

### Action history

```bash
curl https://starkshield-jade.vercel.app/api/actions
```

### Active strategies

```bash
curl https://starkshield-jade.vercel.app/api/strategies
```

## How It Works

1. **Agent auto-creates its own wallet** — generates a Stark keypair via `stark.randomAddress()` + `ec.starkCurve.getStarkKey()`, deploys via StarkZap `sdk.onboard()`
2. **Owner funds the wallet** — sends Sepolia ETH/STRK to the agent's address
3. **Agent operates privately** — swaps via AVNU, shields via Tongo, tracks privacy score
4. **External agents discover capabilities** — via this SKILL.md or MCP tools
5. **Owner audits via viewing key** — selective disclosure of full activity history

## Error Handling

| Error | Cause | Fix |
|-------|-------|-----|
| `Unknown token` | Invalid symbol | Use `ETH` or `STRK` |
| `No swap routes found` | No AVNU liquidity | Try smaller amount |
| `Insufficient shielded` | Not enough in privacy pool | Check `starkshield_get_privacy_status` first |
| `Wallet not initialized` | RPC unreachable | Check `STARKNET_RPC_URL` env var |
| `fetch failed` | Agent wallet not funded | Send Sepolia tokens to the agent's address |

## SDK Stack

- **StarkZap** — `sdk.onboard()`, `wallet.execute()`, `wallet.balanceOf()`, `wallet.transfer()`, `Amount.parse()`, `fromAddress()`, `sepoliaTokens`
- **AVNU SDK v4** — `getQuotes()`, `executeSwap()` for DEX aggregation
- **Tongo SDK** — `fund()`, `withdraw()` for confidential ERC-20 payments
- **starknet.js v9** — Keypair generation, low-level contract calls
- **MCP SDK** — Model Context Protocol server (stdio transport)