npm package: @fluxpointstudios/saturnswap-agent-skills
Description: Agent skills for trading and managing liquidity on SaturnSwap DEX
Latest version: 1.0.0

# SaturnSwap Agent Skills

Agent skill pack for trading and managing liquidity on [SaturnSwap](https://saturnswap.io) DEX (Cardano) — plus cross-chain swaps across 119 blockchains. Makes it trivial for AI agents with wallets to swap tokens, place limit orders, provide liquidity, and bridge across chains.

## Quick Start

```bash
npm install @flux-point-studios/saturnswap-agent-skills
```

### Check platform stats
```bash
node skills/saturnswap-analytics/scripts/platform-stats.js
```

### Find a pool
```bash
node skills/saturnswap-pools/scripts/list-pools.js --ticker MNT
```

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

### Place a limit order
```bash
node skills/saturnswap-limit-orders/scripts/create-limit.js \
  --address addr1q... --pool <pool-uuid> \
  --policy "" --asset "" --sell 50 --buy 1000000
```

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

## Architecture

```
saturnswap-agent-skills/
├── package.json
├── shared/
│   ├── saturnswap-api.md            # API conventions, display units, endpoint
│   ├── signing-flow.md              # Create → Sign → Submit pattern
│   └── uex-cross-chain-api.md       # Cross-chain UEX API reference
├── scripts/
│   ├── saturnswap-client.js         # Core GraphQL client (17 functions)
│   ├── saturnswap-signer.js         # CSL/MeshJS signing helper
│   └── uex-client.js               # Cross-chain UEX client
└── skills/
    ├── saturnswap-pools/            # Pool discovery & order book
    ├── saturnswap-portfolio/        # View positions & open orders
    ├── saturnswap-analytics/        # TVL, volume, platform stats
    ├── saturnswap-market-swap/      # Market buy/sell guidance
    ├── saturnswap-market-swap-operator/   # Execute market swaps
    ├── saturnswap-limit-orders/     # Place/cancel limit orders
    ├── saturnswap-limit-orders-operator/  # Execute limit orders
    ├── saturnswap-liquidity/        # Add/withdraw liquidity
    ├── saturnswap-liquidity-operator/     # Execute liquidity ops
    └── saturnswap-cross-chain/      # Cross-chain swaps (119 chains)
```

## Skills

### Guidance Skills (read-only + tx building)

| 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 via Cosmic Router (119 chains) | `list-chains` `find-token` `get-quote` `create-order` |

### 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 |

## 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 GraphQL
2. **Operator skill** signs locally with CSL or MeshJS, then submits
3. Private keys never leave the local machine

See [shared/signing-flow.md](shared/signing-flow.md) for detailed examples.

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `SATURNSWAP_API_URL` | No | Override API endpoint (default: `https://api.saturnswap.io/v1/graphql/`) |
| `PAYMENT_SKEY_HEX` | For signing | Raw ed25519 private key hex (64 chars) |
| `PAYMENT_SKEY_CBOR` | For signing | CBOR-wrapped signing key from cardano-cli |

Only one signing key variable is needed. `PAYMENT_SKEY_HEX` uses CSL directly; `PAYMENT_SKEY_CBOR` uses MeshJS.

## Important: Display Units

**ALL amounts use display units, NOT base units (lovelace).**

| You want | You pass | NOT |
|---|---|---|
| 5 ADA | `tokenAmountSell: 5` | `tokenAmountSell: 5000000` |
| 100 MNT | `tokenAmountSell: 100` | `tokenAmountSell: 100000000` |

The backend multiplies by `10^decimals` internally. Passing base units will hit the 25K ADA ceiling and silently return empty results.

## Dependencies

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

## License

MIT