pactfi-mcp

MCP (Model Context Protocol) server for the PactFi AMM DEX on Algorand. Part of the UluOS agent ecosystem.

Architecture

┌──────────────┐     ┌──────────────┐     ┌──────────────────┐
│  PactFi MCP  │────▶│ UluWalletMCP │────▶│ UluBroadcastMCP  │
│  (this repo) │     │  (signing)   │     │  (submit to net) │
└──────┬───────┘     └──────────────┘     └──────────────────┘
       │
       ├── PactFi REST API (api.pact.fi) ── pool discovery & metadata
       └── Algorand algod (algonode.cloud) ── on-chain state & tx params

No PactFi SDK dependency — pools are queried via the PactFi REST API, quotes are computed locally using constant-product AMM math, and transactions are built directly with algosdk.

Tools

Tool	Description
get_pools	List PactFi pools with optional filters (symbol, verified, pool type)
get_pool	Get detailed pool info by app ID (on-chain reserves + API metadata)
get_quote	Compute swap quote with expected output, fee, price impact, and slippage
swap_txn	Build unsigned swap transaction group
add_liquidity_txn	Build unsigned add-liquidity transaction group
remove_liquidity_txn	Build unsigned remove-liquidity transaction group

Tool Details

get_pools

List PactFi liquidity pools. Supports filtering by token symbol, verification status, pool type (CONST or STABLE), and result limit.

get_pool

Fetch on-chain pool state (reserves A/B, LP supply, fee configuration) merged with API metadata (token names, prices, TVL, APR).

get_quote

Simulate a swap without building transactions. Provide fromToken/toToken symbols and an amount. Optionally specify poolAppId to target a specific pool, or let it auto-discover the highest-TVL pool for the pair.

swap_txn

Build a 2-transaction atomic group:

1. Deposit (payment or asset transfer) to pool escrow
2. Application call with SWAP + minimum received

add_liquidity_txn

Build a 3-transaction atomic group:

1. Deposit primary asset to pool escrow
2. Deposit secondary asset to pool escrow
3. Application call with ADDLIQ + minimum LP tokens

remove_liquidity_txn

Build a 2-transaction atomic group:

1. Deposit LP tokens to pool escrow
2. Application call with REMLIQ + minimum primary + minimum secondary

Agent Flow Example

Agent: get_quote(fromToken="ALGO", toToken="USDC", amount="100")
  → { expectedOutput: "8.52", minimumReceived: "8.47", poolAppId: 1073557308, ... }

Agent: swap_txn(fromToken="ALGO", toToken="USDC", amount="100", sender="ABC...")
  → { transactions: ["base64...", "base64..."], details: { ... } }

Agent: UluWalletMCP.sign_transactions(signerId="my-signer", transactions=["base64..."])
  → { signedTransactions: ["base64..."] }

Agent: UluBroadcastMCP.broadcast_transactions(network="algorand-mainnet", txns=["base64..."])
  → { txIds: ["TXID..."] }

Setup

npm install

Usage

node index.js

Adding to a Client

{
  "mcpServers": {
    "pactfi-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/pactfi-mcp/index.js"]
    }
  }
}

Data Sources

• PactFi REST API (api.pact.fi): pool listing, token metadata, TVL, volume, APR
• Algorand algod (mainnet-api.algonode.cloud): on-chain pool state, transaction parameters

Supported Pool Types

• Constant Product (CONST): Standard x·y=k AMM pools — fully supported for quotes and transactions
• NFT Constant Product: Same AMM math as constant product — fully supported
• Stableswap (STABLE): Curve-style stable pools — get_quote returns an approximate result (with warning); swap_txn rejects stableswap pools since the constant-product math cannot produce correct minimum-received values for on-chain execution

Known Limitations

• Stableswap transactions: Building swap/liquidity transactions for stableswap pools is not supported. The on-chain contract uses the StableSwap (Curve) invariant which requires different math than constant-product. get_quote provides an approximation with a warning.
• Pool discovery: The PactFi API is used for token metadata (symbols, decimals, prices). For specific pools, use the appId parameter directly.

License

MIT