npm package: @fluxpointstudios/cardano-defi-agent-skills
Description: Agent skills for Cardano DeFi — trading, lending, prediction markets, perpetuals, and cross-chain swaps
Latest version: 6.0.0

# Cardano DeFi Agent Skills

One-stop agent skill pack for Cardano's DeFi ecosystem — trading, lending, prediction markets, perpetuals, and cross-chain swaps across 119 blockchains. Makes it trivial for AI agents with wallets to participate in all of Cardano DeFi.

## Quick Start

```bash
npm install @fluxpointstudios/cardano-defi-agent-skills
```

### Swap on SaturnSwap
```bash
node skills/saturnswap-market-swap/scripts/preview-swap.js --pool <pool-uuid> --amount 10 --side buy
```

### Best rate across all DEXes
```bash
node skills/dexhunter-swap/scripts/estimate-swap.js --token-in "" --token-out <tokenId> --amount 10000000
```

### Earn yield on lending
```bash
node skills/defi-lending/scripts/list-pools.js --sort supplyApy
```

### Trade prediction markets
```bash
node skills/bodega-markets/scripts/list-markets.js
node skills/bodega-markets/scripts/buy.js --market <id> --side Yes --amount 100 --slippage 0.05 --address addr1q...
```

### Open a leveraged position
```bash
node skills/strike-perpetuals/scripts/open-position.js --address addr1q... --asset ADA --side Long --leverage 5 --collateral 100
```

### Cross-chain swap (ADA → ETH)
```bash
node skills/saturnswap-cross-chain/scripts/get-quote.js --from ADA --to ETH --amount 500
```

### Unified portfolio
```bash
node skills/defi-portfolio/scripts/portfolio.js --address addr1q...
```

## Architecture

```
cardano-defi-agent-skills/
├── package.json
├── shared/
│   ├── saturnswap-api.md            # SaturnSwap API conventions
│   ├── signing-flow.md              # Create → Sign → Submit pattern
│   └── uex-cross-chain-api.md       # Cross-chain UEX API reference
├── scripts/
│   ├── saturnswap-client.js         # SaturnSwap DEX client
│   ├── saturnswap-signer.js         # Transaction signing (CSL/MeshJS)
│   ├── uex-client.js               # Cross-chain swap client
│   ├── dexhunter-client.js          # Multi-DEX aggregator client
│   ├── indigo-client.js              # Synthetic assets & CDPs client
│   ├── surf-client.js               # Lending/borrowing client
│   ├── bodega-client.js             # Prediction markets client
│   └── strike-client.js             # Perpetuals client
└── skills/
    ├── saturnswap-*/                # DEX trading (6 skills)
    ├── saturnswap-cross-chain/      # Cross-chain swaps (119 chains)
    ├── dexhunter-swap/              # Multi-DEX aggregated swaps
    ├── indigo-cdp/                  # Synthetic assets & CDPs
    ├── indigo-stability/            # Stability pools
    ├── indigo-staking/              # INDY staking
    ├── indigo-analytics/            # Indigo TVL, APR, governance
    ├── defi-lending/                # Lending & borrowing (Surf)
    ├── bodega-markets/              # Prediction markets
    ├── strike-perpetuals/           # Leveraged perps
    ├── defi-portfolio/              # Unified cross-protocol portfolio
    └── *-operator/                  # Signing skills (5 operators)
```

## Protocols

| Protocol | Category | Skills |
|---|---|---|
| **SaturnSwap** | DEX (CLOB + AMM) | Pools, orders, liquidity, market swap |
| **SaturnSwap UEX** | Cross-chain | 119 chains via Cosmic Router |
| **DexHunter** | Swap Aggregator | Multi-DEX routing (Minswap, WingRiders, etc.) |
| **Indigo Protocol** | Synthetic Assets | CDPs, stability pools, INDY staking, iUSD/iBTC/iETH/iSOL |
| **Surf Finance** | Lending/Borrowing | Supply (earn APY), borrow against collateral |
| **Bodega Markets** | Prediction Markets | Buy/sell Yes/No outcome shares |
| **Strike Finance** | Perpetuals | Leveraged long/short (ADA, BTC) |

## All Skills (19)

### Guidance Skills

