Minswap Agent

A specialized Cardano DeFi AI agent powered by Minswap's aggregator API. This agent provides comprehensive DeFi functionality including real-time ADA pricing, wallet analysis, token discovery, swap route optimization, and transaction building across Cardano's leading DEX protocols.

🌟 Features

🤖 Complete AI Agent Setup - Pre-configured agent with OpenAPI specification for Minswap integration
💰 Real-time ADA Pricing - Get current ADA prices in 40+ currencies with 24-hour change data
👛 Wallet Analysis - Comprehensive Cardano wallet balance and token analysis
🔍 Token Discovery - Search and filter Cardano native tokens with verification status
📊 Swap Optimization - Find optimal swap routes across multiple DEX protocols:
- MinswapV2
- SundaeSwap
- WingRiders
- MuesliSwap
- VyFinance
📋 Order Management - Track pending swap orders across all supported protocols
🔗 Transaction Building - Create unsigned Cardano transactions ready for wallet signing
⚡ Next.js 15 with App Router and TypeScript
🎨 Modern Development Stack - Tailwind CSS, ESLint, TypeScript
🚀 One-Command Development - Integrated with make-agent for seamless development
📋 Production Ready - Built-in deployment scripts and Vercel integration

🚀 Quick Start

Prerequisites

Node.js 18+ and pnpm (or npm)
A Bitte wallet account
Git

1. Clone and Setup

git clone https://github.com/BitteProtocol/minswap-agent.git
cd minswap-agent
pnpm install

2. Environment Configuration

Create a .env.local file:

# Required: Get your API key from https://key.bitte.ai
BITTE_API_KEY='your-api-key'

# Required: Your account ID (can be any identifier)
ACCOUNT_ID='your-account-id'

# Optional: For local development
NEXT_PUBLIC_HOST='localhost'
PORT=3000

3. Start Development

pnpm run dev

This command will:

Start your Next.js application on http://localhost:3000
Launch make-agent development mode
Prompt you to sign a message in your Bitte wallet to authenticate
Open your agent in the Bitte playground for testing
Enable hot reload for seamless development

4. Build for Production

# Build without deployment
pnpm run build

# Build and deploy to production
pnpm run build:deploy

🔧 Available Tools

The Minswap agent includes comprehensive DeFi tools for Cardano ecosystem interaction:

1. ADA Price Information (`/api/tools/get-ada-price`)

Purpose: Get real-time ADA prices in 40+ currencies
Parameters: currency (optional, defaults to USD)
Features: 24-hour price change tracking
Use Case: Portfolio valuation and price monitoring

2. Wallet Balance Analysis (`/api/tools/get-wallet-balance`)

Purpose: Comprehensive wallet balance and token analysis
Parameters: address (Cardano wallet), amount_in_decimal (optional)
Features: ADA balance, token holdings, minimum lovelace requirements
Use Case: Portfolio analysis and asset management

3. Token Search & Discovery (`/api/tools/search-tokens`)

Purpose: Search and filter Cardano native tokens
Parameters: query, only_verified, assets, search_after
Features: Verification status, pricing data, project information
Methods: Both GET (query params) and POST (JSON body)
Use Case: Token research and discovery

4. Swap Route Optimization (`/api/tools/get-swap-estimate`)

Purpose: Find optimal swap routes across multiple DEXs
Parameters: amount, token_in, token_out, slippage, etc.
Features: Multi-hop routing, protocol exclusion, price impact analysis
Methods: Both GET (query params) and POST (JSON body)
Integration: Aggregates liquidity across 5 major DEX protocols

5. Pending Order Management (`/api/tools/get-pending-orders`)

Purpose: Track pending swap orders across all protocols
Parameters: owner_address, amount_in_decimal
Features: Cross-protocol order tracking, detailed order information
Use Case: Order monitoring and management

6. Transaction Building (`/api/tools/build-swap-tx`)

Purpose: Build unsigned Cardano transactions for swaps
Parameters: sender, min_amount_out, estimate, amount_in_decimal
Features: CBOR transaction output ready for wallet signing
Integration: Uses estimate data to construct valid transactions

7. User Information (`/api/tools/get-user`)

Purpose: Get user account and EVM address information
Context-Aware: Automatically populated by Bitte's context system
Use Case: User identification and multi-chain support

8. Blockchain Information (`/api/tools/get-blockchains`)

Purpose: Get supported blockchain information
Implementation: Returns available blockchain networks
Use Case: Multi-chain awareness and network selection

🤖 Agent Configuration

The agent is configured through AI plugin manifests at /api/ai-plugin/route.ts and /app/ai-plugin/route.ts. These endpoints return OpenAPI specifications that define:

Agent Metadata

{
  name: "Minswap Agent",
  description: "A specialized Cardano DeFi assistant powered by Minswap's aggregator API...",
  instructions: "You are a Cardano DeFi specialist focused on Minswap integration...",
  tools: [
    { type: "get-ada-price" },
    { type: "get-wallet-balance" },
    { type: "search-tokens" },
    { type: "search-tokens-query" },
    { type: "get-swap-estimate" },
    { type: "get-swap-estimate-query" },
    { type: "get-pending-orders" },
    { type: "build-swap-tx" },
    { type: "get-user" },
    { type: "get-blockchains" },
    { type: "generate-cardano-tx" }
  ],
  categories: ["DeFi", "DAO", "Social"],
  chainIds: [1, 8453]
}

Important Configuration Notes

Dual Method Support: Many endpoints support both GET (query parameters) and POST (JSON body) for AI agent flexibility
Token Symbol Mapping: Automatic conversion of common symbols (MIN, DJED, SHEN, ADA) to proper token IDs
Workflow Integration: Designed for estimate → build-tx → generate-cardano-tx workflow
Error Handling: Comprehensive validation and error reporting
Deployment URL: Automatically detected from Vercel or environment variables

