SaturnSwap Agent Skills

Agent skill pack for trading and managing liquidity on SaturnSwap 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

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

Check platform stats

node skills/saturnswap-analytics/scripts/platform-stats.js

Find a pool

node skills/saturnswap-pools/scripts/list-pools.js --ticker MNT

Preview a swap

node skills/saturnswap-market-swap/scripts/preview-swap.js --pool <pool-uuid> --amount 10 --side buy

Place a limit order

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)

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