| Skill | Description | Scripts |
|---|---|---|
| **saturnswap-pools** | Pool discovery, order book, token search | `list-pools` `get-pool` `order-book` `search-tokens` |
| **saturnswap-portfolio** | View open orders and liquidity positions | `my-orders` `my-liquidity` |
| **saturnswap-analytics** | Platform stats, top pools, API health | `platform-stats` `top-pools` `api-status` |
| **saturnswap-market-swap** | Preview and build market swap transactions | `preview-swap` `create-swap` |
| **saturnswap-limit-orders** | Preview, build, and cancel limit orders | `preview-limit` `create-limit` `create-cancel` |
| **saturnswap-liquidity** | Build add/withdraw liquidity transactions | `create-add-liquidity` `create-withdraw-liquidity` |
| **saturnswap-cross-chain** | Cross-chain swaps (119 chains) | `list-chains` `find-token` `get-quote` `create-order` |
| **dexhunter-swap** | Multi-DEX aggregated swaps | `search-tokens` `estimate-swap` `build-swap` |
| **indigo-cdp** | Synthetic asset CDPs (iUSD, iBTC, iETH, iSOL) | `my-cdps` `cdp-health` `open-cdp` `manage-cdp` `prices` |
| **indigo-stability** | Stability pools (earn from liquidations) | `pools` `my-accounts` `manage-sp` |
| **indigo-staking** | INDY token staking | `staking-info` `my-staking` `manage-staking` |
| **indigo-analytics** | Indigo TVL, APR, DEX yields, governance | `stats` `apr` `dex-yields` `governance` |
| **defi-lending** | Lending pools, supply, borrow (Surf) | `list-pools` `supply` `borrow` |
| **bodega-markets** | Prediction market trading | `list-markets` `positions` `buy` `sell` `claim` |
| **strike-perpetuals** | Leveraged long/short positions | `pool-info` `my-positions` `open-position` `close-position` `update-position` |
| **defi-portfolio** | Unified cross-protocol portfolio | `portfolio` |

### Operator Skills (signing + submission — manual confirmation required)

| Skill | Description |
|---|---|
| **saturnswap-market-swap-operator** | Sign and submit market swaps |
| **saturnswap-limit-orders-operator** | Sign and submit limit orders / cancels |
| **saturnswap-liquidity-operator** | Sign and submit liquidity transactions |
| **dexhunter-swap-operator** | Sign and submit DexHunter swaps |
| **indigo-cdp-operator** | Sign and submit Indigo CDP transactions |
| **defi-lending-operator** | Sign and submit lending transactions |
| **bodega-markets-operator** | Sign and submit prediction market transactions |
| **strike-perpetuals-operator** | Sign and submit perpetual transactions |

## Transaction Flow

Every write operation follows a 3-step pattern:

```
CREATE (API builds tx) → SIGN (local wallet) → SUBMIT (API broadcasts)
```

1. **Guidance skill** builds the unsigned transaction via protocol API
2. **Operator skill** signs locally with CSL or MeshJS, then submits
3. Private keys never leave the local machine

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `PAYMENT_SKEY_HEX` | For signing | Raw ed25519 private key hex (64 chars) |
| `PAYMENT_SKEY_CBOR` | For signing | CBOR-wrapped signing key from cardano-cli |
| `DEFI_API_URL` | No | Override gateway URL (default: `https://saturnswap.io/api/defi`) |
| `SATURNSWAP_API_URL` | No | Override SaturnSwap GraphQL endpoint |
| `STRIKE_API_PUBLIC_KEY` | For Strike trading | Ed25519 public key (64 hex chars) |
| `STRIKE_API_PRIVATE_KEY` | For Strike trading | Ed25519 private key (64 hex chars) |

## Important: Unit Conventions

| Protocol | Units |
|---|---|
| **SaturnSwap** | Display units (5 ADA, not 5000000) |
| **DexHunter** | Display units (10 = 10 ADA) |
| **Surf Finance** | Lovelace (5000000 = 5 ADA) |
| **Indigo** | Lovelace for ADA, base units for iAssets (iUSD=6, iBTC=8, iETH=18, iSOL=9 decimals) |
| **Bodega** | Shares + price in micro-units (500000 = 0.5 ADA/share) |
| **Strike v2** | Contract units (see exchangeInfo for precision) |

## Dependencies

- Node.js >= 18
- `@emurgo/cardano-serialization-lib-nodejs` — Transaction signing (CSL)
- `@meshsdk/core` — Alternative signing (MeshJS)
- `graphql-request` — GraphQL client

## License

MIT