💡 Usage Examples

Swap Workflow

1. User: "I want to swap 10 ADA for MIN tokens"
2. Agent searches for MIN token using searchTokensQuery
3. Agent gets swap estimate using getSwapEstimateQuery
4. Agent asks user for wallet address
5. Agent builds transaction using buildSwapTx
6. Agent returns unsigned transaction CBOR for wallet signing

Price Monitoring

1. User: "What's the current ADA price in EUR?"
2. Agent calls getAdaPrice with currency=eur
3. Agent returns current price and 24h change

Portfolio Analysis

1. User provides Cardano wallet address
2. Agent calls getWalletBalance
3. Agent returns comprehensive portfolio breakdown

📝 Environment Variables

Variable	Required	Description	Example
`BITTE_API_KEY`	✅	Your Bitte API key from key.bitte.ai	`bitte_key_...`
`ACCOUNT_ID`	✅	Your account identifier	`your-account-id`
`NEXT_PUBLIC_HOST`	❌	Development host	`localhost`
`PORT`	❌	Development port	`3000`
`NEXT_PUBLIC_BASE_URL`	❌	Base URL for assets	`https://yourdomain.com`

🛠️ Development Scripts

# Development with hot reload and make-agent
pnpm run dev

# Next.js development only (without make-agent)
pnpm run dev:agent

# Production build (local)
pnpm run build

# Build and deploy to production
pnpm run build:deploy

# Linting
pnpm run lint

🚀 Deployment

Automatic Deployment (Recommended)

Push your code to GitHub
Connect your repository to Vercel
Add environment variables in Vercel dashboard:
- BITTE_API_KEY
- ACCOUNT_ID
Deploy! The build process automatically runs make-agent deploy

Manual Deployment

# Build and deploy manually
pnpm run build:deploy

🔨 Creating Custom Tools

To add your own tools to the agent:

1. Create the Tool Endpoint

// src/app/api/tools/my-tool/route.ts
import { NextResponse } from "next/server";

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const param = searchParams.get("param");

  // Your tool logic here

  return NextResponse.json({ result: "success" });
}

2. Add to Agent Manifest

Update both /api/ai-plugin/route.ts and /app/ai-plugin/route.ts:

// Add to tools array
tools: [
  // ... existing tools
  { type: "my-tool" }
],

// Add to paths object
paths: {
  // ... existing paths
  "/api/tools/my-tool": {
    get: {
      summary: "My custom tool",
      description: "Description of what your tool does",
      operationId: "my-tool",
      parameters: [
        {
          name: "param",
          in: "query",
          required: true,
          schema: { type: "string" }
        }
      ],
      responses: {
        "200": {
          description: "Successful response",
          content: {
            "application/json": {
              schema: {
                type: "object",
                properties: {
                  result: { type: "string" }
                }
              }
            }
          }
        }
      }
    }
  }
}

3. Update Agent Instructions

Modify the instructions field in both agent configurations to include guidance on when and how to use your new tool.

📖 Key Dependencies

@bitte-ai/agent-sdk - Core SDK for Bitte integration
make-agent - Development and deployment tooling
Next.js 15 - React framework with App Router
Minswap Aggregator API - Cardano DEX aggregation service
vercel-url - Automatic deployment URL detection

🌐 Community & Support

📚 Bitte Protocol Documentation
💬 Join our Telegram - Get help and connect with other developers
🐛 Report Issues
🔗 Next.js Documentation
📋 OpenAPI Specification
🏛️ Minswap Protocol

📋 Project Structure

minswap-agent/
├── src/app/
│   ├── api/
│   │   ├── ai-plugin/route.ts        # Agent manifest endpoint
│   │   └── tools/                    # Tool endpoints
│   │       ├── get-ada-price/
│   │       ├── get-wallet-balance/
│   │       ├── search-tokens/
│   │       ├── get-swap-estimate/
│   │       ├── get-pending-orders/
│   │       ├── build-swap-tx/
│   │       ├── get-user/
│   │       └── get-blockchains/
│   ├── ai-plugin/route.ts            # Alternative agent manifest
│   ├── config.ts                     # Environment configuration
│   ├── layout.tsx                    # Root layout
│   └── page.tsx                      # Home page
├── public/                           # Static assets
├── package.json                      # Dependencies and scripts
└── README.md                         # This file

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

📄 License

MIT License - see LICENSE file for details.

Built with ❤️ using Bitte Protocol and Minswap

Name		Name	Last commit message	Last commit date
Latest commit History 26 Commits
public		public
src/app		src/app
.gitignore		.gitignore
README.md		README.md
eslint.config.mjs		eslint.config.mjs
next.config.mjs		next.config.mjs
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json

BitteProtocol/minswap-agent

Folders and files

Latest commit

History

Repository files navigation

Minswap Agent

🌟 Features

🚀 Quick Start

Prerequisites

1. Clone and Setup

2. Environment Configuration

3. Start Development

4. Build for Production

🔧 Available Tools

1. ADA Price Information (/api/tools/get-ada-price)

2. Wallet Balance Analysis (/api/tools/get-wallet-balance)

3. Token Search & Discovery (/api/tools/search-tokens)

4. Swap Route Optimization (/api/tools/get-swap-estimate)

5. Pending Order Management (/api/tools/get-pending-orders)

6. Transaction Building (/api/tools/build-swap-tx)

7. User Information (/api/tools/get-user)

8. Blockchain Information (/api/tools/get-blockchains)